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:

Diagram of the build pipeline: Markdown content flows through the Rust generator into the static output directory

  1. Load and validate frontmatter (strict, fail-fast).
  2. Parse Markdown into an event stream.
  3. Transform headings, code blocks, callouts and images.
  4. Compile SCSS with grass.
  5. Render templates, generate RSS/sitemap/search JSON.
  6. 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.

rust
fn take_inner(events: &[(Event, Range<usize>)], start: usize) -> (Vec<Event>, usize) {
    let mut depth = 1usize;
    let mut inner = Vec::new();
    let mut j = start + 1;
    while j < events.len() {
        match &events[j].0 {
            Event::Start(_) => depth += 1,
            Event::End(_) => {
                depth -= 1;
                if depth == 0 { break; }
            }
            _ => {}
        }
        inner.push(events[j].0.clone());
        j += 1;
    }
    (inner, j)
}

Because the parser reports source offsets, unsafe link schemes can be rejected with the exact file and line number:

text
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:

rust
pub fn highlight(&self, code: &str, lang: &str) -> Result<String> {
    let syntax = match self.syntax_set.find_syntax_by_token(lang) {
        Some(syntax) => syntax,
        None => return Ok(escape_html_text(code)),
    };
    let mut generator = ClassedHTMLGenerator::new(syntax, &self.syntax_set);
    for line in LinesWithEndings::new(code) {
        generator.parse_html_for_line(line)?;
    }
    Ok(generator.finalize())
}

An unknown language is not an error — it degrades to plain, escaped text.

Determinism and atomic output #

Two properties make the build trustworthy:

PropertyHow it is achieved
Deterministic outputsorted iteration, content fingerprints, no wall-clock timestamps
Atomic publishingrender 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.

yaml
title: "Building a Static Site Generator in Rust"
date: 2026-10-20
tags: [rust, systems-programming]
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.

1

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.