About this site

See also

• Sam Hughes, “On short URLs”, https://qntm.org/urls2011
• Derek Sivers, “Short URLs: why and how”, https://sive.rs/su2022
• Gwern Branwen, “Design Graveyard: Long URLs”, https://gwern.net/design-graveyard#long-urls2023
• Clean URL

I cannot fully endorse Derek Sivers’s approach. I think regular words are preferable to single letters or initialisms. Words are easier to remember. Words are also easier to type on mobile devices with autocomplete. Typos are more obvious in common words. With words instead of single letters, typos are less likely to take you to an existing but incorrect page.

Tclssg

The manual process was soon replaced as I started developing the Tclssg static site generator. The focus of the site became its newly added blog, which lasted from 2014 to 2016. Blogging didn’t necessarily encourage me to write and publish. The blog is preserved. Tclssg remains in use outside my website. It has been adopted by some Tcl users and projects, including core.tcl-lang.org.

Fossil SCM

The second major version (2020–2022) was a personal wiki served by Fossil SCM. After examining different wiki software and finding flaws in each, I went with one I was already using. I noticed Fossil’s curious potential beyond source control. Fossil had enough wiki and theming features to serve a customized website. It let me edit the site’s contents in the browser. I joked that Fossil SCM was secretly “Fossil CMS”. This marked a temporary break from storing content in Git. For deployment, I started building a Debian package with the Fossil binary, Caddy configuration, and static files. When installed, the package replaced the previous version of the site as a whole; if installation failed, changes were automatically reverted.

It took some hacks to make Fossil do what I wanted. The wiki lacked categories and transclusion. At the time, it could not generate a table of contents for a page. I created a simple notation for tags and began generating a “tag page” using a Tcl script. The script ran when I synchronized my local Fossil repository with dbohdan.com. (A Fossil synchronization is like a Git pull followed by a push.) The TOC was generated in JavaScript in the reader’s browser.

I enjoyed my time with a Fossil-based site. Being able to edit the wiki in the browser removed friction compared to a static site generator. However, I kept feeling Fossil’s limitations as a wiki engine. Beyond built-in categories and TOCs, I wanted the ability to version pages together. It’s easier to understand your site’s edit history when related changes to multiple pages are grouped together. Using the /doc/ page feature was an option but would have negated Fossil’s advantage of live wiki editing. I wrote fossil-wiki-export to have a migration path off Fossil and eventually used it.

Custom SSG

I initially2022 wrote the third major version of the static site generator in Clojure. It was still a wiki, only static. The code ran in Babashka and rendered a page template using Django templates-inspired Selmer.

Not long after, in 2023, I ported it to Python to take advantage of its numerous libraries and its good optional static typing thanks to Pyright. This made it easy to translate the template to Jinja. Deployment still used a Debian package, now with only static files, until I migrated the site to BoxyBSD in 2025. With that migration, I switched to rsync deployment.

I was quite happy with the Clojure-Python port. By using ThreadPoolExecutor in Python and leaning on Pandoc Lua filters, I reduced the build time of the site to single-digit seconds. (I also wrote an experimental async/await version. I discarded it when it proved slower than a thread pool.)

Macros

I consider shortcodes or macros essential for managing complex pages. They make a page easier to create and especially to maintain over time compared to raw HTML markup.

The macros in page Markdown went through several iterations. Tclssg allows you to write Tcl code in pages, which I used for transclusion and a more compact syntax for images. Those macros were gone with the switch to Fossil.

Macros in major version 3 of the site began as edn expressions between <<< ... >>> delimiters. The first term determined the macro function to call, such as include, and the rest was passed as arguments. The string returned from the function replaced the delimited expression. These macros were only simple shortcodes without control flow. With the migration to Python, I replaced edn with shlex. The content required minimal changes because I didn’t use complex edn expressions.

Most recently, I replaced custom macros with Jinja. This improved the macro system and, at the same time, reduced the line count in the SSG. What pushed me to do it was the need to optimize the size and image quality of the Chrontendo episode guide page, which had grown large with the addition of episode covers. A little testing of different image formats showed I could accomplish both goals with AVIF. However, I needed a fallback for browsers that didn’t support the still-new image format. Jinja let me define a macro in the body of the page that generated <picture> tags for AVIF images with JPEG fallback.

This is the macro:

<% macro cover(alt, src_prefix, attrs) %>
                        <picture>
                            <source srcset="<%= src_prefix =%>.avif" type="image/avif" />
                            <img alt="<%= alt =%>" src="<%= src_prefix =%>.jpg" <%= attrs =%> />
                        </picture>
                        <% endmacro -%>
                        

The delimiters are <% ... %> and <%= ... =%> in place of Jinja’s standard {% ... %} and {{ ... }} to avoid conflicts with things like the Caddy templates.

Native templates

In 2025, I ported my Jinja page template to htpy. After the Jinja template grew in complexity, I started thinking about how to make it more maintainable, especially how to spot problems early. I looked into other template languages and was drawn to writing HTML directly in Python. This meant I could use standard tools like Ruff and Pyright on the template.

I compiled a list of Python HTML DSLs and later picked htpy as the most mature. Porting the template and refactoring the generator was done in a day. I kept Jinja for macros. Later, I replaced htpy with a custom HTML DSL that I found more readable.

For comparison, here is a fragment of the template in Jinja, htpy, and my custom DSL. Jinja first:

{% if show_metadata %}
                        <footer>
                          <div class="box metadata">
                            {% if "index" not in tags %}
                            <div class="metadata-dates">
                              Published {{ published }}, updated {{ updated }}.
                            </div> <!-- .metadata-dates -->
                            {% endif %}
                        
                            <!-- ... -->
                          </div> <!-- .box .metadata -->
                        </footer>
                        {% endif %}

htpy:

page.show_metadata and footer[
                          div(".box.metadata")[
                            page.tags and "index" not in page.tags
                            and div(".metadata-dates")[
                              f"Published {page.published}, updated {page.updated}."
                            ],
                        
                            # ...
                          ]
                        ]

Custom DSL:

footer(
                            div(
                                f"Published {page.published}, updated {page.updated}.",
                                class_="metadata-dates",
                                if_=page.tags and "index" not in page.tags,
                            ),
                        
                            # ...
                        
                            class_="box metadata",
                            if_=page.show_metadata,
                        ),

Ruff’s linting and Pyright’s type checking were immediately useful with htpy. The Ruff Formatter was not. It didn’t format foo[bar, baz,] as multiline the way it would foo(bar, baz,), and it didn’t produce the look I wanted for a markup DSL. I quickly wrapped the layout in # fmt: off and # fmt: on to disable automatic formatting and decided to indent with two spaces.

htpy only output minified HTML, and I wanted the final HTML to be readable and indented consistently. Consistent indentation was something I didn’t have with Pandoc output inserted in a Jinja template. Since whitespace matters in HTML, I looked for a formatter that wouldn’t break significant whitespace, as tidy-html5 sometimes did. I found Prettier the most proven option. I was hesitant to add a Node.js dependency to the project compared to C, Go, or Rust. It turned out to not be a hassle to manage. The formatting step only took a couple of seconds.

Later in 2025, there was a series of supply chain attacks on NPM. Prettier wasn’t affected. Nonetheless, I decided it was best to move away from NPM for something I didn’t watch closely. I found a suitable replacement in dprint. While Rust also has a culture of many small dependencies, it hasn’t seen a similar level of attacks. (Yet. Growth mindset.)