docs: migrate from MkDocs to Zensical (#144)

.github/workflows/docs.yml

@@ -36,7 +36,7 @@ jobs:
       - name: Sync deps (runtime + docs)
         run: uv sync --frozen --group docs
       - name: Build site (strict)
-        run: uv run mkdocs build --strict
+        run: uv run zensical build --strict
       - name: Upload Pages artifact
         if: github.ref_type == 'tag'
         uses: actions/upload-pages-artifact@v5

.gitignore

@@ -33,7 +33,7 @@ venv/
 # Local-only design notes (kept out of git history)
 docs/superpowers/
 
-# mkdocs
+# docs build output
 site/
 
 # git worktrees

docs/contributing/release-process.md

@@ -11,7 +11,7 @@ on a `chore/release-X.Y.Z` feature branch, gets PR-merged into `main`,
 and only then is `vX.Y.Z` tagged on the resulting merge commit.
 
 The same `v*` tag push also publishes the documentation site.
-`docs.yml` runs build-only (`mkdocs build --strict`) on docs-touching
+`docs.yml` runs build-only (`zensical build --strict`) on docs-touching
 pull requests, but the GitHub Pages **deploy** job only runs on a `v*`
 tag push — the live docs site updates on release, not on merge to
 `main`.

justfile

@@ -54,10 +54,10 @@ e2e:
         docker compose -f tests/e2e/docker-compose.yml down -v; \
         exit $rc
 
-# Serve the MkDocs site locally at http://127.0.0.1:8000
+# Serve the docs site locally at http://127.0.0.1:8000 (preview only)
 docs:
-    uv run mkdocs serve
+    uv run zensical serve
 
-# Build the MkDocs site (strict mode — fails on broken links, missing nav targets, etc.)
+# Build the docs site (strict mode — fails on broken links, missing anchors, etc.)
 docs-build:
-    uv run mkdocs build --strict
+    uv run zensical build --strict

pyproject.toml

@@ -78,8 +78,7 @@ dev = [
     "types-PyYAML>=6.0",
 ]
 docs = [
-    "mkdocs>=1.6",
-    "mkdocs-material>=9.5",
+    "zensical>=0.0.38",
     "pyyaml>=6.0",
 ]
 

scripts/gen_docs.py

@@ -1,4 +1,4 @@
-"""Generate the four auto-generated reference pages for the MkDocs site.
+"""Generate the four auto-generated reference pages for the docs site.
 
 Usage:
     python scripts/gen_docs.py             # write the pages