A small static site generator

Part of the how this site is built series. This one covers the generator: about 900 lines of Node that turn a folder of markdown into the site. The idea is own the glue, borrow the hard parts. Anything with nasty edge cases is a library, and the code in between is small enough to read in one sitting.

Why not a framework

I tried MkDocs first and it looked like a docs portal. Astro or Eleventy would have worked, but a custom generator meant one renderer shared with the phone admin, no upgrade churn, and a build that does exactly what this site needs and nothing else. With Claude writing most of the glue, it was quicker than learning a framework’s way of doing things.

The libraries

Templates are plain JavaScript functions using a small html tagged template that escapes everything by default. No template language to learn.

The content model

Every post is a folder:

content/
  food/
    egg-custard/
      index.md
      cover.jpg
  tech/
    how-this-site-is-built/
      index.md

Frontmatter only needs four fields:

---
title: "Egg custard"
type: recipe        # recipe or note: decides the layout
section: food       # where it lives in the menu, and the URL
date: 2024-10-11
tags: [dessert]     # optional, but must exist in taxonomy.yml
cover: cover.jpg    # optional
---

section and type are separate on purpose. A food reference sheet and a Linux how-to are both notes, but they live in different sections. Recipes can also carry serves, prep, cook and diet, and the recipe layout puts the ingredients beside the method on wide screens.

taxonomy.yml and the validator

taxonomy.yml lists every section, type and tag, each tag with a one-line description and optional aliases. The validator checks every post against it before anything is written:

• required fields are there, and dates are real dates
• the section matches the folder the post is in
• the type exists, and type-specific fields only appear on that type
• every tag exists (aliases are rewritten to the real tag, with a warning)
• the cover file actually exists in the post folder

Any error stops the build. That is the point: tags cannot sprawl, and a typo never reaches the live site. The same validator runs in the phone admin before it saves.

What the build does

npm run build runs site/build.js, which:

1. Loads taxonomy.yml and site.yml and validates every post. Stops on the first batch of errors.
2. Renders each post: markdown to HTML, images resized and cached, cover crops made.
3. Writes the home page, section pages, tag pages, a tag index, related posts, a 404 page, RSS (feed.xml), sitemap.xml and robots.txt.
4. Writes _headers and _redirects for Cloudflare Pages (see the Pages post).
5. Builds the Pagefind search index over the finished HTML.

After a build, npm run check walks every page in dist/ and fails if any internal link, image or #anchor does not resolve. Resized images are cached in .cache/, so a rebuild on my laptop takes about a second.

Commands

npm run validate   # check content against taxonomy.yml
npm run build      # validate, then build into dist/
npm run check      # every internal link, image and anchor in dist/ resolves
npm test           # unit tests (node --test)
npm run dev        # build and serve dist/ on http://localhost:8080

Setting up something similar

1. Start a Node 22 project with "type": "module" and install markdown-it, shiki, sharp, pagefind and js-yaml.
2. Write a loader that finds content/*/*/index.md, and splits frontmatter from the body with a regex plus js-yaml.
3. Write the validator before the templates. A strict vocabulary file is the cheapest way to keep a site tidy as it grows.
4. Render with markdown-it, plug Shiki in as its highlight function, and resize images with sharp.
5. Write templates as functions that return strings, with escaping by default.
6. Run Pagefind’s Node API over the output folder last.
7. Add a link checker. It pays for itself the first time you rename a post.

I kept the markdown setup in its own module without Shiki (site/lib/markdown-base.js), so the Cloudflare Worker behind the admin can import it without bundling every highlighting grammar.