Skip to content

RFC-001: Documentation platform migration

Field Value
Status Draft
Author Amy Gray
Created 2026-03-03
Last updated 2026-03-03

Summary

MkDocs 1.x has been unmaintained since August 2024. MkDocs 2.0, released in February 2026, is incompatible with Material for MkDocs - it removes the plugin system, changes the theme architecture, and has unclear licensing. PetFolio's documentation site needs a long-term supported platform.

This RFC evaluates migration options and recommends a phased approach: stay on pinned MkDocs 1.x in the short term, then migrate to Zensical once its module system is stable.

Problem

What happens if we do nothing

PetFolio Docs currently runs on MkDocs 1.6.1 with Material for MkDocs. MkDocs 1.x has received no updates since August 2024. Staying indefinitely on an unmaintained framework carries increasing risk:

  • Security - no patches for vulnerabilities discovered in MkDocs or its dependencies
  • Dependency rot - Python ecosystem moves on; pinned dependencies become harder to maintain over time
  • No bug fixes - any issues found in MkDocs 1.x will not be resolved upstream
  • CI fragility - as Python and pip evolve, the venv-based build may break without upstream support

MkDocs 2.0 breaking changes

MkDocs 2.0 is not a viable upgrade path for Material-based projects:

  • Plugin system entirely removed - the search and tags plugins stop working
  • Theme architecture changed - navigation is passed as pre-rendered HTML rather than structured data, breaking Material's advanced navigation features (tabs, collapsible sections, indexes)
  • Configuration format changed - moves from YAML to TOML with no migration path
  • Source code not on GitHub - available only as downloadable packages
  • Licensing unclear - currently unlicensed, raising usage and contribution concerns
  • Community reaction overwhelmingly negative - users and theme authors migrating away

Community reaction

"Before MkDocs Material, MkDocs was a toy. With MkDocs 2, even the direct continuation of the MkDocs Material project...is in peril." - MkDocs Discussion #4077

The Material for MkDocs team has committed to critical and security fixes for MkDocs 1.x for 12 months from their February 2026 announcement, giving us a window until approximately February 2027.

Constraints

Any replacement must satisfy:

  1. CloudFlare Pages deployment - the site is hosted on CloudFlare Pages with automatic deployments from GitHub Actions
  2. CloudFlare Access authentication - the site is private, protected by CloudFlare Access (email OTP, SSO)
  3. Mermaid diagram support - used extensively for C4, sequence, and flow diagrams
  4. Custom JavaScript - wireframe-viewer.js and multi-stage-viewer.js are used for interactive wireframe pages
  5. Custom CSS - extra.css for site-specific styling
  6. Private site search - search must work without external crawlers (CloudFlare Access blocks them)
  7. Nx monorepo compatibility - the docs project must integrate with the existing Nx workspace
  8. Markdown content portability - approximately 40+ pages of existing Markdown content must migrate with minimal rewriting

Options considered

Option A: Zensical

Zensical is a next-generation static site generator built by the Material for MkDocs team (squidfunk) as a direct replacement for MkDocs.

How it works:

  • Built on ZRX, an open-source differential build engine
  • MIT licensed, fully open source
  • Natively reads mkdocs.yml configuration files
  • Existing Markdown files, template overrides, CSS, and JavaScript extensions work unchanged
  • Professional tier (Zensical Spark) available for organisations needing long-term maintenance guarantees

Strengths:

  • Lowest migration effort - content and configuration carry over directly
  • 4-5x faster rebuild times during development
  • New client-side search engine (Disco) with improved ranking and filtering
  • URL structures remain identical - no broken links
  • Same team that builds Material for MkDocs

Limitations:

  • Partial plugin support only - MkDocs plugins require redesign via the upcoming module system (launching early 2026)
  • Component system also planned but not yet available
  • Newer project with a smaller track record than established alternatives
Feature mapping
MkDocs feature Zensical equivalent Notes
Markdown content (.md) Markdown (.md) Unchanged - same files
mkdocs.yml configuration mkdocs.yml configuration Natively read - no conversion needed
Admonitions (!!! note) !!! note Unchanged - Python Markdown extensions supported
Code blocks + syntax highlighting Pygments Unchanged - same renderer
Mermaid diagrams (pymdownx.superfences) pymdownx.superfences Unchanged - same extension
Tabbed content (pymdownx.tabbed) pymdownx.tabbed Unchanged - same extension
Tags (tags plugin) Module system (pending) Requires module system - verify before migrating
Custom CSS/JS Custom CSS/JS Explicitly supported - same mechanism
Search (search plugin) Disco (client-side) Improved - better ranking and filtering
Navigation tree (YAML nav) YAML nav Unchanged - same structure
Template overrides Template overrides Explicitly supported
PetFolio-specific risk assessment
Feature Risk Notes
search plugin Low Replaced by Disco (better)
tags plugin Medium Needs module system - verify before migrating
pymdownx.superfences (mermaid) Low Python Markdown extensions supported
pymdownx.emoji with Material extensions Medium Material-specific extensions - needs testing
Custom JS (wireframe-viewer, multi-stage-viewer) Low Explicitly supported
theme.features (navigation.indexes, etc.) Medium Material-specific - confirm support
Template overrides Low Explicitly supported
CloudFlare Pages deployment Low Static output, works identically

Option B: Docusaurus

Docusaurus is Meta's React-based documentation SSG. It would eliminate the Python dependency entirely and slot into the Nx monorepo as a native JavaScript project.

Strengths:

  • Very mature with a large ecosystem and community
  • No Python dependency - removes venv setup from CI entirely
  • Native Nx integration as a JS project
  • MDX support - embed React components directly in docs
  • Built-in doc versioning and i18n
  • Official CloudFlare Pages deployment guide
  • Client-side SPA navigation for faster page transitions

Limitations:

  • Medium-high migration effort - content needs syntax changes (admonitions, tabs, custom JS)
  • wireframe-viewer.js and multi-stage-viewer.js would need converting to React components or ES module imports (highest-effort item)
  • No direct equivalents for some pymdownx extensions (abbreviations, definition lists, smart symbols)
  • Ships a React SPA (larger bundle) vs MkDocs' plain HTML output
  • Search for private sites requires a local search plugin rather than the default Algolia (which cannot crawl behind CloudFlare Access)
  • YAML nav replaced by sidebars.js - more powerful but more complex
  • Different visual theme - loses the Material Design look
Feature mapping
MkDocs feature Docusaurus equivalent Notes
Markdown content (.md) MDX (.md or .mdx) Built-in
Admonitions (!!! note) :::note syntax Built-in (different syntax)
Code blocks + syntax highlighting Prism.js Built-in
Mermaid diagrams @docusaurus/theme-mermaid Official plugin
Tabbed content (=== "Tab") <Tabs> / <TabItem> components Built-in (JSX syntax)
Tags @docusaurus/plugin-content-docs tags Built-in
Custom CSS/JS src/css/custom.css / ES imports Supported
Search Local search plugin Plugin required for private sites
Navigation tree (YAML) sidebars.js config Built-in
Abbreviations (abbr) No direct equivalent Needs remark plugin
Definition lists (def_list) No native support Needs remark plugin
Smart symbols (pymdownx.smartsymbols) No direct equivalent Needs remark plugin
PetFolio-specific risk assessment
Feature Risk Notes
Admonition syntax (!!! note) Medium All 40+ pages need :::note rewrite - automatable but tedious
Tabbed content (=== "Tab") Medium Needs converting to <Tabs> / <TabItem> JSX components
Custom JS (wireframe-viewer, multi-stage-viewer) High Must be converted to React components or ES module imports
Search (private site) Medium Algolia cannot crawl behind CloudFlare Access - requires local search plugin
Navigation (mkdocs.yml nav) Low Rewrite to sidebars.js - straightforward but manual
Mermaid diagrams Low Official @docusaurus/theme-mermaid plugin - drop-in
Tags Low Built-in support via @docusaurus/plugin-content-docs
Custom CSS Low Supported via src/css/custom.css
CloudFlare Pages deployment Low Official deployment guide available
pymdownx extensions (abbr, def_list, smart symbols) Medium No direct equivalents - need remark plugins or content removal

Option C: Stay on MkDocs 1.x (pinned)

Continue using MkDocs 1.6.1 with mkdocs>=1.6.0,<2.0 pinned in requirements.txt to prevent accidental MkDocs 2.0 installation.

Strengths:

  • Zero effort - everything works today
  • Material for MkDocs team provides critical/security fixes for 12 months (until approximately February 2027)
  • No risk of introducing new issues through migration

Limitations:

  • No new features or non-critical bug fixes
  • Security coverage expires approximately February 2027
  • Python dependency remains in the CI pipeline
  • Increasingly difficult to maintain as the Python ecosystem evolves

Immediate action already taken

requirements.txt has been pinned to mkdocs>=1.6.0,<2.0 to prevent accidental MkDocs 2.0 installation regardless of which option is chosen.

Option D: MkDocs 2.0 (rejected)

Upgrading to MkDocs 2.0 was evaluated and rejected. It is incompatible with Material for MkDocs due to the removal of the plugin system, changed theme architecture, unclear licensing, and closed development approach. See the Problem section for details.

Comparison matrix

Criteria are weighted by importance to PetFolio's specific needs.

Criteria Weight Zensical Docusaurus Stay on MkDocs 1.x
Migration effort High Excellent - reads existing config and content Adequate - syntax changes and custom JS conversion needed Excellent - no migration
Feature parity High Excellent - same features, improved search Good - most features have equivalents, some gaps Excellent - identical
Long-term support High Good - actively developed, MIT licensed Excellent - Meta-backed, massive community Poor - unmaintained, security fixes expire Feb 2027
CloudFlare Pages Medium Good - static output, works identically Excellent - official deployment guide Good - works today
Private site search Medium Excellent - Disco is client-side Good - local search plugin required Good - built-in client-side search
Nx integration Medium Adequate - separate Python venv Excellent - native JS project Adequate - separate Python venv
Mermaid support Medium Good - via Python Markdown extensions Good - official plugin Good - via pymdownx.superfences
Custom JS/CSS Low Good - explicitly supported Good - supported via ES imports Good - works today
Community/ecosystem Low Adequate - new, growing Excellent - very large Poor - stagnant

Recommendation

Short term: Stay on MkDocs 1.x (pinned). There is no urgency to migrate today. The requirements.txt pin to mkdocs>=1.6.0,<2.0 is already in place.

Medium term: Migrate to Zensical once the module system is stable (expected early-mid 2026). Zensical offers the lowest migration cost - our content, configuration, custom JS/CSS, and URL structures carry over unchanged. It is built by the same team behind Material for MkDocs, which gives high confidence in feature parity and ongoing support.

Why not Docusaurus? Docusaurus is a strong platform, but the migration effort is significantly higher for PetFolio specifically. Converting custom JavaScript viewers to React components, rewriting admonition and tab syntax across 40+ pages, and adopting a new configuration format is hard to justify when Zensical offers a near-zero-effort migration path. Docusaurus remains a viable fallback if Zensical does not mature as expected.

Avoid MkDocs 2.0. It is not compatible with Material for MkDocs and shows no signs of resolving the incompatibilities.

Open questions

  1. Zensical module system maturity - the module system is expected in early 2026. Is it stable enough for the tags plugin and Material-specific emoji extensions? This must be verified before migrating.
  2. Docusaurus local search quality - if Zensical falls through, how well do Docusaurus local search plugins (docusaurus-search-local, @easyops-cn/docusaurus-search-local) perform for private sites behind CloudFlare Access?
  3. Timeline pressure - Material for MkDocs commits to critical/security fixes for 12 months from February 2026. That gives us until approximately February 2027. Is that sufficient runway?
  4. Custom JS migration effort - if Docusaurus becomes the fallback, what is the actual effort to convert wireframe-viewer.js and multi-stage-viewer.js to React components?

Next steps

  1. Monitor Zensical module system development - track the module system launch and test the tags plugin compatibility when available
  2. Spike: Zensical proof of concept - once the module system is stable, run a time-boxed spike to build PetFolio Docs with Zensical and verify all features work
  3. Decision checkpoint (Q3 2026) - review Zensical maturity and decide whether to proceed with migration or evaluate Docusaurus as a fallback
  4. Migration (Q4 2026) - if the proof of concept succeeds, execute the migration before the MkDocs 1.x security fix window expires

References