Build the docs with Zensical instead of mkdocs-material

.github/workflows/docs.yaml

@@ -16,23 +16,30 @@ concurrency:
   group: docs
   cancel-in-progress: false
 
+# The site is published with GitHub Pages' own deployment, so Pages must be set to "GitHub Actions"
+# under Settings > Pages.
 permissions:
-  contents: write
+  contents: read
+  pages: write
+  id-token: write
 
 jobs:
   deploy:
     runs-on: ubuntu-latest
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
     steps:
       - uses: actions/checkout@v7
-      - name: Configure Git Credentials
-        run: |
-          git config user.name github-actions[bot]
-          git config user.email 41898282+github-actions[bot]@users.noreply.github.com
       - name: Install uv
         uses: astral-sh/setup-uv@v10.3.0
         with:
           enable-cache: true
-      - name: Build and deploy
-        run: uv run --locked --only-group docs mkdocs gh-deploy --force
-        env:
-          MKDOCS_GIT_COMMITTERS_APIKEY: ${{ github.token }}
+      - uses: actions/configure-pages@v6
+      - name: Build
+        run: uv run --locked --only-group docs zensical build --clean --strict
+      - uses: actions/upload-pages-artifact@v5
+        with:
+          path: site
+      - uses: actions/deploy-pages@v5
+        id: deployment

Makefile

@@ -36,7 +36,7 @@ lint:
 	uv run mypy tests
 
 docs-serve:
-	uv run --group docs mkdocs serve
+	uv run --group docs zensical serve
 
 # docs/reference/*.md are generated from the click commands, the manifest models and examples/.
 docs-generate:
@@ -47,7 +47,7 @@ docs-check:
 	uv run python scripts/docs.py check
 
 docs-build: docs-check
-	uv run --group docs mkdocs build --strict
+	uv run --group docs zensical build --clean --strict
 
 # examples/generated/*.py are what cliffy generates for the manifests in examples/. Nothing is installed or
 # loaded for this: the manifests are only rendered. tests/test_examples.py fails when a file is stale.

docs/project/contributing.md

@@ -76,7 +76,7 @@ then run `make generate-schema` and `make docs-generate`.
 
 ## Working on the documentation
 
-The site is built with [MkDocs Material](https://squidfunk.github.io/mkdocs-material/) from the
+The site is built with [Zensical](https://zensical.org/) from the
 `docs/` directory. The build is strict: a broken link or a missing file is an error.
 
 ### Generated pages

mkdocs.yaml

@@ -46,6 +46,8 @@ nav:
 
 theme:
   name: material
+  # Zensical's classic variant keeps the look of Material for MkDocs.
+  variant: classic
   icon:
     logo: fontawesome/solid/mountain
     repo: fontawesome/brands/github
@@ -80,11 +82,6 @@ theme:
 
 plugins:
   - search
-  # Looks up page contributors through the GitHub API, so it only runs in CI.
-  - git-committers:
-      repository: jaykv/cliffy
-      branch: main
-      enabled: !ENV [CI, false]
 
 markdown_extensions:
   - admonition

pyproject.toml

@@ -78,10 +78,8 @@ dev = [
     "types-pyyaml>=6.0.12",
 ]
 docs = [
-    "mkdocs-git-committers-plugin-2>=2.5.0",
-    "mkdocs-literate-nav>=0.6.2",
-    "mkdocs-material>=9.6.0",
     "pymdown-extensions>=10.14",
+    "zensical>=0.0.70",
 ]
 
 [tool.ruff]