diff --git a/.github/workflows/zensical.yml b/.github/workflows/zensical.yml new file mode 100644 index 00000000..31c9216c --- /dev/null +++ b/.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 diff --git a/CLAUDE.md b/CLAUDE.md index 63d1ace0..3f8bc3c2 100644 --- a/CLAUDE.md +++ b/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 diff --git a/mkdocs.yml b/mkdocs.yml index 1c58d22d..69437330 100644 --- a/mkdocs.yml +++ b/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 diff --git a/requirements-zensical.txt b/requirements-zensical.txt new file mode 100644 index 00000000..9fe971be --- /dev/null +++ b/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