Migrate to Zensical static site generator because Material for MkDocs is in maintenance mode

[HonkingGoose]

Tell us more.

Summary

You're using Material for MkDocs 9.7.0 to build the documentation site. 9.7.0 is the final version, the project is in maintenance mode. It will get security updates for 12 months.

I recommend migrating from Material for MkDocs to Zensical. Zensical is from the same developers, builds on the things we like already, and is built as the replacement.

Todos

• Remove dependencies for Material for MkDocs and MkDocs.
• Remove dependencies for custom bits of Material for MkDocs.
• Install dependencies for Zensical.
• Confirm code that autogenerates parts of the documentation still works, fix it if needed.
• Convert mkdocs.yml to the new Zensical TOML format (technically optional, but I still recommend updating to the new format).
• Remove custom styling, try the baseline from Zensical first.

Official announcement from Material for MkDocs ¹

First snippet:

9.7.0, the final version of Material for MkDocs, includes all features that were previously exclusive to sponsors, making Material for MkDocs Insiders available to everyone!

As we're shifting our efforts to Zensical, Material for MkDocs is entering maintenance mode. This means that while we'll continue to fix critical bugs and security issues for 12 month at least, no new features will be added to Material for MkDocs.

We're also discontinuing our sponsorware model, saying goodbye to GitHub Sponsors. If you were a sponsor of our work, you already received an email mentioning that your sponsorship was cancelled. As one of the numerous individuals and organizations sponsoring Material for MkDocs over the past years – thank you! Your continued support has been invaluable.

Now, we want everyone to benefit from all features we have developed for Material for MkDocs, which is why we're making all Insiders features available to everyone!

This is the logical next step in our journey as we focus on Zensical – our next-generation static site generator built from the ground up to overcome MkDocs' technical limitations. Zensical is fully Open Source, licensed under MIT, maintains compatibility with Material for MkDocs, and can build your existing projects with minimal changes.

In the coming months, we'll close the feature parity gap, bringing the expressiveness of Material for MkDocs to Zensical.

Material for MkDocs maintainers recommend migrating to Zensical

We want to be transparent about the risks of staying on Material for MkDocs. With MkDocs unmaintained and facing fundamental supply chain concerns, we cannot guarantee Material for MkDocs will continue working reliably in the future. We're aware that transitioning takes time, which is why we commit to support it at least for the next 12 months, fixing critical bugs and security vulnerabilities as needed, but the path forward is with Zensical.

If documentation plays a critical role in your organization, and you're worried how this might affect your business, consider joining Zensical Spark, or feel free to schedule a call by reaching out at contact@zensical.org.

Footnotes

1. Announcement on Material for MkDocs blog ↩

[viceice]

my biggest concerns are the plugins and our hook. are they supported on Zensical?

[HonkingGoose]

Based on the Zensical docs, these Python Markdown extensions/plugins should work: ¹

• Abbreviations
• Admonitions (call out / alert boxes)
• Attribute lists
  • Buttons
  • Tooltips
  • Image alignment
  • Image lazy-loading
• Footnotes
• Markdown in HTML
  • Image captions
• Table of Contents
• Tables

That covers nearly all the big ticket things we're using now.

Things like hooks and the custom docs generating code will probably need to be updated manually.

Footnotes

1. Zensical docs, extensions Python Markdown ↩

[HonkingGoose]

I found a better comparison page:

• Zensical docs, Feature parity

The big things that are missing:

• Link validation (strict mode)
• Module system to replace hooks and plugins

Here's the roadmap for the module system.

[viceice]

so no migration possible yet

[viceice]

@squidfunk Do you think zensical is compatible enough for use to migrate?

https://github.com/renovatebot/renovate/blob/main/tools/mkdocs/mkdocs.yml

[squidfunk]

From a quick glance, if you can temporarily forego the privacy and awesome-pages plugin functionality, you should be good to go. If you need more support and have questions, please join our Discord for the discussion – it's quite impossible for me to personally keep on top of all situations where I'm tagged ☺️

[viceice]

thanks, so we're still blocked, privacy could be disabled, but not awesome-pages.

I'm also concerned about our custom hook:

renovate/tools/mkdocs/mkdocs-hooks/custom-edit-url.py

Line 3 in f383805

def on_page_context(context, page, config, **kwargs):

[jamietanna]

I'm seing if Copilot can do some of the migration for us, and see if its PR is OK (#41357)

TL;DR: not yet

[viceice]

looks like it's in a very early alpha stat

[viceice]

2. we need to control the menu structure which won't always match file structure. so a nogo

[ofek]

In case it helps to have an example: at work I switched our developer docs over to Zensical and found the transition to be quite smooth.