This site is generated by a static site generator written in Rust — about 90% of the custom logic in this repository is Rust, and the pages you are reading were produced by it in a single deterministic build pass.
This article walks through the pipeline, shows the interesting parts of the implementation, and documents the trade-offs we made along the way.
Why build one at all? #
The obvious question: static site generators exist, and good ones are free. But a blog generator is a uniquely pleasant project:
- The problem is small and well-bounded — Markdown in, HTML out.
- The feedback loop is fast, which makes experiments cheap.
- Real constraints still apply: correctness, performance, accessibility.
The pipeline #
The build is a straight pipeline with one twist — nothing is published until everything verifies:
- Load and validate frontmatter (strict, fail-fast).
- Parse Markdown into an event stream.
- Transform headings, code blocks, callouts and images.
- Compile SCSS with grass.
- Render templates, generate RSS/sitemap/search JSON.
- Verify every internal link, then swap
dist/atomically.
Markdown as an event stream #
We do not parse Markdown with regular expressions. Instead we treat the parser as a
stream of events and rewrite the ones we care about — headings get anchors, fenced
code is highlighted, blockquotes labelled Note: become callouts:
Headings and anchors #
Every heading gets a slug id and a hover anchor. The table of contents is a free by-product of the same pass — no second parse needed.
Because the parser reports source offsets, unsafe link schemes can be rejected with the exact file and line number:
error: in `content/posts/x.md`, line 12: unsafe link `javascript:alert(1)`
(blocked URL scheme)
Syntax highlighting without inline styles #
Syntax highlighting emits classes, not colors. All token colors live in SCSS and respect the light/dark themes — the same HTML renders correctly everywhere:
An unknown language is not an error — it degrades to plain, escaped text.
Determinism and atomic output #
Two properties make the build trustworthy:
| Property | How it is achieved |
|---|---|
| Deterministic output | sorted iteration, content fingerprints, no wall-clock timestamps |
| Atomic publishing | render into a staging directory, verify, then swap |
The same content always produces byte-identical output, which makes caching,
diffing and rollback trivial. CI builds twice and diffs the trees.
Content as data #
Frontmatter is strict on purpose: unknown keys are rejected, dates are validated,
themes are an enum, accent colours must be #RRGGBB. A typo in metadata fails
the build instead of silently shipping a broken page.
title: "Building a Static Site Generator in Rust"
date:
tags:
theme: paper
accent: "#E56A35"
What we deliberately left out #
- No client-side framework — the article you are reading ships about 3 KB of JavaScript, and none of it is required to read the page.
- No external fonts — the system stack renders beautifully and costs zero bytes.
- No build-time Node.js — SCSS compiles with a Rust Sass implementation.
Footnotes and further reading #
Static site generators reward exactly the skills systems programming teaches: ownership of the whole pipeline, refusal to paper over errors, and a bias toward boring, predictable tools.1
Try the search on the blog index — the index is built at compile time and the matching runs entirely in your browser.
The sitemap, RSS feed, robots.txt and search index are all generated in the same pass, from the same content model, in about 300 ms.