---
title: "Building a Static Site Generator in Go"
date: 2026-04-11
description: "A walkthrough of the design decisions behind this site's custom Go static site generator."
tags: [go, ssg, meta]
author: "Mark"
---

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.