My website has been online since 2013. It serves me as a personal wiki where I collect my writing and thoughts. Some pages are rougher and less presentable while others are more polished and suitable for other readers. Cam Pegg’s defunct “Notes to Self” listed the site as a “digital garden”.
In its current incarnation the site is a collection of interlinked HTML files output by a custom static site generator and served by Caddy.
The build process
- Takes Pandoc Markdown text and TOML metadata;
- Expands file-include macros in the text;
- Converts Markdown to HTML with Pandoc;
- Places the HTML in a page template configured using global and page metadata.
I version the content and the code separately in two Git repositories. The result is something like a wiki that only one person edits.
The common theme is writing evolving pages instead of finished blog posts. Other themes include internal links, organizing link collections into documents (similar to Memex “trails”), one page per subject.
The biggest influence is Gwern.net. Watching its development was what finally made me turn a stalled blog into a personal wiki. Besides the philosophy of perpetual drafts and writing for my future self, the influence is concrete in the design. I have borrowed many design elements that are not reader-visible from Gwern.net, like Pandoc, link archival, and the interwiki link syntax, as well as the very reader-visible subscript dates and link icons.
The first incarnation of the site (version 0.x; current is 3.x) was a page with links to my profiles on other sites and a contact form. The links survive in the “elsewhere” section of the index page, and the contact form is largely intact. I wrote the pages in Markdown and converted them to HTML manually using
Markdown.pl. I stored the page source code in a Git repository.
The third incarnation was a personal wiki served by Fossil SCM. After examining different wiki software and finding flaws with each, I went with something I was already using instead. I had noticed Fossil’s curious potential for use outside of source control. This marked a temporary break from storing content in Git. Fossil had enough wiki and theming features to serve a customized website. It let you edit the site’s contents in the browser. I joked that Fossil SCM was secretly “Fossil CMS”.
My time with Fossil was enjoyable. Being able to edit the wiki in the browser removed friction compared to a static site generator. However, I felt Fossil’s limitations as a wiki engine. Something I wanted, besides built-in categories and TOCs, was the ability to version pages together. I wrote fossil-wiki-export to to have a migration path off Fossil and eventually used it.
I initially wrote the fourth-incarnation static site generator in Clojure using Babashka and a page template in Django-inspired Selmer. Later I migrated to Python to take advantage of its numerous libraries and good optional static typing thanks to Pyright. A Django-inspired template language made it easy to translate the template to Jinja.
I experimented with long URLs derived from the page title by a simple algorithm. What I learned was that URLs should be short. They should also use a minimal set of characters (
[/a-z0-9.-]) in the path and avoid query strings.
In the Fossil incarnation of my site I decided at first to embrace Wikipedia-style page naming: my page URLs included the full title. I thought it was neat: one less thing to worry about; less friction when creating pages.
My Fossil URLs started out as
and evolved to
First, I realized the query part of a URL is too easily lost. Looking for alternatives, I discovered Fossil allowed
/wiki/Baz+foo instead of
/wiki?name=Baz+foo. I didn’t link to my site from many places, yet I still noticed that spaces encoded as
+ in the path part of the URL were sometimes a problem for linking and automatic URL detection. Encoding spaces as
%20 worked more often but looked even uglier. Eventually, I gave up on the idea of page names with the full title.
When I migrated off Fossil, I dropped the
/wiki/ part. My current URL format is one or more lower-case words in the English alphabet joined by dashes:
- 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
I can not quite 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 a mobile device 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 wrong page.
For almost a decade the site used lightly customized Bootstrap 3: at first plain, then with the theme Sandstone from Bootswatch. Now it used its own stylesheet that partially imitates the look it had with Bootstrap. The site’s current palette was built around a tweaked subset of colors from Sandstone.