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. They are 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.

Dark mode

The site implements dark mode using the prefers-color-scheme media query with a switch to override the OS/browser preference. It avoids the mistake of having a switch with only to states, light and dark, and allows the visitor to return to their OS/browser preference. The switch and the approach to dark mode are modeled on Gwern.net’s. The switch replaces the media attibute on a dedicated <style> element for dark-mode CSS.

Loading and storing the settings and replacing the media query is implemented in dark-mode.ts; the switch logic is implemented in dark-mode-switch.ts. dark-mode.ts stores the visitor’s preference in localStorage. While dark-mode-switch.ts is compiled from TypeScript and bundled with other JavaScript, dark-mode.ts is compiled and inlined in the page source, as is dark-mode CSS. This is done to prevent a flash of light on page load.

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 version2020–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 had 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. I have keep the content and the code versioned separately since.

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 the server. (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. The site was still a wiki, only static. The code ran in Babashka and rendered a page template with Django-inspired Selmer.

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

I was quite happy with the Clojure-to-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 after establishing it was 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 page, which had grown large with the addition of episode covers. A little testing of different image formats showed I both reduce the size and improve the quality 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.

Code-based templates

I experimented with writing HTML in Python. After the Jinja template grew in complexity, I started thinking about how to make it more maintainable, and especially how to detect problems early. I looked into other template languages and was drawn to writing HTML in a Python DSL. This meant I could use standard tools like Ruff and Pyright to check the template.

I compiled a list of Python HTML DSLs and later picked htpy as the most mature. I kept Jinja for macros. The switch resulted in a mild performance improvement. 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,). I quickly wrapped the layout in # fmt: off and # fmt: on to disable automatic formatting. To make the code more compact like HTML, I decided to indent with two spaces.

In the end, I didn’t find htpy code particuarly easy to read or edit. I replaced htpy with a custom HTML DSL that I found more readable some time later and soon reverted to Jinja with regular HTML for the readability.

For comparison, here is a fragment of the page template in Jinja, htpy, 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}."
    ],

    # ...
  ]
]

My 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,
),