docs: migrate from MkDocs to Zensical and adopt the shared theme (#353)

* docs: add zensical.toml alongside mkdocs.yml

Additive step of the MkDocs -> Zensical migration; both generators
build at this commit and the toolchain cutover follows.

Every key from mkdocs.yml was reconciled by hand rather than trusting
the build: Zensical silently ignores unknown config keys even under
--strict, so a clean build proves nothing about the translation.

Adopts the shared stridelabs-docs-theme instead of carrying the look
across -- theme.palette, theme.font and theme.features are dropped
because the theme owns them, so restyling the fleet becomes a version
bump rather than an edit in every repo. theme.icon.logo is kept: it is
what identifies this project beside the shared owl.

Working notes previously withheld via MkDocs exclude_docs move to
discovery/ at the repo root. Zensical has no exclude_docs equivalent
and would have published them.

.gitignore picks up Zensical's root-level /.cache/ (anchored, matching
the file's existing convention).

* docs: cut over from MkDocs to Zensical

Atomic cutover: dependency group, lockfile, both workflows, the Makefile
targets and the removal of mkdocs.yml land together, so no commit has
docs CI or `make docs` pointing at a config that does not exist.

Dependencies: mkdocs, mkdocs-material and pymdown-extensions are dropped
for zensical plus the shared stridelabs-docs-theme (git dependency
pinned to v0.2.2 -- a public repo rather than a registry, so PRs from
forks and local clones can still build docs). pymdown-extensions now
arrives transitively; pinning it twice invites conflicts.
`grep -c mkdocs uv.lock` is 0.

Workflows: adds Docs PR Build, which did not exist -- docs previously
built only on push to main and without --strict, so a broken link or
anchor could land on main and be caught at deploy time or not at all.
Both workflows now build --strict and watch uv.lock, so a theme bump
redeploys. Action pins bumped and each ref verified through the git refs
API; setup-uv is pinned to v9.0.0 because it publishes no moving v9 tag
and actionlint does not catch that.

`make docs` / `make docs-serve` now use --locked, matching CI: the theme
tag is mutable, so the lockfile's resolved commit SHA is the real
integrity check.

--strict required a small content fix that MkDocs had been warning about
without failing: out-of-tree links to tools/, linux/, and packaging/
became GitHub blob URLs, and the DL-12 heading anchor gained the date
suffix that the generated id actually uses.

Verified with the locked toolchain: identical 27-page set and all 374
heading anchors preserved, theme markup present, appcast.xml still
copied through, and zero requests to Google Fonts.

Author: charliek

.github/workflows/docs-pr.yml

@@ -0,0 +1,31 @@
+name: Docs PR Build
+
+on:
+  pull_request:
+    paths:
+      - 'docs/**'
+      - 'zensical.toml'
+      - 'pyproject.toml'
+      - 'uv.lock'
+      - '.github/workflows/docs-pr.yml'
+
+permissions:
+  contents: read
+
+concurrency:
+  group: docs-pr-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+    steps:
+      - uses: actions/checkout@v7
+        with:
+          persist-credentials: false
+      # setup-uv publishes no moving major tag -- v9 does not resolve.
+      - uses: astral-sh/setup-uv@v9.0.0
+      - run: uv python install 3.13
+      - run: uv sync --locked --group docs
+      - run: uv run --locked zensical build --strict

.github/workflows/docs.yml

@@ -5,8 +5,9 @@ on:
     branches: [main]
     paths:
       - 'docs/**'
-      - 'mkdocs.yml'
+      - 'zensical.toml'
       - 'pyproject.toml'
+      - 'uv.lock'
       - '.github/workflows/docs.yml'
   workflow_dispatch:
 
@@ -23,13 +24,14 @@ jobs:
   build:
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@v6
+      - uses: actions/checkout@v7
         with:
           persist-credentials: false
-      - uses: astral-sh/setup-uv@v7
+      # setup-uv publishes no moving major tag -- v9 does not resolve.
+      - uses: astral-sh/setup-uv@v9.0.0
       - run: uv python install 3.13
-      - run: uv sync --group docs
-      - run: uv run mkdocs build
+      - run: uv sync --locked --group docs
+      - run: uv run --locked zensical build --strict
       - uses: actions/upload-pages-artifact@v5
         with:
           path: site-build
@@ -41,5 +43,6 @@ jobs:
     runs-on: ubuntu-latest
     needs: build
     steps:
-      - id: deployment
+      - name: Deploy to GitHub Pages
+        id: deployment
         uses: actions/deploy-pages@v5

.gitignore

@@ -5,6 +5,10 @@
 /build/ghostty-src/
 /site-build/
 
+# Zensical differential-build cache (root only -- the anchor keeps this
+# from also swallowing a nested .cache/ elsewhere in the tree)
+/.cache/
+
 # Rust workspace
 /target/
 **/*.rs.bk

CHANGELOG.md

@@ -9,6 +9,43 @@ builds the DMG + `.deb`s and publishes to the apt repo. Bump
 `[workspace.package].version` in `Cargo.toml` to match before tagging (the
 release workflow asserts they agree).
 
+## Unreleased
+
+### Changed
+
+- **Docs site migrated from Material for MkDocs to
+  [Zensical](https://zensical.org)**, the successor from the same team.
+  Material entered maintenance mode in November 2025 and now warns on every
+  build that MkDocs 2.0 will remove the plugin and theming systems with no
+  migration path. `mkdocs.yml` is replaced by a native `zensical.toml`;
+  documentation content is unchanged aside from a handful of links that
+  `--strict` now validates (out-of-tree paths became GitHub blob URLs; one
+  stale heading anchor was corrected).
+
+  The look now comes from the shared
+  [stridelabs-docs-theme](https://github.com/charliek/stridelabs-docs-theme)
+  package rather than per-repo config, so restyling every site is a version
+  bump instead of an edit in each repo. Fonts are self-hosted by the theme, so
+  the site no longer requests anything from `fonts.googleapis.com` or
+  `fonts.gstatic.com`.
+
+  Working notes previously withheld via MkDocs `exclude_docs` moved to
+  `discovery/` at the repo root — Zensical has no equivalent, and leaving
+  them under `docs/` would have published them.
+
+  Verified against the pre-migration build: identical 27-page set and all
+  374 heading anchors preserved, so existing deep links still resolve.
+  `docs/appcast.xml` still copies through to the published site. Page
+  `<title>` now derives from the page `<h1>` rather than the nav label, which
+  is the one intentional difference.
+
+### Added
+
+- **`Docs PR Build` workflow.** Docs previously built only on push to `main`,
+  and without `--strict`, so a broken link or heading anchor could land on
+  `main` and be caught at deploy time or not at all. Both workflows now build
+  `--strict` and watch `uv.lock`.
+
 ## v0.0.17 — 2026-07-31
 
 Agents move out of the palette and into the sidebar. Every running agent now

CLAUDE.md

@@ -241,6 +241,44 @@ wrapper small.
     and before the single-instance lock, so it never touches a running
     instance.
 
+## Docs
+
+**Not part of `make check` or the `ci-success` gate.** The docs site has
+its own toolchain (uv/Python) and its own CI workflows; the Rust/Swift
+gates do not cover it. Run it for commits touching `docs/`,
+`zensical.toml`, `pyproject.toml`, `uv.lock`, or either docs workflow —
+both workflows trigger on those shared inputs (and each additionally on
+its own file), because a dependency or lockfile change can break the
+build just as easily as a content change:
+
+```bash
+make docs            # uv run --locked zensical build --strict
+make docs-serve      # preview on http://127.0.0.1:7070
+```
+
+The site is [Zensical](https://zensical.org) (not MkDocs — migrated 2026-08),
+configured in `zensical.toml`, built into `site-build/`. `--strict` fails
+on broken links and anchors and is what both CI workflows run, so run it
+locally before pushing docs changes. Note `zensical serve --strict` is
+unsupported; verify strictness via `build`.
+
+The look comes from the shared
+[stridelabs-docs-theme](https://github.com/charliek/stridelabs-docs-theme)
+package, pinned by tag in `pyproject.toml`. Palette, fonts and feature
+toggles live there, not here — do not add `theme.palette`, `theme.features`,
+or a `[project.theme.font]` table to `zensical.toml`. The last is the
+sharp edge: it re-enables Zensical's Google Fonts `<link>` on every page
+while the theme's self-hosted faces keep loading anyway.
+
+Working notes in `discovery/` live outside `docs/` on purpose. Zensical
+has no `exclude_docs` equivalent; files under `docs_dir` are published.
+
+Two gotchas worth knowing: Zensical **silently ignores unknown config
+keys** even under `--strict`, so a green build does not prove a config
+edit did what you meant; and the `pymdownx.emoji` callables live in the
+`zensical.extensions.emoji` namespace — the Material for MkDocs
+`material.extensions.emoji` namespace aborts the build.
+
 ## Build
 
 - libghostty-vt is pinned to a specific Ghostty commit in

Makefile

@@ -259,11 +259,11 @@ check: fmt-check clippy themes-check test  ## Pre-push gate: fmt-check + clippy
 # ---- docs -------------------------------------------------------------
 
 .PHONY: docs docs-serve
-docs:  ## Build the mkdocs site into site-build/
-	uv sync --group docs && uv run mkdocs build
+docs:  ## Build the docs site into site-build/ (same as CI)
+	uv sync --locked --group docs && uv run --locked zensical build --strict
 
-docs-serve:  ## Serve the docs locally (mkdocs serve)
-	uv sync --group docs && uv run mkdocs serve
+docs-serve:  ## Serve the docs locally with live reload
+	uv sync --locked --group docs && uv run --locked zensical serve
 
 # ---- clean ------------------------------------------------------------
 

README.md

@@ -56,7 +56,7 @@ cd mac && swift build                 # or: ./mac/scripts/bundle.sh release  →
 
 ## Documentation
 
-The full site lives under `docs/` and builds with `mkdocs-material` (`make docs-serve` → http://127.0.0.1:7070):
+The full site lives under `docs/` and builds with [Zensical](https://zensical.org) (`make docs-serve` → http://127.0.0.1:7070):
 
 - [Installation](docs/getting-started/installation.md) — toolchain + build
 - [First Run](docs/getting-started/first-run.md) — launch behavior + where state lives

RELEASING.md

@@ -176,7 +176,7 @@ Inspect or edit at https://github.com/charliek/roost/rules.
 ## The appcast lives where
 
 The Sparkle appcast is at `docs/appcast.xml`, served by GitHub Pages from
-`https://charliek.github.io/roost/appcast.xml` via `docs.yml`'s mkdocs
+`https://charliek.github.io/roost/appcast.xml` via `docs.yml`'s Zensical
 deploy. The `appcast` job mutates that file in place, commits it as the
 release-bot, and pushes to main; `docs.yml` redeploys Pages shortly after.
 

docs/discovery/README.md discovery/README.mddocs/discovery/README.md renamed to discovery/README.md

@@ -1,8 +1,8 @@
 # Discovery notes
 
-Working notes, not product commitments. `mkdocs.yml` lists this
-folder under `exclude_docs`, so it is not in the nav and is not
-built into the public site.
+Working notes, not product commitments. These files live outside
+`docs/` so they are not built into the public site — Zensical has
+no equivalent of MkDocs `exclude_docs`.
 
 | Note | What it is |
 |---|---|