chore: switch the Read the Docs build to Zensical

.github/workflows/zensical.yml

@@ -1,7 +1,5 @@
-# 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.
+# 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:

.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,36 +4,28 @@ This file provides guidance to Claude Code (claude.ai/code) when working with co
 
 ## Overview
 
-This is the source repository for the BentoBox main documentation site at **https://docs.bentobox.world**. It is built with [MkDocs](https://www.mkdocs.org/) using the Material theme. When commits are pushed to the `master` branch, [ReadTheDocs.org](https://readthedocs.org/) automatically pulls the changes, builds the site, and publishes the updated documentation live within minutes.
+This is the source repository for the BentoBox main documentation site at **https://docs.bentobox.world**. It is built with [Zensical](https://zensical.org), the successor to Material for MkDocs, which reads the MkDocs-style `mkdocs.yml`. When commits are pushed to the `master` branch, [ReadTheDocs.org](https://readthedocs.org/) automatically pulls the changes, builds the site, and publishes the updated documentation live within minutes.
 
 ## Commands
 
 ### Local Development
 
 ```bash
-# Install dependencies
-pip install -r requirements.txt
+# Install dependencies (Python 3.10+ required)
+pip install -r requirements-zensical.txt
 
 # Serve locally with live reload
-mkdocs serve
+zensical serve
 
 # Build static site
-mkdocs build
+zensical 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.
+The local server runs at `http://localhost:8000` by default. `.github/workflows/zensical.yml` runs the same build on every push and PR.
 
-```bash
-# Python 3.10+ required
-pip install -r requirements-zensical.txt
-zensical serve   # or: zensical build
-```
+### MkDocs fallback
 
-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).
+Material for MkDocs reaches end of life on 2026-11-05, but the repo stays buildable with it: `pip install -r requirements.txt && mkdocs build`. Zensical reads the same `mkdocs.yml`. Differences: Zensical does not support the `git-revision-date-localized` plugin (so no "last updated" line), and `theme.variant: classic` is only read by Zensical (MkDocs ignores it). To fall back on Read the Docs, restore the `mkdocs:` section in `.readthedocs.yml` and point it at `requirements.txt`.
 
 ## 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/en/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

requirements-zensical.txt

@@ -1,12 +1,13 @@
-# Alternative build with Zensical (https://zensical.org), the successor to
+# 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.
-# Production (Read the Docs) still builds with MkDocs via requirements.txt.
+# 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