I wrote my own site generator. Should you use it?

I built colophon, the generator this blog runs on, so treat everything here as the opinion of a man reviewing his own homework. I've tried to keep it to facts and features rather than affection. Where colophon is the wrong choice I'll say so, because pretending otherwise helps nobody, least of all me.

The boring truth first: almost every static site generator does the same core job. Markdown goes in, a fast pile of static HTML comes out, and you host it somewhere cheap. They differ on three things that actually matter: how mature and well-supported the tool is, what comes built in versus what you bolt on, and who it was written for.

The grown-ups

These are the tools you should reach for by default.

Hugo is the sensible answer for most people, and it's what this blog originally ran on. It renders a large site in seconds, has by far the biggest theme catalogue, and if you hit a wall someone solved it years ago and wrote it down. Jekyll is older and slower on big sites, but if you just want to push Markdown to GitHub Pages and walk away, nothing is simpler. Zola is the closest of the lot to colophon in spirit: one Rust binary, sensible things built in, and a deliberate refusal to grow a plugin system. Eleventy and Astro are the JavaScript end of the room, Eleventy all flexibility and no opinions, Astro a proper framework for when a "blog" is really an app wearing a blog's clothes.

None of them ship AI media generation, spoken-audio readings, IndieWeb webmentions or POSSE syndication in the box. That isn't a criticism: it's a scope decision, and you can add most of it with plugins and a few external services.

Where colophon is actually different

colophon is also a single Go binary that turns Markdown into a static site, so on the core job it's unremarkable. The difference is what it folds in as first-party features, the parts you'd otherwise assemble from a plugin here and a SaaS there:

• AI-generated hero images from a gen: prompt, and spoken text-to-speech readings of each post, content-addressed and cached
• IndieWeb plumbing: microformats, webmentions, and POSSE syndication to Bluesky and Mastodon, built in
• A glossary with reference links, slide decks derived from the post, and an Obsidian vault as a first-class source

The on-site search deserves a specific mention, and a specific honesty. The architecture isn't original: it's the model Pagefind popularised, a sharded index built from the rendered output, with the browser fetching only the shards and fragments a query actually touches, and colophon's design notes say exactly that. What's different is that it's Go-native and dependency-free, with its own open format rather than a reverse-engineered one, a vanilla-JavaScript reader and no WASM, where the usual way to get this is to shell out to Pagefind's Rust toolchain. It lives as a standalone module with a language-neutral spec and golden test vectors, so it indexes any {id, url, title, body} documents and anyone can write a conformant reader in another language. I'm pleased with how it turned out, but I'm not claiming the idea.

That bundle is the whole pitch.

Accessibility, and languages

Two things colophon tries genuinely hard at, with very different results so far.

Accessibility is treated as the engine's job rather than something you inherit from whichever theme you happened to pick. There has been a deliberate sweep toward WCAG AAA: code blocks, diagrams and display maths are keyboard-focusable scroll regions, every control has a visible focus indicator, the muted text and link colours are pushed to the 7:1 contrast ratio AAA asks for, audio and attachment markers carry real labels, the glossary pop-overs are proper accessible tooltips, and the whole site still works with JavaScript switched off. Any of the grown-up tools can be made just as accessible with a careful theme; the difference is who carries that weight. Here it's baked into the engine, not left to you.

Internationalisation is the part still in flux. The foundations have been there a while: a per-post language tag that flows into <html lang>, the feeds and Open Graph, plus localised player chrome and pronunciation tables in six languages. Newer, and currently being trialled, is proper multi-language posts: drop a my-post.es.md beside the English one and you get a Spanish version at /es/posts/my-post/, linked by a shared slug, with hreflang alternates, a language selector in the header, and a quiet browser-preference banner that never force-redirects. Each translation is a full post, so it gets its own reading, feeds and deck. This very page is the test: there's a Spanish version, and the selector at the top will take you to it. That's an experiment in the feature rather than a change of language here. I'm not starting to post in Spanish, and the Spanish version is a translation of this post rather than something written separately, so read it as a demonstration of the plumbing rather than as Spanish writing. It's early, and Hugo's multilingual is still more complete and more proven, but the bones are good, and it's exactly the sort of thing where help would be very welcome.

The honest part

There is no popular tool that matches colophon feature-for-feature. The single-binary, batteries-included niche is held by Zola and Hugo; the own-your-content, federate-by-default spirit is best embodied by Micro.blog, which is a lovely thing but a hosted, paid platform rather than a generator you run. colophon's particular combination doesn't exist elsewhere in one box, and that cuts both ways: it's the reason to look at it, and the reason not to.

colophon is a work in progress and right now it's just me, so contributions are very welcome. The assumption is that most people will interact with it through an LLM and the skills it ships, because that's what makes getting your thoughts down quick, and I'd expect the same from anyone who wants to work on it. Found a bug? Pull out your LLM of choice and file a PR. I use my own agent tooling (aide), and if you do too you'll inherit the same captured decisions and implementation standards.

To be fair in the other direction: your words aren't trapped if you did choose to give it a try. The input is plain Markdown and the output is ordinary static HTML, so moving to another tool means rewriting templates and config, not rescuing your content. The lock-in is in the conveniences, not the writing. That's the bit I care about most, and it's true of all the tools here.

So when is colophon the right thing, if ever

Pick one of the grown-ups if you want a blog that simply works for the next decade. For most people, most of the time, that means Hugo. Choose Jekyll if you live on GitHub Pages, Astro if you need components, Eleventy if you want to build it your way, and Micro.blog if you want the IndieWeb and cross-posting half without running anything at all. Or simply, any of the hundreds of other tools that do something similar, or roll your own!

colophon earns its place in a narrow case: you specifically want that opinionated bundle, generated images, spoken readings, IndieWeb and POSSE, glossary and slides, in a single binary instead of stitched together.

It's especially useful if you write in Obsidian, and you can happily live close to the edge of a young, one-maintainer project. That's a real reason. It's just not a universal one, and today the person it fits best is me. I use it because I wanted exactly these features in one place and I'm content to be my own support desk.

Related

• A Colophon Blog on Cloudflare Pages and R2: how this blog is actually built and hosted.
• Wiring the Blog into the IndieWeb: the federation and POSSE half, in practice.
• The Post Is the Slide Deck: one of the bundled features, decks derived from a post.
• Rebuilt the Blog. Again.: why I moved off Hugo in the first place.