Goal
Migrate this repo's documentation from MkDocs + Material for MkDocs to
Zensical — the successor to both, built by the same
team (squidfunk). Zensical reads your existing mkdocs.yml as-is, preserves all
URLs/anchors, keeps Python-Markdown and its extensions, and gives 4–5× faster
incremental builds plus a stricter link/anchor validator.
This is a neutral, self-contained tutorial so it can be executed in a later
session without extra context.
Before you start — compatibility check
Zensical is 0.0.x. It is production-usable if the features you use are
supported. Verify before committing:
- Open
mkdocs.yml and list your plugins: and any non-standard theme.features.
- Cross-check them against the compatibility matrix:
- Vanilla Material setups (stock
theme.features, standard markdown_extensions,
no third-party plugins: beyond built-in search) migrate cleanly. If the
repo uses plugins like mkdocstrings, gen-files, awesome-pages, etc., the
module system that replaces them is not yet GA — hold off or plan around it.
Steps
-
Swap the docs dependencies. In pyproject.toml (or requirements/
poetry), remove mkdocs and mkdocs-material, add zensical (>=0.0.38).
Keep pyyaml if present.
-
Leave mkdocs.yml unchanged. Zensical consumes it natively. Do not
convert to zensical.toml — upstream advises against it for existing projects.
-
Update local build/serve commands (justfile / Makefile / scripts / docs):
mkdocs serve → zensical serve (local preview only)mkdocs build --strict → zensical build --strict (validates links and anchors)
-
Update CI. In the docs workflow (e.g. .github/workflows/docs.yml), change
the build step to uv run zensical build --strict (or pip-equivalent). The
output directory is still site/, so the Pages upload path: stays the same.
Keep the mkdocs.yml path trigger — it's still the config file.
-
Sync and build.
uv sync --group docs # or your install command
uv run zensical build --strict
Expect No issues found, exit 0. Fix any reported broken links/anchors.
-
Visual spot-check. zensical serve, then eyeball the homepage, one guide,
and the CLI/API reference. Confirm nav tabs/sections, palette light/dark toggle,
code-copy, admonitions, tabbed content, and superfences all render.
Good-to-know gotchas
zensical serve is preview-only — not for production hosting.- Modern theme header: Zensical's modern variant paints the top bar from
--md-default-bg-color--light (a derived CSS var), not the primary color
as classic Material does. If you customize colors via extra_css, override that
variable too or the header keeps the stock near-white/near-black.
extra_css + --md-* CSS variables work — custom color tweaks port over.- Absolute links are treated as relative; Zensical warns on them.
Acceptance criteria
Rollback
mkdocs.yml is untouched, so reverting is just undoing the deps + command + CI
commits — no config or content to restore.
References
Tutorial issue — safe to pick up in a future session. Delete or close if this
repo's docs stay on MkDocs intentionally.
Goal
Migrate this repo's documentation from MkDocs + Material for MkDocs to
Zensical — the successor to both, built by the same
team (squidfunk). Zensical reads your existing
mkdocs.ymlas-is, preserves allURLs/anchors, keeps Python-Markdown and its extensions, and gives 4–5× faster
incremental builds plus a stricter link/anchor validator.
This is a neutral, self-contained tutorial so it can be executed in a later
session without extra context.
Before you start — compatibility check
Zensical is
0.0.x. It is production-usable if the features you use aresupported. Verify before committing:
mkdocs.ymland list yourplugins:and any non-standardtheme.features.theme.features, standardmarkdown_extensions,no third-party
plugins:beyond built-in search) migrate cleanly. If therepo uses plugins like
mkdocstrings,gen-files,awesome-pages, etc., themodule system that replaces them is not yet GA — hold off or plan around it.
Steps
Swap the docs dependencies. In
pyproject.toml(orrequirements/poetry), removemkdocsandmkdocs-material, addzensical(>=0.0.38).Keep
pyyamlif present.Leave
mkdocs.ymlunchanged. Zensical consumes it natively. Do notconvert to
zensical.toml— upstream advises against it for existing projects.Update local build/serve commands (justfile / Makefile / scripts / docs):
mkdocs serve→zensical serve(local preview only)mkdocs build --strict→zensical build --strict(validates links and anchors)Update CI. In the docs workflow (e.g.
.github/workflows/docs.yml), changethe build step to
uv run zensical build --strict(orpip-equivalent). Theoutput directory is still
site/, so the Pages uploadpath:stays the same.Keep the
mkdocs.ymlpath trigger — it's still the config file.Sync and build.
Expect
No issues found, exit 0. Fix any reported broken links/anchors.Visual spot-check.
zensical serve, then eyeball the homepage, one guide,and the CLI/API reference. Confirm nav tabs/sections, palette light/dark toggle,
code-copy, admonitions, tabbed content, and superfences all render.
Good-to-know gotchas
zensical serveis preview-only — not for production hosting.--md-default-bg-color--light(a derived CSS var), not theprimarycoloras classic Material does. If you customize colors via
extra_css, override thatvariable too or the header keeps the stock near-white/near-black.
extra_css+--md-*CSS variables work — custom color tweaks port over.Acceptance criteria
zensical build --strictpasses with zero link/anchor issues.mkdocsreferences remain except historicalCHANGELOG/lockfiles.Rollback
mkdocs.ymlis untouched, so reverting is just undoing the deps + command + CIcommits — no config or content to restore.
References
panorama-super-cliPR perf(startup): defer httpx import off the cold-start path (#13) #143Tutorial issue — safe to pick up in a future session. Delete or close if this
repo's docs stay on MkDocs intentionally.