Material for MkDocs is in maintenance mode. Now what?

If your documentation runs on Material for MkDocs, nothing broke when the project entered maintenance mode, and nothing will break on the day support ends. What changes is who carries the risk. Every Python upgrade, dependency advisory and browser change after that date lands on your team, with no upstream fix coming. That makes this a planning decision, not an emergency, and the right time to make it is while the maintainers are still shipping security fixes.

This post covers what was announced, what it means in practice, and how we would choose between staying, moving to Zensical, and moving to Docusaurus. We have tried to stick to what the maintainers have published; where dates matter, check their announcements, because they have already changed once.

What was announced

The short timeline, as published by the Material for MkDocs team:

• November 2025. The team announced Zensical, a new static site generator written from scratch by the same people. Its source repository is MIT-licensed and built with Python and Rust.
• November 2025. The team announced that Material for MkDocs 9.7.0, described as the final version, includes all the previously sponsor-only Insiders features, and that the project was entering maintenance mode: no new features, with a commitment to fix critical bugs and security vulnerabilities for at least the next 12 months.
• Since then. The end-of-life date for those fixes has been extended. At the time of writing, the end-of-life issue in the project's GitHub repository gives May 5, 2027, six months later than the date first announced.

New feature work now goes into Zensical. Material for MkDocs will keep building your site; it just will not grow, and after the support window it will not be patched.

The MkDocs core question

There is a second layer to this. Material for MkDocs is a theme and plugin collection on top of MkDocs itself, and MkDocs core has its own maintenance question. In February 2026 the Material team published an analysis of MkDocs 2.0 stating that MkDocs 1.x had seen no releases in the previous 18 months, and describing the announced MkDocs 2.0 as a ground-up rewrite with potentially significant breaking changes, no plugin system and no compatibility with Material for MkDocs.

We are not going to predict where MkDocs core goes. The practical point is narrower: staying on Material for MkDocs means staying on MkDocs 1.x, so your site depends on two projects that are not adding features. That is fine for a while. It is not a five-year plan.

What maintenance mode means for your site

Your site keeps building and serving pages. The risk accrues slowly and from the edges:

• Python upgrades. When your CI image or security policy moves to a newer Python, an unmaintained dependency may stop installing or start warning.
• Dependency advisories. A vulnerability in a transitive dependency needs a fix somewhere in the chain. After the support window, that fix may never come for your version.
• Markdown extensions and plugins. Third-party plugins keep evolving and may drop support for the old stack before you are ready.
• Features you wanted next. Anything you were waiting for, such as better search, new layouts or new integrations, will now arrive in Zensical, not in Material.

None of these break a site overnight. Together, they mean that the longer you wait, the more likely the move happens under pressure.

Your four options

Option	Effort	Good fit when	Main risk
Stay on Material, pin versions	Lowest now	The site is small, stable and internal, and you plan to revisit within a year	Unpatched dependencies after the support window
Move to Zensical	Low to moderate	You like how MkDocs works, your plugins are supported, templates are lightly customized	A younger project; check plugin and setting support first
Move to Docusaurus	Moderate to high	You need React components, built-in versioning and localization, or one stack with your product frontend	A real migration: content, config, theme and redirects
Move to a hosted platform	Moderate	Writers need a visual editor and nobody wants to own a build	New lock-in; see our post on the real cost of vendor lock-in

If you are weighing the last three against each other for a customer-facing help center, we compared them in more detail in Docusaurus vs MkDocs vs GitBook for help centers.

If you stay: pin and monitor

Staying is a legitimate choice for a small, stable site, as long as it is a decision with a review date and not a default. Pin every Python dependency to an exact version in a lock file, build in CI from that lock file, and subscribe to security advisories for the packages you use. Put a calendar reminder a few months before the end-of-life date to revisit. The handbook page on CI/CD publishing covers how we keep builds reproducible.

If you try Zensical: test it on a branch

Zensical's migration guidance is refreshingly cautious: keep your MkDocs production deployment as it is, build the same project with Zensical, compare the output, and only switch commands in CI when you are confident. Zensical reads mkdocs.yml natively, so the first test needs no config conversion. The install steps follow Zensical's getting started guide:

python3 -m venv .venv
source .venv/bin/activate
pip install zensical

# Build the existing project, config unchanged.
zensical build

# Preview locally and compare against the production site.
zensical serve

Then check the known gaps against your project. At the time of writing, Zensical's compatibility documentation lists these as worth checking:

• Plugins. Zensical does not load MkDocs plugins as Python code. According to its plugin compatibility page, it ships its own reimplementations of a list of widely used plugins, including search, blog, tags, redirects, mkdocstrings, macros and several navigation plugins, and lists mkdocs-gen-files as unsupported. If a plugin you depend on is not on their list, that is your blocker.
• Settings. Some mkdocs.yml settings are not yet supported, including hooks, exclude_docs, draft_docs and not_in_nav. Hooks are the one to look for first, because they are where custom Python usually hides.
• Template overrides. Zensical uses MiniJinja rather than Jinja and cannot call arbitrary Python from templates. Its migration page notes that Material adapted its own templates for this in 9.6.18, so recent overrides may work; older ones that call Python functions need rewriting.
• Deployment. There is no gh-deploy command, so if you publish with mkdocs gh-deploy, move publishing to a CI workflow.

Compare a representative sample of pages, the navigation, search results for your top queries and any custom components. If all of that holds, switching is mostly a change of command in CI.

When Docusaurus is the better move

A move to Docusaurus is more work than a move to Zensical, and we would not recommend it just to escape maintenance mode. It earns its cost when one of these is already true:

• You need versioned documentation for several supported releases, and you are tired of maintaining it with plugins.
• You publish in several languages and want localization built into the platform rather than bolted on.
• You want interactive components in pages, such as API explorers, calculators or tabbed install instructions, and your frontend team already works in React.
• Your docs, marketing pages and help center should live in one stack with one build and one design system.

The content side of that move is straightforward, because both tools use Markdown. The work is in admonition and tab syntax, navigation config, theme customizations and, most importantly, redirects for every URL that changes. The handbook page on deciding whether to migrate has a framework for making that call with numbers rather than preferences.

Our default recommendation

For most MkDocs sites we see, the order is: test Zensical on a branch this quarter, because it is the cheapest move if it works. If a plugin, hook or template blocks it, or if you already had reasons to want versioning, localization or React components, plan a Docusaurus migration instead and do it before the support window closes, not after.

If you want help with either path, our documentation migration service covers moves between docs-as-code stacks, and Docusaurus engineering covers the build, theme and plugin work at $75/hr or $560/day. Send us your repository structure and plugin list through the contact page. We reply within 1 business day.