Maintenance: Evaluate migration from MkDocs Material to Zensical for documentation

[dreamorosi]

Summary

MkDocs is changing its license and the creator of mkdocs-material has released a new project called Zensical — a from-scratch replacement for both MkDocs and Material for MkDocs, licensed under MIT. Zensical is currently in alpha but is designed for seamless compatibility with Material for MkDocs projects, reading mkdocs.yml directly with no content or configuration changes needed for core features.

An initial compatibility assessment shows that most of our docs setup (markdown extensions, theme features, navigation, custom CSS/JS, template overrides) is already supported. However, three plugins we depend on are not yet available: mike (versioning — Tier 1 priority in their backlog), mkdocs-typedoc (API reference generation — not planned), and mkdocs-llmstxt (LLM text output — not planned). This issue tracks the evaluation and eventual migration when Zensical reaches sufficient maturity.

Compatibility Assessment

Feature / Plugin	Status	Notes
mkdocs.yml configuration	✅ Supported	Zensical reads it directly, no conversion needed
Markdown extensions (all 14)	✅ Supported	admonition, pymdownx.tabbed, pymdownx.highlight, pymdownx.snippets, pymdownx.superfences w/ Mermaid, pymdownx.emoji, etc.
Material theme features	✅ Supported	navigation.sections/tabs/instant/tracking/top/indexes, content.code.annotate/copy, header.autohide, announce.dismiss, content.tabs.link
Color palette toggle (light/dark)	✅ Supported
Custom CSS/JS (extra_css, extra_javascript)	✅ Supported	Same HTML structure and CSS variables
Template overrides (Jinja → MiniJinja)	✅ Low risk	Our main.html uses only standard block overrides, no Python calls. Already on Material v9.7.6 (post-MiniJinja compat)
Directory URLs, file layout, URL structure	✅ Supported	Identical behavior
search plugin	✅ Tier 1 backlog	Core feature
exclude plugin	✅ Tier 1 backlog	Listed for support
privacy plugin	⚠️ Tier 2 backlog	Lower priority, not yet available
git-revision-date plugin	⚠️ Tier 2 backlog	Localized variant in Tier 2; "Revisioning" feature checked in feature parity
mike (versioning)	⚠️ Tier 1 backlog	Committed but not done yet — critical blocker (Backlog #14)
mkdocs-typedoc	❌ Not planned	Not in either tier. Needs workaround (pre-build step)
mkdocs-llmstxt	❌ Not planned	Not in either tier. Needs post-build script

Why is this needed?

• MkDocs is changing its license, which may affect our ability to continue using it under current terms
• Zensical is MIT licensed, removing future licensing concerns
• Zensical is built in Rust with parallel rendering and caching, offering significant build performance improvements
• It consolidates MkDocs + Material for MkDocs into a single coherent stack, reducing dependency surface
• The same team behind Material for MkDocs (trusted by 70,000+ projects) is building Zensical, so continued maintenance and feature development is expected
• Acting early lets us track blockers and be ready to migrate when the project stabilizes

Which area does this relate to?

Other

Solution

1. Monitor Zensical's progress on key blockers:

   • mike versioning support (Backlog #14) — critical for our multi-version docs deployment
   • Module system maturity — needed for custom integrations
   • Move from alpha to beta/stable

2. When mike support lands, run a trial build of our docs with Zensical to identify any remaining gaps

3. Decouple mkdocs-typedoc by running TypeDoc as a separate pre-build step (generate markdown into the docs tree before the site build). This removes the dependency on a MkDocs-specific plugin regardless of migration

4. Replace mkdocs-llmstxt with a post-build script or wait for Zensical's module system to support a custom equivalent

5. Validate template override compatibility (docs/overrides/main.html) — low risk since it uses only standard block overrides with no Python function calls, and we're already on Material v9.7.6 (post-MiniJinja compatibility changes)

Acknowledgment

• This request meets Powertools for AWS Lambda (TypeScript) Tenets
• Should this be considered in other Powertools for AWS Lambda languages? i.e. Python, Java, and .NET

---

Disclaimer: After creating an issue, please wait until it is triaged and confirmed by a maintainer before implementing it. This will reduce amount of rework and the chance that a pull request gets rejected.

Future readers

Please react with 👍 and your use case to help us understand customer demand.