TL;DR: I recommend we switch to Zensical, which should be a quick action for us to do, as it's authored by the same authors as of our Material for MkDocs website and made fully compatible and portable with it, ideally by November 6, 2026.
@al-fisher @peterjamesnugent
What happened
The creators of Material for MkDocs, which we rely upon for the BHoM Documentation, have been forced to take into account the changes being forced by the underlying system, MkDocs. MkDocs is being rewritten (version 2.0) and made incompatible with version 1.x, which our Material for MkDocs BHoM documentation site uses.
MkDocs 2.0 was announced – a ground-up rewrite of the documentation tool tens of thousands of projects rely on, introducing potentially significant breaking changes.
...
MkDocs 1.x is unmaintained, with issues and PRs piling up and no releases in the past 18 months, and seemingly no plans to fix long-standing issues like live-reload problems. More importantly, it's unclear whether security issues will be addressed, and whether the project will receive any updates at all in the future.
Therefore, the authors have set Material for MkDocs in maintenance mode until November 6, 2026, allowing users to migrate to another solution:
Material for MkDocs is in maintenance mode
We want to be transparent about the risks of staying on Material for MkDocs or on forks of both Material for MkDocs and MkDocs. With MkDocs 1.x unmaintained and facing fundamental supply chain concerns, its future is uncertain and we cannot guarantee Material for MkDocs will continue working reliably. MkDocs 2.0 will introduce breaking changes – something we analyzed thoroughly in our MkDocs 2.0 article.
We're aware that transitioning takes time, which is why we commit to supporting Material for MkDocs for at least the next 12 months, fixing critical bugs and security vulnerabilities as needed. If you have questions about your specific situation or need help planning a migration, don't hesitate to reach out at hello@zensical.org.
The authors of Material for MkDocs have authored a replacement solution, Zensical, which is designed to be a drop-in replacement to both Material for MkDocs and MkDocs itself:
Zensical is designed to be a drop-in replacement for MkDocs 1.x, with the goal of building your existing projects without any changes.
...
To make the transition seamless, compatibility comes first. We're putting significant effort into ensuring a smooth migration from Material for MkDocs for all users. Zensical can natively read mkdocs.yml, allowing you to build your existing project with minimal changes. As of now, a subset of plugins is supported, and we're working on feature parity in the coming months.
Zensical is fully Open Source, licensed under MIT, and can be used for any purpose, including for commercial use.
...
Rather than turning this into a marketing pitch, we encourage you to read the announcement post if you'd like to understand how Zensical differs from MkDocs and what you can already expect today. Additionally, the compatibility section on our website offers an overview of what features are already supported without changes.
TL;DR: I recommend we switch to Zensical, which should be a quick action for us to do, as it's authored by the same authors as of our Material for MkDocs website and made fully compatible and portable with it, ideally by November 6, 2026.
@al-fisher @peterjamesnugent
What happened
The creators of Material for MkDocs, which we rely upon for the BHoM Documentation, have been forced to take into account the changes being forced by the underlying system, MkDocs. MkDocs is being rewritten (version 2.0) and made incompatible with version 1.x, which our Material for MkDocs BHoM documentation site uses.
Therefore, the authors have set Material for MkDocs in maintenance mode until November 6, 2026, allowing users to migrate to another solution:
The authors of Material for MkDocs have authored a replacement solution, Zensical, which is designed to be a drop-in replacement to both Material for MkDocs and MkDocs itself: