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.11"
-
-# 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,17 +4,17 @@ This file provides guidance to Claude Code (claude.ai/code) when working with co
 
 ## What this repo is
 
-Chinese translation of the BentoBoxWorld documentation site. It is an MkDocs (Material theme) project that publishes the user-facing docs for BentoBox, its game modes, and its addons. The English source lives at https://github.com/BentoBoxWorld/docs — this repo mirrors that structure with content translated into Chinese. The current working branch is typically `update/sync-with-english`, which is used to pull new English content over and translate it.
+Chinese translation of the BentoBoxWorld documentation site. It is a [Zensical](https://zensical.org) project (the successor to Material for MkDocs; it reads the MkDocs-style `mkdocs.yml`) that publishes the user-facing docs for BentoBox, its game modes, and its addons. The English source lives at https://github.com/BentoBoxWorld/docs — this repo mirrors that structure with content translated into Chinese. The current working branch is typically `update/sync-with-english`, which is used to pull new English content over and translate it.
 
 ## Common commands
 
 ```bash
-pip install -r requirements.txt    # install MkDocs + plugins (pinned old versions, see note below)
-mkdocs serve                       # local preview at http://127.0.0.1:8000
-mkdocs build                       # build static site into ./site
+pip install -r requirements-zensical.txt    # Python 3.10+; installs Zensical (no MkDocs packages needed)
+zensical serve                       # local preview at http://localhost:8000
+zensical build                       # build static site into ./site
 ```
 
-Note: `requirements.txt` pins fairly old versions (mkdocs 1.3.0, mkdocs-material 8.2.15, macros 0.6.0). If installing fresh, use a venv to avoid conflicts with system packages.
+Note: `requirements.txt` is the MkDocs fallback (`pip install -r requirements.txt && mkdocs build`); Zensical reads the same `mkdocs.yml`. Read the Docs runs `zensical build` on Python 3.12 (see `.readthedocs.yml`), and `.github/workflows/zensical.yml` runs the same build on every push and PR. Zensical does not support the `git-revision-date-localized` plugin, so the "last updated" line is not shown.
 
 ## 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/zh-cn/latest/
 copyright: "© Copyright 2017-2026 tastybento and the BentoBoxWorld community (CC-BY 4.0)."
 repo_url: https://github.com/BentoBoxWorld/BentoBox
 repo_name: BentoBoxWorld/BentoBox
@@ -89,6 +91,8 @@ nav:
 theme:
   name: material
   custom_dir: overrides
+  # Zensical-only: keep the Material for MkDocs look. MkDocs passes unknown theme keys through.
+  variant: classic
   palette:
     scheme: slate
     primary: deep orange

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