Skip to content

Migrate the documentation from MkDocs to Zensical - #111

Open
kattni wants to merge 2 commits into
beeware:mainfrom
kattni:tooling/zensical-migration
Open

kattni wants to merge 2 commits into
beeware:mainfrom
kattni:tooling/zensical-migration

Conversation

@kattni

@kattni kattni commented Nov 6, 2026 •

Copy link
Copy Markdown
Contributor

Migrates Cricket's documentation from MkDocs and Material for MkDocs to Zensical, using Zensical-native configuration.

This depends on beeware/beeware-docs-tools#288, which moves the shared docs build to Zensical. Until that PR merges, beeware-docs-tools is temporarily pinned to its branch (kattni/beeware-docs-tools@tooling/zensical-migration). The pin will be reverted to beeware/main once beeware/beeware-docs-tools#288 is merged.

Changes

  • docs/config.yml, docs/mkdocs.en.yml and docs/en/SUMMARY.md are replaced by docs/zensical.toml and docs/zensical.en.toml, generated with the docs-tools converter. The literate-nav SUMMARY.md is now a native nav setting in docs/zensical.toml, so new pages are added there.
  • tox.ini: removed the MkDocs-only DISABLE_MKDOCS_2_WARNING and NO_MKDOCS_2_WARNING environment variables.
  • pyproject.toml: temporary docs-tools pin (see above), and the docs/en/SUMMARY.md rumdl exclusion removed.
  • .gitignore: ignores the docs/_build.*.toml files that docs-tools generates during a build.

Verification

The strict Zensical build (tox -e docs) passes with no issues. Compared against a MkDocs build of main:

  • Same 37 pages, with identical titles, sidebar navigation, tabs and footer links.
  • Article text is identical on 32 pages. The other 5 are shared contribution-guide pages whose content comes from docs-tools, which now describes nav in zensical.toml instead of SUMMARY.md, and Zensical instead of MkDocs.
  • objects.inv and the image are identical.
  • The pages look the same in light and dark mode. The only visible difference is Zensical's more compact search button.

Notes for reviewers

  • The pymdownx.magiclink repo setting is "website", so a bare issue reference in Cricket's docs links to the website repository rather than Cricket. This predates the migration and is unchanged here.
  • mkdocstrings is configured, but no page currently uses it (there are no API reference pages). It's kept as is.

PR Checklist:

  • I will abide by the BeeWare Code of Conduct
  • I have read and have followed the CONTRIBUTING.md file
  • This PR was generated or assisted using an AI tool

Assisted-by: Claude Code (Claude Opus 5.5)

Convert docs/config.yml, docs/mkdocs.en.yml and docs/en/SUMMARY.md into
Zensical-native docs/zensical.toml and docs/zensical.en.toml, with the
navigation as a native nav setting, using the docs-tools converter.

Remove the MkDocs 2 warning environment variables from tox.ini, drop the
SUMMARY.md rumdl exclusion, and ignore the generated docs/_build.*.toml
files.

Temporarily pin beeware-docs-tools to the Zensical migration branch.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant