From 42de753587cc5894f282df7ec2a2d0e5654e83e2 Mon Sep 17 00:00:00 2001 From: tastybento Date: Sun, 6 Sep 2026 17:27:56 -0700 Subject: [PATCH 1/2] chore: switch the Read the Docs build to Zensical Material for MkDocs reaches end of life on 2026-11-05. Zensical was trialled in #102 (same mkdocs.yml, native macros, classic theme variant) and the output matches the MkDocs build, so production moves over. - .readthedocs.yml: Python 3.12, install requirements-zensical.txt, run zensical build and copy site/ to the output directory, following the official Read the Docs Zensical guide. - mkdocs.yml: explicit site_url, since Zensical cannot read READTHEDOCS_CANONICAL_URL. - CLAUDE.md, requirements-zensical.txt, workflow comments updated; requirements.txt and the mkdocs: fallback are documented for rollback. Known difference: the "last updated" line from git-revision-date-localized is no longer shown, as Zensical does not support that plugin yet. Co-Authored-By: Claude Fable 5.1 Claude-Session: https://claude.ai/code/session_01AtaKe95zrGF2Do7h3FfNBS --- .github/workflows/zensical.yml | 6 ++---- .readthedocs.yml | 29 ++++++++++++++++++----------- CLAUDE.md | 24 ++++++++---------------- mkdocs.yml | 2 ++ requirements-zensical.txt | 5 +++-- 5 files changed, 33 insertions(+), 33 deletions(-) diff --git a/.github/workflows/zensical.yml b/.github/workflows/zensical.yml index 31c9216c..68b2919a 100644 --- a/.github/workflows/zensical.yml +++ b/.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: diff --git a/.readthedocs.yml b/.readthedocs.yml index 4841a742..db0833d6 100644 --- a/.readthedocs.yml +++ b/.readthedocs.yml @@ -1,22 +1,29 @@ # .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 and point +# python.install at 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" + python: "3.12" + jobs: + 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/ -# 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 + - requirements: requirements-zensical.txt diff --git a/CLAUDE.md b/CLAUDE.md index 3f8bc3c2..3b8a8126 100644 --- a/CLAUDE.md +++ b/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 diff --git a/mkdocs.yml b/mkdocs.yml index 69437330..2025615b 100644 --- a/mkdocs.yml +++ b/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 diff --git a/requirements-zensical.txt b/requirements-zensical.txt index 9fe971be..54578c01 100644 --- a/requirements-zensical.txt +++ b/requirements-zensical.txt @@ -1,4 +1,4 @@ -# 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. # @@ -6,7 +6,8 @@ # .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 From 55a4a1571363a8d2235d4b8d3d93bc3043612aac Mon Sep 17 00:00:00 2001 From: tastybento Date: Sun, 6 Sep 2026 17:31:30 -0700 Subject: [PATCH 2/2] fix(rtd): install Zensical via build.jobs.install python.install is only run for sphinx/mkdocs builds, so with build.jobs alone the zensical command was not found on Read the Docs. Co-Authored-By: Claude Fable 5.1 Claude-Session: https://claude.ai/code/session_01AtaKe95zrGF2Do7h3FfNBS --- .readthedocs.yml | 11 +++++------ 1 file changed, 5 insertions(+), 6 deletions(-) diff --git a/.readthedocs.yml b/.readthedocs.yml index db0833d6..383ccad4 100644 --- a/.readthedocs.yml +++ b/.readthedocs.yml @@ -6,8 +6,8 @@ # 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 and point -# python.install at requirements.txt. +# To fall back to MkDocs, restore the `mkdocs:` section, drop build.jobs and +# use python.install with requirements.txt. version: 2 @@ -16,6 +16,9 @@ build: tools: 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 @@ -23,7 +26,3 @@ build: # Copy the built site into the directory Read the Docs publishes. - mkdir -p $READTHEDOCS_OUTPUT/html/ - cp --recursive site/* $READTHEDOCS_OUTPUT/html/ - -python: - install: - - requirements: requirements-zensical.txt