Field note · February 10, 2026

This whole site is 900 lines of Node and one dependency

Why we wrote our own generator instead of using a framework, and what that bought.

1 min read ·Data engineering ·engineering

The site is a static generator we wrote, about 900 lines of Node, with exactly one dependency — a markdown parser.

This is not a purity thing. It was a maintenance calculation.

The site needs to still build in five years with no attention. Every dependency is a thing that can break, deprecate, require a migration, or acquire a supply-chain problem. A framework would have saved perhaps two days of initial work and added a permanent upgrade obligation for a project nobody is paid to maintain.

What the 900 lines do:

  • Parse a small YAML subset for front matter — the only formats content actually uses, and it throws loudly on anything else rather than guessing.
  • Render markdown with a custom renderer for anchored headings, base-path-aware links, and a syntax highlighter that covers the four languages the course uses.
  • Generate every dataset from a fixed seed at build time, so a rebuild produces byte-identical CSVs and "row 4,112" stays row 4,112.
  • Emit pages, a search index, RSS, and a sitemap.
  • Withhold any post whose date has not arrived.

The syntax highlighter is 130 lines and only knows Python, SQL, JavaScript and bash. Anything else renders as escaped plain text, which is a much better outcome than wrong colour.

The one thing I would defend hardest: every page renders without JavaScript. The whole course, every article, every dataset page. JavaScript adds search, the theme toggle, progress tracking and the tools, and nothing breaks without it. That is not nostalgia — it is what makes the site fast on a bad connection and readable in a decade.

Build time for 108 pages and 5MB of generated CSV is under a second. The whole thing is MIT licensed if you want to fork it and make one about something else.