an invisible migration to a different static site generator

be0ba

2024-06-02

Invisible Changes

As absolutely noone will have noticed, over the last day I’ve migrated from generating this site using Kristaps Dzonsons’ sblg and lowdown to racket and Matthew Butterick’s pollen. (If you haven’t seen MB’s Practical Typography site, I highly recommend it.)

As I’m still using markdown as the input format, and the same output templates (lightly modified for pollen instead of sblg), the visual output is essentially identical, although the generated HTML is slightly different in places.

For anyone interested in seeing how this is all put together, the links to the individual projects I’m using are linked at the bottom of every page, and the source for this site is available here.

Background

I very much appreciate sblg and lowdown; both well written, portable software. The real driving force behind this migration is the mandatory orchestration between the two, and a reliance on XML as an intermediary format. The Makefile had to crank out XML snippets with shell variable interpolation to generate articles; it was very painful, and painful to change or work with.

Pollen on the other hand has one command that builds everything without further orchestration required: raco pollen render. The Makefile now serves as a wrapper to sequence rendering, installing the files into the separate repository the site is deployed into, and updating the site.

Markdown Portability

One of the biggest highlights of this migration for me was the relative lack of vendor lock-in imposed by sblg+lowdown. While markdown has several popular variants, I don’t use anything fancy enough to be non-portable, so Pollen already understood the source files just fine, save for one thing. lowdown supports document tags at the start of a file; simple key: value strings until the first blank line is found. Pollen doesn’t have any out of the box support for this, but does provide full access to Racket, so tag conversion was actually simple:

key: value

became

◊(define-meta article/key "value")

Templates have ready access to this information in a #hash, so fetching the information is as simple as can be:

<html>
...
        <h2>◊(select 'article/tag metas)</h2>
...
</html>

Difficulties

The most difficult part of the changeover was generating the index page. sblg essentially did this automagically, but Pollen required some extra logic. Along with templates, Pollen looks for a pollen.rkt file to provide extra definitions. Once I got a handle on how to generate a proper hierarchy of lists (it took me forever to find the unquote-splice operator (,@)), generating the index became very easy.

Conclusions

This was a fun project that helped me delve deeper into Racket in a surprising way, and I’m certainly going to keep Pollen in mind as a tool for other projects as well. While I’m using it to generate HTML from markdown, that is essentially operating in it’s simplest, most boring mode. Pollen supports multiple input and output formats, and much more customization than I’m making use of.