Use case
MkDocs 1.x has been unmaintained for 18+ months and we're already getting security alerts. MkDocs 2.0 introduced significant breaking changes (removed plugin support entirely, switched config from YAML to TOML) with no migration path. We can't stay on a discontinued tool that's diverging from our stack.
Zensical is built by the same team behind Material for MkDocs, designed as a drop-in replacement for MkDocs 1.x. It reads our existing mkdocs.yml as-is and already supports everything we need: mkdocstrings, mike versioning, search, all pymdownx extensions, navigation, admonitions, content tabs.
The material/privacy plugin (downloads external assets locally for compliance) isn't available in Zensical yet, but I checked our docs and the only external asset is the Ubuntu Google Font. We can just download it and serve it locally, no plugin needed for that.
We'll also drop mkdocs-llmstxt as part of this migration. Modern IDEs and AI tools already have init/indexing commands that reverse-engineer project context on the fly. Shipping a static llms.txt adds noise to the context window more than it helps, the codebase itself is the best source of truth.
Solution/User Experience
Migrate docs build from MkDocs to Zensical. For contributors, mkdocs.yml stays the same because Zensical reads it natively. The only manual work is internalizing the Google Font (Ubuntu) since the privacy plugin isn't available yet in Zensical. Everything else works today.
Steps:
- Replace
mkdocs with zensical in dev dependencies
- Download Ubuntu font locally, add
@font-face in extra.css
- Remove
mkdocs-llmstxt plugin and generated files
- Remove
mkdocs-git-revision-date-plugin (not supported yet, low value)
- Validate docs build and deploy
Alternative solutions
Acknowledgment
Use case
MkDocs 1.x has been unmaintained for 18+ months and we're already getting security alerts. MkDocs 2.0 introduced significant breaking changes (removed plugin support entirely, switched config from YAML to TOML) with no migration path. We can't stay on a discontinued tool that's diverging from our stack.
Zensical is built by the same team behind Material for MkDocs, designed as a drop-in replacement for MkDocs 1.x. It reads our existing
mkdocs.ymlas-is and already supports everything we need: mkdocstrings, mike versioning, search, all pymdownx extensions, navigation, admonitions, content tabs.The
material/privacyplugin (downloads external assets locally for compliance) isn't available in Zensical yet, but I checked our docs and the only external asset is the Ubuntu Google Font. We can just download it and serve it locally, no plugin needed for that.We'll also drop
mkdocs-llmstxtas part of this migration. Modern IDEs and AI tools already have init/indexing commands that reverse-engineer project context on the fly. Shipping a static llms.txt adds noise to the context window more than it helps, the codebase itself is the best source of truth.Solution/User Experience
Migrate docs build from MkDocs to Zensical. For contributors,
mkdocs.ymlstays the same because Zensical reads it natively. The only manual work is internalizing the Google Font (Ubuntu) since the privacy plugin isn't available yet in Zensical. Everything else works today.Steps:
mkdocswithzensicalin dev dependencies@font-faceinextra.cssmkdocs-llmstxtplugin and generated filesmkdocs-git-revision-date-plugin(not supported yet, low value)Alternative solutions
Acknowledgment