From 18d6507d2f3a9dba03d90e6d20cfc993401c520a Mon Sep 17 00:00:00 2001 From: tastybento Date: Sun, 6 Sep 2026 16:40:51 -0700 Subject: [PATCH] chore: add Zensical trial build alongside MkDocs Material for MkDocs reaches end of life on 2026-11-05. Zensical, from the same team, reads the existing mkdocs.yml and runs the main.py macros natively, so this repo can be built with either tool from one config. - requirements-zensical.txt: zensical pinned (pre-1.0) plus PyYAML/requests for main.py; no MkDocs packages needed. - .github/workflows/zensical.yml: builds with Zensical on every push/PR and checks macros and the footer override rendered. - mkdocs.yml: theme.variant: classic keeps the Material look under Zensical; MkDocs passes the key through unchanged (verified with a strict build). - CLAUDE.md: document the dual build and the one known gap (git-revision-date-localized is not supported by Zensical). Production on Read the Docs is unchanged and still builds with MkDocs. Co-Authored-By: Claude Fable 5.1 Claude-Session: https://claude.ai/code/session_01AtaKe95zrGF2Do7h3FfNBS --- .github/workflows/zensical.yml | 40 ++++++++++++++++++++++++++++++++++ CLAUDE.md | 12 ++++++++++ mkdocs.yml | 3 +++ requirements-zensical.txt | 12 ++++++++++ 4 files changed, 67 insertions(+) create mode 100644 .github/workflows/zensical.yml create mode 100644 requirements-zensical.txt 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