Add Zola-based documentation site with essays and solutions

[alycda]

Summary

This PR introduces a static documentation site built with Zola, publishing the repository's essays and solutions as a browsable website. The site is authored in plain markdown with YAML frontmatter in docs/, then translated to Zola's format at build time via a Python collector script. The site is published to GitHub Pages via a new CI workflow.

Key Changes

• Site infrastructure (site/)

  • config.toml: Zola configuration with taxonomies for tags and categories
  • sass/main.scss: Complete stylesheet with warm, paper-like aesthetic and dark mode support
  • templates/: Base layout, essay/solution/section/taxonomy templates, and shared macros
  • bin/collect.py: Python script that translates docs/ markdown + YAML into Zola's TOML format and renders CONCEPTS.md into a data file for entity references

• Documentation sources (docs/)

  • essays/_index.md and solutions/_index.md: Section landing pages
  • essays/the-same-bug-three-times.md: Example essay demonstrating the [E01]-style entity reference system

• CI/CD (.github/workflows/pages.yml)

  • Builds site on pushes to main/master and PRs
  • Runs collector and Zola build
  • Deploys to GitHub Pages on main/master only

• Build integration (justfile)

  • docs-collect: Regenerate site content from sources
  • docs-build: Full site build
  • docs-serve: Local development server with live reload
  • docs-fonts: Instructions for optional webfont vendoring

• Documentation (CLAUDE.md)

  • Added section explaining the docs site architecture and collector behavior
  • Clarified that site/content/ and site/data/ are build artifacts, never edited by hand

Implementation Details

Design philosophy: The site reads like "something a person wrote" rather than generated documentation. It uses serif fonts for prose, a single narrow column, and a warm paper-like color scheme with dark mode support.

Collector behavior: Rather than reformatting sources to suit Zola, collect.py translates them on the way in:

• Converts YAML frontmatter to TOML under +++
• Flattens nested solution directories into a flat list with category taxonomy
• Strips redundant leading H1s that restate the title
• Renders CONCEPTS.md into data/concepts.toml for entity reference resolution

Entity references: Essays can declare concepts: in frontmatter to reference shared vocabulary. The {{ e(name="...") }} shortcode resolves these to [E01]-style links in the rendered output, with definitions displayed at the end of each essay.

Gitignore: site/content/, site/data/, and site/public/ are marked as build artifacts and ignored.

https://claude.ai/code/session_01X7JLHmbox2A7tpyCU5HqvB

[github-actions]

⊕ Entity-level changes

.github/workflows/pages.yml

Status	Type	Name
+	property	name
+	section	on
+	section	permissions
+	section	concurrency
+	section	jobs

.gitignore

Status	Type	Name
Δ	chunk	lines 1-20
-	chunk	lines 21-36
+	chunk	lines 21-40
+	chunk	lines 41-45

CLAUDE.md

Status	Type	Name
Δ	heading	Repository Structure
+	heading	The docs site (site/, published to GitHub Pages)
Δ	heading	Meta: Updating This Document

docs/essays/_index.md

Status	Type	Name
+	preamble	(preamble)

docs/essays/the-same-bug-three-times.md

Status	Type	Name
+	preamble	(preamble)
+	heading	What I thought the boundary was
+	heading	Why the obvious fix does not generalise
+	heading	The part I keep relearning

docs/solutions/_index.md

Status	Type	Name
+	preamble	(preamble)

flake.nix

Status	Type	Name
Δ	binding	outputs

justfile

Status	Type	Name
Δ	chunk	lines 81-100
+	chunk	lines 101-120
↻ Δ	chunk	lines 101-115 -> lines 121-138

site/bin/collect.py

Status	Type	Name
+	orphan	module-level
+	function	toml_value
+	function	split_frontmatter
+	function	to_zola_frontmatter
+	function	humanize
+	function	strip_leading_h1
+	function	collect_page
+	function	parse_concepts
+	function	write_concepts
+	function	main
+	orphan	module-level

site/config.toml

Status	Type	Name
+	orphan	module-level
+	property	base_url
+	property	title
+	property	description
+	property	compile_sass
+	property	build_search_index
+	property	generate_feeds
+	property	feed_filenames
+	property	taxonomies
+	property	{ name
+	property	{ name
+	section	markdown
+	property	markdown.highlighting
+	section	extra

site/sass/main.scss

Status	Type	Name
+	chunk	lines 1-20
+	chunk	lines 21-40
+	chunk	lines 41-60
+	chunk	lines 61-80
+	chunk	lines 81-100
+	chunk	lines 101-120
+	chunk	lines 121-140
+	chunk	lines 141-160
+	chunk	lines 161-180
+	chunk	lines 181-200
+	chunk	lines 201-220
+	chunk	lines 221-240
+	chunk	lines 241-260
+	chunk	lines 261-280
+	chunk	lines 281-300
+	chunk	lines 301-320
+	chunk	lines 321-340
+	chunk	lines 341-360
+	chunk	lines 361-374

site/templates/base.html

Status	Type	Name
+	orphan	module-level
+	element	title
+	orphan	module-level
+	element	body
+	element	a
+	element	header
+	element	a
+	element	nav
+	element	a
+	element	a
+	element	a
+	element	a
+	element	main
+	element	footer
+	element	div
+	element	h2
+	element	ul
+	element	li
+	element	a
+	element	li
+	element	a
+	element	li
+	element	a
+	element	li
+	element	a
+	element	p
+	element	a
+	element	code
+	orphan	module-level

site/templates/concepts.html

Status	Type	Name
+	chunk	lines 1-20
+	chunk	lines 21-36

site/templates/essay.html

Status	Type	Name
+	chunk	lines 1-20
+	chunk	lines 21-40
+	chunk	lines 41-60
+	chunk	lines 61-64

site/templates/index.html

Status	Type	Name
+	chunk	lines 1-20
+	chunk	lines 21-40
+	chunk	lines 41-42

site/templates/macros/bits.html

Status	Type	Name
+	chunk	lines 1-20
+	chunk	lines 21-40
+	chunk	lines 41-60
+	chunk	lines 61-62

site/templates/section.html

Status	Type	Name
+	chunk	lines 1-20

site/templates/shortcodes/e.html

Status	Type	Name
+	chunk	lines 1-12

site/templates/solution.html

Status	Type	Name
+	chunk	lines 1-20
+	chunk	lines 21-40
+	chunk	lines 41-53

site/templates/taxonomy_list.html

Status	Type	Name
+	chunk	lines 1-20

site/templates/taxonomy_single.html

Status	Type	Name
+	chunk	lines 1-20
+	chunk	lines 21-22

Summary: 109 added, 6 modified, 1 deleted, 1 renamed across 21 files (6 added orphans)

_{functions and classes, not lines · sem}