The Architecture of This Site

This site is built to last. The goal is that the full content should be rebuildable from source files alone, with no external API calls, no database, and no proprietary tooling that could disappear.

The pipeline

Every page starts as a Markdown file with YAML frontmatter:

---
title: My Page
date: 2024-01-01
tags: [example]
---

Content here.

The build script — a single Python file — walks the content/ directory, resolves wikilinks, calls Pandoc to convert Markdown to HTML, injects backlinks, renders Jinja2 templates, and writes static files to dist/.The build is deterministic: the same source always produces the same output. This is not just convenient — it is a correctness property.

Pages link to each other with [[Page Title]] syntax. The build script resolves these at compile time into proper HTML links. It also computes backlinks: every page knows which other pages link to it.

This gives the site a graph structure, assembled from the filesystem at build time, with zero runtime computation.

Math

Math is written in LaTeX and rendered client-side by KaTeXKaTeX is bundled locally — no CDN dependency. The raw LaTeX source is always present in the HTML for readers who disable JavaScript.:

$$\int_0^\infty e^{-x^2} dx = \frac{\sqrt{\pi}}{2}$$

Inline math: the Euler identity is eiπ + 1 = 0.

Longevity guarantees

The site can be rebuilt from:

  1. The content/ directory (plain Markdown)
  2. build.py (Python 3, standard library + Jinja2 + PyYAML)
  3. A Pandoc binary

No other state is required. The templates, CSS, and JS are all in the repository. KaTeX is bundled locally after ./setup.sh.

See On Writing for the Long Term for the philosophy behind these choices.

Backlinks