Skip to content

Documentation Platform Evaluation

This note captures the implications of a possible move from MkDocs + Material to Zensical, with a focus on this repository's current documentation setup and Cloudflare-hosted delivery.

Current State

The documentation stack currently uses:

  • mkdocs
  • mkdocs-material
  • mkdocs-awesome-pages-plugin
  • mkdocs-git-revision-date-localized-plugin
  • mkdocs-mermaid2-plugin
  • mkdocstrings

The site is built as a static output directory (site/) and then served from a static host or CDN path. That means the hosting layer cares about files, not the generator name.

MkDocs 2.0 Impact

Material for MkDocs states that MkDocs 2.0 is not compatible with Material and removes the plugin system, which breaks this repo's current docs stack.

That means:

  • mkdocs.yml is not a drop-in configuration for MkDocs 2.0
  • existing plugin-based navigation and rendering features would need a new implementation
  • theme-specific behavior such as tabs, sections, and current navigation structure would need re-validation

Zensical Impact

Zensical currently supports Python Markdown and ships with a default extension set. It also documents support for extensions relevant to this repo, including mkdocstrings, Macros, and GLightbox.

That suggests Zensical is the more plausible migration target if we want to keep the current docs model, but there are still risks:

  • Markdown rendering defaults may differ from MkDocs
  • plugin parity is not guaranteed for every current MkDocs plugin
  • navigation and theme behavior would still need a full visual review

Cloudflare Hosting Impact

If the replacement still produces a static site, Cloudflare hosting impact should be low.

What would likely change:

  • build command in CI or local docs scripts
  • output directory path, if it changes from site/
  • any redirect or asset assumptions tied to the current generator output

What should not change:

  • using Cloudflare as a static CDN or Pages host
  • DNS setup for the docs hostname

If the replacement requires server-side rendering or runtime execution, then the Cloudflare story changes and needs a separate hosting review.

  1. Confirm the new generator still emits a static directory suitable for Cloudflare Pages or equivalent static hosting.
  2. Inventory plugin-by-plugin replacements:
  3. awesome-pages navigation
  4. revision date metadata
  5. Mermaid rendering
  6. mkdocstrings
  7. Render the current docs and compare the generated navigation, search, and code-block behavior.
  8. Verify Markdown compatibility for existing docs that rely on Python Markdown extensions.
  9. Confirm the final deploy path still works with the current Cloudflare DNS and hosting setup.

Decision

At this point, the question is not "Cloudflare or not". It is whether we can preserve the current docs behavior with a different static generator without losing plugin functionality or changing the publishing model.