ferrisite: replacing Hugo with a generator built from my own diagram tools
Part 7 of 7 in Building your own tools
Contents
I didn’t replace Hugo because Hugo was slow or hard to use. I replaced it because seven articles couldn’t be published, every diagram on the site was drawn by a script fetched from a CDN, and the tools that could fix both were already mine.
ferrisite is a static site generator written in Rust. It reads the same Markdown and AsciiDoc content Hugo did, renders it through templates, and writes static HTML. What makes it different from any other generator is where its diagrams and AsciiDoc come from: mmd for Mermaid, puml for PlantUML, forge for architecture models and adoc for AsciiDoc. They’re my own pure-Rust tools, and they all lay diagrams out into the same data structure, diagram-scene, so one painter draws all of them. ferrisite is one binary with no Node, no Java and no Ruby.
Since 1 November it builds this site: 148 published posts going back to July 2009, 524 legacy URL redirects from the WordPress and Jekyll years, and 522 more for tags I retired. This post is about why I built it, how I made sure the switch didn’t break anything, and the three things that broke anyway.
What Hugo couldn’t do here
The first problem was seven articles. In 2017 I wrote a series on event-driven architecture in AsciiDoc, with PlantUML diagrams inline. Under Jekyll they rendered through asciidoctor-diagram, which ran a PlantUML jar checked into the repository, which needs Java. When the site moved to Hugo, Hugo could still run asciidoctor for the AsciiDoc, but not the diagram extension, so the series sat in the repository as drafts with 14 diagrams that nothing would draw.
The second was how Mermaid worked. Hugo’s Markdown render hook turned a ```mermaid fence into a <pre class="mermaid">, and a script in the base template imported Mermaid from jsDelivr on any page that had one. The diagram was laid out in the reader’s browser, after the page loaded. Switching between light and dark mode called location.reload(), because Mermaid has no clean way to re-render in place. It worked, but each diagram depended on a third-party CDN and on JavaScript, and a crawler or an agent reading the HTML saw diagram source, not a diagram.
The third was something I wanted to add rather than fix: output written for AI agents as well as people. Every page available as Markdown, an llms.txt index, and a stated policy on training. Hugo can be made to do most of that with custom output formats, but it’s work against the grain of its templates.
All three pointed the same way. mmd, puml and adoc were already finished tools with releases. A generator built around them would render every diagram at build time, in both colour schemes, and fail the build if a diagram used syntax they didn’t support. I decided that last part early: a diagram that silently disappears or degrades is worse than a build that stops and names the file and line.
Not a Hugo replacement
The design document lists what ferrisite deliberately doesn’t do, so that a later session doesn’t helpfully build it. It doesn’t run Go templates: the site’s layouts were rewritten in minijinja. It doesn’t compile Sass: the theme’s compiled CSS is vendored once as plain CSS. There’s no plugin API, no multilingual support, no theme inheritance and no image processing beyond social cards. Features exist because this site uses them. Before writing any code I inventoried what the site actually used, down to frontmatter keys by count (title 211 times, aliases 143, install 9, and so on), and that list was the scope.
That’s the advantage of software with one known user: the hard part of a general generator is everything other sites need. ferrisite needed to do what Hugo did for this site, byte for byte where it mattered, and nothing else.
Proving the switch with a parity check
The risk in replacing a site generator isn’t the pages you look at. It’s the redirect stub for a 2011 WordPress URL that someone linked to from a conference talk, or a tag page that moves because two posts spell the tag differently. So the switch was gated by a command, ferrisite parity, that builds nothing itself. It takes two finished sites, the Hugo build and the ferrisite build, and checks:
- every file in the Hugo build exists in the ferrisite build;
- every redirect stub points at the same target;
- every internal link on every page matches, and none is broken, fragments included;
- every RSS feed lists the same items in the same order.
Anything ferrisite produces by design that Hugo didn’t, like the Markdown copies, is listed with a reason rather than ignored silently. The last run before the switch compared 254 pages and checked 9,671 links, with no missing files, no redirect differences and no link differences. Feed descriptions differ in 545 items, which the check counts but doesn’t fail on: summaries truncated at 200 characters come out slightly differently, because Hugo counts ’ as seven characters and ferrisite counts it as one.
Parity is a migration tool, and I’ve already arranged for it to be deleted. Link checking, which ferrisite check also needs, moved into its own module so that nothing depends on the parity code once the Hugo fallback is retired.
Diagrams at build time, and the fixes they forced
Every Mermaid, PlantUML and forge diagram is now laid out once and painted twice, into a light and a dark SVG, and CSS shows the one that matches the page. No script, no CDN and no reload on a theme change. The colours come from the site’s config, so the build-time diagrams match the palette the client-side ones had.
The real content found gaps that my tools’ own tests hadn’t. The event-driven architecture articles used PlantUML participant boxes, labelled relations and skinparam blocks that puml didn’t parse yet, and AsciiDoc includes whose paths used attributes, which adoc didn’t substitute. Rather than work around them in ferrisite, I fixed them upstream and released puml v2026.10.31 and adoc v2026.11.1, and ferrisite pins those tags. The styling pass afterwards turned up two more adoc bugs, an image attribute list read as alt text and bold that spanned a line break showing literal asterisks, which went out as adoc v2026.11.2. The series went back up on 1 November with all 14 diagrams.
Output for agents
Every page also exists as Markdown, at its URL plus index.md, and its HTML says so with <link rel="alternate" type="text/markdown">. There’s an /llms.txt index and an /llms-full.txt with every post (672 KB at the moment), and robots.txt carries Content-Signal: search=yes, ai-input=yes, ai-train=no: index it, read it to answer questions, don’t train on it. ferrisite check --agents fails the build if any page is missing its Markdown copy or its alternate link, or if llms.txt has a link that doesn’t resolve.
Whether agents actually use any of this is a separate question, and I don’t know yet. One study found that most llms.txt files get no AI requests at all. The cost of publishing them was small, and the host’s logs will say whether they’re read.
Three things only the deploy could show
The first deploy run failed. ferrisite check, running in CI, reported 510 broken links: every page pointed at the theme’s stylesheet and search script, and neither existed. They were in the repository’s ferrisite-static/public/ directory on my machine, but .gitignore had a line, public/, meant for Hugo’s output at the root. It also matched ferrisite-static/public/, so the files had never been committed. Every local build and check had passed, because the files were on my disk. The fix was one character, /public/, and the check in CI is the only reason it didn’t reach the live site.
The second was case. Before the first real publish I compared the live site’s files with the new build’s, and found eight tag pages that would disappear: /tags/ruby/, /tags/process/, /tags/Design/ and five more. The live site had been built before I consolidated the tags, when Hugo picked different spellings, and the new build had /tags/Ruby/ and /tags/Process/. The web server treats URLs as case-sensitive, so the old spellings would have returned 404. My Mac’s file system doesn’t, which is why neither the comparison nor any local build had shown it until I checked against exact paths. Seven became redirects; Ruby, which is still a live tag, took the spelling the live site already used.
The third came from the fix for the second. With both /tags/Design/ and /tags/design/ now redirect stubs, two outputs mapped to one file on a case-insensitive disk, and ferrisite writes files in parallel through a temporary file that both writers named identically. Local builds started failing intermittently while CI, on Linux, built cleanly. A test that writes 40 pairs of such stubs failed three times in three on the old code, and passes now that every write gets its own temporary name.
None of the three was a bug in the parity check’s logic. All three were the gap between the machine the site is built on and the machine it’s served from.
Fast enough to forget about
A full build of the site takes 0.9 to 1.2 seconds from an empty directory, on a 12-core laptop. Most of that is the 224 social card images: drawing and compressing PNGs was three-quarters of the CPU time. Rebuilding into the same directory when nothing has changed takes a quarter of a second, because ferrisite now writes a file only when its contents change and caches each card by a hash of its drawing. ferrisite serve, which I use while writing, skips the cards, rebuilds when any file under the site root changes and reloads the open page.
What it took, and what I’d keep
ferrisite is 8,462 lines of Rust across 25 files, plus 647 lines of integration tests, 95 tests in all. The repository has 30 commits, all on 31 October and 1 November, with Claude Code doing most of the typing. Two days is possible because the hard parts already existed as finished tools; ferrisite is mostly the glue between them and the site, plus the checks.
If I did it again, I’d keep the order: inventory first, parity before switching, and a check in CI that fails on broken links. I’d also add a comparison against exact paths on a case-sensitive file system from the start, rather than finding out from the server.
Try it
ferrisite is public at github.com/grahambrooks/ferrisite. It’s built for this site rather than as a general Hugo replacement, so expect to write templates. The first release, v2026.11.1, has prebuilt tarballs for Linux (x86_64 and aarch64) and Intel macOS. To build from source:
It needs Rust 1.99 or later.