About this site
My website has been online since 2013. It serves as my personal wiki where I collect writing and thoughts. Some pages are rougher and most useful for me, while others are more polished and made 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 result is something like a wiki that only one person can edit.
The static site generator performs the following steps for each page:
- Take Pandoc Markdown text and TOML metadata
- Expand Jinja macros in the Markdown (if enabled for the page)
- Convert Markdown to HTML with Pandoc
- Inject the HTML into a Jinja page template configured using global and page metadata
I keep the content and the code versioned separately in two different Git repositories.
Influences on the site include Wikipedia, the Tcler’s Wiki, Ward Cunningham’s wiki, the Memex and Ted Nelson’s writings, TiddlyWiki, TV Tropes, Everything2, and Everything Shii Knows.
The common theme of these sites is writing evolving pages instead of finished blog posts. Other themes include internal linking, organizing link collections into documents (similar to Memex “trails”), and 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 your future self, the influence is concrete in the design. I have borrowed many design elements from Gwern.net that are not visible to the reader, like Pandoc, link archival, and the interwiki link syntax ([favicon](!W) to link to “Favicon” on Wikipedia), as well as visible design elements like the subscript dates and link icons.
The initial version of the site (subsequently labeled 0.x) was a static 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 unchanged. I wrote the pages in Markdown and converted them to HTML manually with John Gruber’s Markdown.pl. To store the page source code, I created a Git repository.
This 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 was not necessarily a medium that encouraged 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.
The second major version (2020–2022) was a personal wiki served by Fossil SCM. After examining different wiki software and finding flaws with each, I went with one I was already using. I had noticed Fossil’s curious potential for use outside of source control. 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”. This marked a temporary break from storing content in Git.
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 content for the 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 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. Besides built-in categories and TOCs, I wanted the ability to version pages together. You can understand the edit history of your site better when related changes to multiple page are grouped together. Using the /doc/ page feature was an option but would negate Fossil’s advantage of live wiki editing. I wrote fossil-wiki-export to to have a migration path off Fossil and eventually used it.
I initially wrote the third major version of the static site generator in Clojure. It ran in Babashka and rendered a page template using Django templates-inspired Selmer. Later, I migrated it 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 consider shortcodes or macros essential for managing complex pages. They make a page easier to create and especially to maintain over time compared to 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, like 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 have 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 grew large with the addition of the 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.
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 in the path ([/A-Za-z0-9.-_]) 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
https://dbohdan.com/wiki?name=How+
Internet+ communities+ function
and evolved to
and then
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 lowercase English words 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
- Clean URL
I cannot 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 the site uses 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.
The site favicon is taken from the original Windows File Manager (winfile.exe). In 2018 Windows File Manager was released as free software under the MIT License.