chore: switch the Read the Docs build to Zensical

.github/workflows/zensical.yml

@@ -0,0 +1,38 @@
+# Builds the site with Zensical, the same tool Read the Docs uses for
+# production (see .readthedocs.yml), and checks the output is sane.
+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

.readthedocs.yml

@@ -1,22 +1,28 @@
 # .readthedocs.yml
 # Read the Docs configuration file
 # See https://docs.readthedocs.io/en/stable/config-file/v2.html for details
+#
+# The site is built with Zensical (https://zensical.org), the successor to
+# Material for MkDocs. It reads mkdocs.yml directly. Setup follows the official
+# guide: https://docs.readthedocs.com/platform/stable/intro/zensical.html
+#
+# To fall back to MkDocs, restore the `mkdocs:` section, drop build.jobs and
+# use python.install with requirements.txt.
 
-# Required
 version: 2
 
-# Set the version of Python and other tools you might need
 build:
-  os: ubuntu-22.04
+  os: ubuntu-24.04
   tools:
-    python: "3.9"
-
-# Build documentation with MkDocs
-mkdocs:
-  configuration: mkdocs.yml
-
-# We recommend specifying your dependencies to enable reproducible builds:
-# https://docs.readthedocs.io/en/stable/guides/reproducible-builds.html
-python:
-  install:
-    - requirements: requirements.txt
+    python: "3.12"
+  jobs:
+    # python.install only runs for sphinx/mkdocs builds, so install here.
+    install:
+      - pip install -r requirements-zensical.txt
+    build:
+      html:
+        - zensical build
+    post_build:
+      # Copy the built site into the directory Read the Docs publishes.
+      - mkdir -p $READTHEDOCS_OUTPUT/html/
+      - cp --recursive site/* $READTHEDOCS_OUTPUT/html/

CLAUDE.md

@@ -4,19 +4,19 @@ This file provides guidance to Claude Code (claude.ai/code) when working with co
 
 ## Repository purpose
 
-French translation of the BentoBox documentation site (a Minecraft Bukkit plugin framework). The site is built with MkDocs + Material theme and published via Read the Docs. Almost all content is Markdown under `docs/`; the rest of the repo is the build configuration and a small set of macros that generate tables at build time.
+French translation of the BentoBox documentation site (a Minecraft Bukkit plugin framework). The site is built with [Zensical](https://zensical.org) (the successor to Material for MkDocs; it reads the MkDocs-style `mkdocs.yml`) and published via Read the Docs. Almost all content is Markdown under `docs/`; the rest of the repo is the build configuration and a small set of macros that generate tables at build time.
 
 ## Common commands
 
 Use the in-repo virtualenv (`.venv/`) or install requirements first:
 
 ```bash
 pip install -r requirements.txt
-mkdocs serve     # local preview at http://127.0.0.1:8000
-mkdocs build     # output to ./site
+zensical serve     # local preview at http://localhost:8000
+zensical build     # output to ./site
 ```
 
-Read the Docs uses Python 3.9 and `mkdocs.yml` as the entry point (see `.readthedocs.yml`). There are no tests or linters.
+Read the Docs uses Python 3.12 and runs `zensical build` (see `.readthedocs.yml`); `.github/workflows/zensical.yml` runs the same build on every push and PR. `requirements.txt` is kept as the MkDocs fallback (`pip install -r requirements.txt && mkdocs build`); Zensical does not support the `git-revision-date-localized` plugin, so the "last updated" line is not shown. There are no tests or linters.
 
 ## Architecture
 

mkdocs.yml

@@ -1,4 +1,6 @@
 site_name: BentoBox World
+# Zensical cannot read READTHEDOCS_CANONICAL_URL, so the canonical URL is set explicitly.
+site_url: https://docs.bentobox.world/fr/latest/
 copyright: "© Copyright 2017-2026 tastybento et la communauté BentoBoxWorld (CC-BY 4.0)."
 repo_url: https://github.com/BentoBoxWorld/BentoBox
 repo_name: BentoBoxWorld/BentoBox
@@ -90,6 +92,8 @@ nav:
 theme:
   name: material
   custom_dir: overrides
+  # Zensical-only: keep the Material for MkDocs look. MkDocs passes unknown theme keys through.
+  variant: classic
   language: fr
   palette:
     scheme: slate

requirements-zensical.txt

@@ -0,0 +1,13 @@
+# Production 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.
+# Read the Docs installs this file (see .readthedocs.yml). requirements.txt is
+# kept as the MkDocs fallback.
+zensical==0.0.59
+PyYAML>=6.0
+requests>=2.31