(SSG means static site generator.)

This website was first made with Jekyll. I quickly found it lacking and wrote my own hodgepodge of Perl scripts to replace it. About 10 years later, I also found that lacking and rewrote it.

Was this worth it? Should I have just used something readily available and made it work?

Too many choices

Every person has their own laundry list of features they want out of an SSG. For example, I want:

• Backwards compatibility with old content for 20+ years.
• Build from single static binary.
• Full cold build under 1 second.
• Detailed logging of render times to support above.
• Built-in HTTP server with file watcher.
• Purpose built templating engine (e.g. Jinja)
• …with embedded data serialization (e.g. YAML)
• …and embedded computation (e.g. Lua).
• Extensible Djot markup.
• Page–index distinction.
• Single pass build with self-contained pages.
• HTML pages all rendered to <url>/index.html.
• Ability to output non-HTML pages from template engine.
• Build time syntax highlighting (with a theme I like).
• Build time maths formatting.
• No client side JavaScript required for any of the above.

You probably want an entirely different set of features.

It’s certainly possible there’s an off-the-shelf solution that does all this. There’s a lot of them out there. Maybe Hugo can do everything if we read enough of their documentation (although it doesn’t even seem like Djot is an option right now, let alone extending it).

But even if something adequate already existed, the amount of time it would take to find and understand it is longer than it would take to just write a custom SSG.

All of them suck

You don’t need an SSG to make a website. You could just write all the HTML, CSS, and JS files directly. All an SSG does is abstract away the tedious or repetitive parts of that. That’s it. For example, it might insert a header and footer around every page, or it might transform some Markdown into HTML, or it might pull in an entire npm abomination and bundle it into megabytes of JavaScript.

Everything an SSG does is an abstraction, and abstractions have a cost: you have to learn the interface. What are its inputs? What happens for this input, or that input, or what if there’s an error? The more inputs the interface has, the greater its exposed complexity and the greater the cost of the abstraction.

For an SSG, this interface can be endless: What is the markup language? Can it produce this kind of document? Can it fall back to raw HTML if needed? What is the template engine? How do I extend these? Where do files go? How do template includes work? What data is exposed to the template engine, and where? Are there included HTML layouts and CSS themes? What are the classes used for these? Can they be modified, and how? Is there any bundled JavaScript for certain functionality? How does that work? Can I turn off features I don’t like? And so on and so forth.

So if we do learn all this complexity for whatever SSG we’ve chosen, what are the rewards? How much complexity does the interface dissolve?

Breaking down the roughly 700 lines of code that currently generate this site:

• ~200 lines copying the source files and coordinating them with minijinja.
• ~170 lines extending Djot.
• ~120 lines defining custom jinja filters.
• ~110 lines for the HTTP server and file watcher.
• ~50 lines for the CLI.
• ~40 lines of dependencies.

These are all details I am specifically interested in. They’re not things I want hidden. What’s more, most of that code is plugging libraries together.

If one imagines a hypothetical SSG that is modular enough for such modifications to even be possible, the interface would be enormous, and these modifications would be more lines of code since there would be fewer libraries available and it would be more complicated to integrate them.

It took me a weekend to write the initial Perl script that made this site. It took me another weekend to do the Rust rewrite (although porting all the content took two weeks). These are not complicated programs. Even this site’s CSS file is fewer lines. The real work is done by the libraries: the markup language, the template engine, etc.

Why do you even want a website?

Perhaps writing an SSG is not in your wheelhouse, but you still want a website. Why? There are many good reasons, but the reason chooses the tool, and an SSG may not be the right one.

• You want to own your content? Use Substack.
• You also want to own your brand? Use WordPress.
• You want something with batteries included? Use Squarespace.
• You want to sell things? Use Shopify.
• You want a personal knowledge base? Use Obsidian or MediaWiki.
• You want to use the full power of the web? You should be able to write an SSG.
• You want free web hosting? Hugo might be the right option.