Every developer eventually builds their own static site generator. It’s a rite of passage — like writing a to-do app, but with more opinions about Markdown parsers.

The Architecture

The generator follows a simple pipeline:

  1. Parse — Read Markdown files, extract YAML frontmatter
  2. Load — Walk content directories, build a typed site model
  3. Render — Execute Go templates with the site data
  4. Write — Output HTML (and Markdown source) to the public directory

Each step is its own package. The builder orchestrates them in sequence.

Content Organisation

Content lives in two directories:

  • content/posts/ — Blog posts with dates, tags, and descriptions
  • content/pages/ — Static pages (about, contact) that appear in the navigation

Posts get rendered to /posts/{slug}/, while pages render at the root level — so about.md becomes /about/.

Tags

Tags are collected from post frontmatter during the load phase. The loader:

  1. Gathers all unique tag names across posts
  2. Sorts them alphabetically
  3. Assigns colours from a palette, cycling through coral, amber, teal, and dusty blue
  4. Generates index pages at /tags/ and /tags/{slug}/

Markdown for LLMs

Every HTML page has a companion index.md file containing the raw Markdown source. The HTML head includes a <link rel="alternate" type="text/markdown"> tag pointing to it, making the content easily discoverable by AI systems.