chore: add Zensical trial build alongside MkDocs

.github/workflows/zensical.yml

@@ -0,0 +1,40 @@
+# Trial build with Zensical, run alongside the Read the Docs MkDocs build.
+# Zensical is the successor to Material for MkDocs (which reaches end of life
+# on 2026-11-05). This workflow keeps the repo verified against it so a later
+# switch of the production build is a config change rather than a migration.
+name: Zensical build
+
+on:
+  push:
+    branches: [master]
+  pull_request:
+  workflow_dispatch:
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+          cache: pip
+          cache-dependency-path: requirements-zensical.txt
+      - run: pip install -r requirements-zensical.txt
+      - run: zensical build
+        env:
+          # Lifts the unauthenticated GitHub rate limit used by the
+          # translations() macro in main.py.
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+      - name: Sanity-check output
+        run: |
+          test -f site/index.html
+          test -f site/addons/Level/index.html
+          # Macros must have rendered, not been passed through as text.
+          ! grep -rl '{{ *addon_description' site
+          grep -q 'md-footer-policies__link' site/FAQ/index.html
+      - uses: actions/upload-artifact@v4
+        with:
+          name: zensical-site
+          path: site
+          retention-days: 7

CLAUDE.md

@@ -23,6 +23,18 @@ mkdocs build
 
 The local server runs at `http://127.0.0.1:8000` by default.
 
+### Alternative build with Zensical (trial)
+
+[Zensical](https://zensical.org) is the successor to Material for MkDocs, which reaches end of life on 2026-11-05. It reads the same `mkdocs.yml` and runs the `main.py` macros natively. The repo is kept buildable with both tools; `.github/workflows/zensical.yml` runs a Zensical build on every push and PR. Production (Read the Docs) still uses MkDocs.
+
+```bash
+# Python 3.10+ required
+pip install -r requirements-zensical.txt
+zensical serve   # or: zensical build
+```
+
+Known differences when building with Zensical: the `git-revision-date-localized` plugin is not supported, so the "last updated" line is omitted, and `theme.variant: classic` in `mkdocs.yml` is only read by Zensical (MkDocs ignores it).
+
 ## Architecture
 
 ### Directory Structure

mkdocs.yml

@@ -90,6 +90,9 @@ nav:
 theme:
   name: material
   custom_dir: overrides
+  # Zensical-only: keep the Material for MkDocs look when building with Zensical.
+  # MkDocs passes unknown theme keys through, so this is harmless for mkdocs build.
+  variant: classic
   palette:
     scheme: slate
     primary: deep orange

requirements-zensical.txt

@@ -0,0 +1,12 @@
+# Alternative build with Zensical (https://zensical.org), the successor to
+# Material for MkDocs from the same team. Reads the same mkdocs.yml and runs
+# the macros in main.py natively, so no MkDocs packages are needed.
+#
+#   python3 -m venv .venv && .venv/bin/pip install -r requirements-zensical.txt
+#   .venv/bin/zensical build      # or: zensical serve
+#
+# Requires Python 3.10+. Zensical is pre-1.0, so the version is pinned exactly.
+# Production (Read the Docs) still builds with MkDocs via requirements.txt.
+zensical==0.0.59
+PyYAML>=6.0
+requests>=2.31