Skip to content

Convert docs from MkDocs to Zensical - #347

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

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

Conversation

@kattni

@kattni kattni commented Nov 6, 2026

Copy link
Copy Markdown
Contributor

Converts the toga-chart documentation build from MkDocs and Material for MkDocs to Zensical, using Zensical-native configuration.

This depends on beeware/beeware-docs-tools#288. docs-tools is temporarily pinned to that PR's branch (kattni/beeware-docs-tools@tooling/zensical-migration) in the docs dependency group; the pin will be reverted to beeware/main once #288 is merged.

Changes

  • docs/config.yml and docs/mkdocs.en.yml are replaced by docs/zensical.toml and docs/zensical.en.toml, generated with docs-tools' convert_mkdocs_config. Its equivalence check reported the converted configuration as equivalent to the YAML (the only note was the order of the Markdown extensions).
  • docs/en/SUMMARY.md (literate-nav) is replaced by the native nav setting in docs/zensical.toml. New pages now need to be added to nav by hand.
  • pyproject.toml: docs-tools pinned to the migration branch (temporary), and docs/en/SUMMARY.md removed from the rumdl exclude list.
  • tox.ini: removed the MkDocs-only DISABLE_MKDOCS_2_WARNING / NO_MKDOCS_2_WARNING settings, and the --source-code arguments, which docs-tools now ignores.
  • .gitignore: ignores the generated docs/_build.*.toml files.

Verification

  • tox -r -e docs,docs-lint builds in strict mode with no issues, and the spelling check passes.
  • Compared with a MkDocs build of main:
    • The same 38 pages, with identical titles, heading ids, sidebar, tabs and footer navigation.
    • Article text is identical on 32 pages. The other 6 are contribution-guide pages from docs-tools' shared content, which now describes editing nav in zensical.toml instead of SUMMARY.md, and refers to Zensical instead of MkDocs.
    • The API reference (toga_chart.Chart) renders identically, and objects.inv, sitemap.xml and the images are byte-identical.
    • Visually the same in light and dark mode, apart from Zensical's more compact search box.

Notes for reviewers

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)

Generated with docs-tools' convert_mkdocs_config: docs/config.yml and
docs/mkdocs.en.yml become docs/zensical.toml and docs/zensical.en.toml, and
the literate-nav SUMMARY.md becomes the native nav setting.
Drop the MkDocs 2 warning environment variables and the --source-code
arguments (now ignored by docs-tools) from tox, and ignore the generated
docs/_build.*.toml files.
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