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..383ccad4 100644 --- a/.readthedocs.yml +++ b/.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/ 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