BuildNot yet confirmed elsewhere1 publisher3 min readPublished Updated
Default MkDocs settings let stale pages build clean before any migration begins
Material for MkDocs' team says its theme will cease to work with MkDocs 2.0, and it promised fixes for at least 12 months. A dev.to post says two off-by-default checks let stale pages build clean, so accuracy work carries over to any destination.
The Engineer · Build desk
Timeline: November 5, 2025, Material for MkDocs announces maintenance mode. August 2026, MkDocs 2.0 is a PyPI pre-release, no release date announced. October 5 and 8, 2026, Zensical 0.0.68 and 0.0.69 ship as alpha. November 5, 2026 is the date on Zensical's roadmap banner.
- 2025Material for MkDocs team announces maintenance mode, claim 1
- 2026MkDocs 2.0 published as PyPI pre-release; no release date announced, claim 2
- 2026Zensical 0.0.68 ships, classified alpha on PyPI, claim 5
- 2026Zensical 0.0.69 follows, also alpha, claim 5
- 2026Twelve months after Material's notice; date on Zensical's roadmap banner, claim 18
| Date | Event | Claim |
|---|---|---|
| November 5, 2025 | Material for MkDocs team announces maintenance mode | 1 |
| August 2026 | MkDocs 2.0 published as PyPI pre-release; no release date announced | 2 |
| October 5, 2026 | Zensical 0.0.68 ships, classified alpha on PyPI | 5 |
| October 8, 2026 | Zensical 0.0.69 follows, also alpha | 5 |
| November 5, 2026 | Twelve months after Material's notice; date on Zensical's roadmap banner | 18 |
What happened
- MkDocs 2.0 reached PyPI as a pre-release in August 2026, and the Material team says no official release date has been announced.
- Zensical shipped 0.0.68 on October 5 and 0.0.69 on October 8, and PyPI classifies both as alpha.
- MkDocs' strict setting, which halts the build on a warning, defaults to false.
Why it matters
- constraint A site on the Material theme can run only MkDocs 1.x, because the theme will not work on 2.0.
- decision The accuracy audit is the one step that survives all three options, so it can start before the team picks a destination.
- exposure Dead heading links stay invisible to a strict build until anchor validation is raised, so a migration copies them to the new platform intact.
- contradiction Zensical's page says existing MkDocs projects build without changes, yet the post still tells readers to check plugins against Zensical's replacement list.
The support floor and the Zensical launch banner land on the same day. Twelve months from the November 5, 2025 announcement is November 5, 2026 [18], and the Zensical roadmap banner names November 5 for 0.1.0 [6]. That is 28 days after the 0.0.69 alpha shipped [19]. The Material team's wording is a floor: support "for at least the next 12 months, fixing critical bugs and security vulnerabilities as needed" [1]. The Zensical roadmap says "Our roadmap is directional and does not promise delivery dates" [7].
Staying on MkDocs 1.x comes with known limits. The Material team writes that its theme "will cease to work with MkDocs 2.0" [4], and MkDocs 2.0 "won't have a plugin system" [3]. One team has already chosen 1.x. FeldrinH wrote on April 6, 2026: "We are using MkDocs 1.6 and for the time being have no plans or bandwidth to migrate." [9] The tool that keeps API pages in step with code carries its own warning. The mkdocstrings homepage, checked October 8, 2026, reads "mkdocstrings is in maintenance mode!" [8]
An engineer renames an argument. mkdocstrings regenerates the API reference from the docstring, and the tutorial that calls the old argument stays wrong [15]. In the post's test, the new signature appears, the strict build is green, and the tutorial still passes the old argument [17].
Turning strict on helps less than it sounds. MkDocs 1.6 logs a missing file at warning level and a missing anchor at info level, so strict mode breaks the build over a deleted page yet lets a dead heading link through until anchor validation is set to warn [11].
By default, a missing Snippets file fails silently. With `check_paths` at its default of off, a missing file means "the markup will be removed" [12], and the page publishes with a hole where the example was. With it on, the build fails [13]. The post does not say whether MkDocs 2.0 supports Snippets. It reads Snippets as a Markdown extension, notes that neither of its sources confirms 2.0 support, and advises testing [23].
The post suggests a check on your own site: take the last merged pull request that renamed an argument and ask whether anything flagged the tutorial that calls it [16]. Its own condition for when the existing tools suffice is narrow. Python code and docs must share a repository, and the pull request must hold every fact a tutorial needs [22]. For a team whose facts are spread across a ticket, a Slack thread, a spec or a separate repository, the post says the same-PR rule depends on memory [22]. We think audit-first is sound advice for the first kind of team. The second kind has to find where its facts live before the audit means anything.
Weigh the destination advice with the source in mind. The post favors targets that keep docs as Markdown in Git. It names Potluck Docs, an MIT-licensed Astro and Starlight template maintained by EkLine, and points readers to its own guide [14]. The statements from the Material team, Zensical and mkdocstrings reach us as the post quotes them.
What to watch
- Whether Zensical 0.1.0 ships on the November 5 banner date and drops the alpha classification.
- Whether the Material team extends support past its 12-month floor, which runs to November 5, 2026.
- Whether the MkDocs 2.0 pre-release gets a release date and a confirmed answer on Snippets support.
Clarity's read
What the record supports and how the coverage leans. The claims behind it follow.
Reality
- Evidence55
- Adoption
- Insufficient
- Hype gap+8
- Incentives40
- Confidence55
Claim ledger
Ranked by verification strength, evidence, and original report placement.
- [1]
On November 5, 2025, the Material for MkDocs team announced that "Material for MkDocs is in maintenance mode," with support "for at least the next 12 months, fixing critical bugs and security vulnerabilities as needed."
ReportedSupportedSource: Material for MkDocs team announcement, as quoted in the dev.to postView cited source - [2]
MkDocs 2.0 was "published as a pre-release on PyPI" in August 2026, and "No official release date has been announced yet."
ReportedSupportedSource: Material team post (February 18, 2026, updated October 2, 2026), as quoted in the dev.to postView cited source - [3]
The Material team's post says "MkDocs 2.0 won't have a plugin system."
- [4]
Of its own theme, the Material team writes that "it will cease to work with MkDocs 2.0."
- [5]
Zensical version 0.0.68 shipped on October 5 and 0.0.69 followed on October 8 (2026), both classified as alpha on PyPI.
- [6]
The Zensical roadmap banner announces a "November 5 Zensical 0.1.0, Studio, and Spark Community launch."
- [7]
The Zensical roadmap says "Our roadmap is directional and does not promise delivery dates."
- [8]
The mkdocstrings project homepage, checked October 8, 2026, warns "mkdocstrings is in maintenance mode!"
- [9]
"We are using MkDocs 1.6 and for the time being have no plans or bandwidth to migrate."
- [10]
The MkDocs strict setting halts processing when a warning is raised, and it defaults to false.
- [11]
In MkDocs 1.6, a missing file reports as a warning and a missing anchor only as info, so a strict build fails on a deleted page but passes a dead heading link until anchor validation is raised to warn.
- [12]
The pymdownx Snippets extension has check_paths at its default of off; with it off, a missing file means "the markup will be removed."
- [13]
With Snippets check_paths turned on, a missing file fails the build.
- [14]
The post names Potluck Docs, an MIT-licensed Astro and Starlight template maintained by EkLine and described as "a template, not a hosted product," as a target that keeps docs as Markdown in Git, and points readers to its own guide for a side-by-side platform comparison.
- [15]
In the post's example, an engineer renames an argument on a Python function; mkdocstrings regenerates the API reference from the docstring, but the tutorial that calls the function with the old argument stays wrong.
- [16]
The post suggests a test on your own site: open the last merged pull request that renamed an argument or changed what a function does, and check whether anything flagged the tutorial that calls it.
- [17]
In the post's test, on the next build mkdocstrings shows the new signature, the strict build is green, and the tutorial still passes the old argument.
- [18]
Twelve months from the November 5, 2025 announcement is November 5, 2026, the same date as the Zensical roadmap banner.
- [19]
November 5, 2026 is 28 days after the October 8, 2026 release of Zensical 0.0.69.
- [20]
Because the Material theme will cease to work with MkDocs 2.0, a site on the Material theme can run only MkDocs 1.x.
- [21]
Zensical's compatibility page says "Zensical can build existing MkDocs projects without requiring changes." The post nonetheless says that waiting for Zensical means keeping your mkdocs.yml and Markdown with plugins checked against Zensical's replacement list.
ReportedContestedSource: Zensical compatibility page and dev.to post2 sources— create a free account to open themView cited source - [22]
The post says that if Python code and docs share a repository and the pull request holds every fact a tutorial needs, mkdocstrings plus a same-PR rule keeps pages right; if the facts sit in a ticket, a Slack thread, a spec or another repository, the rule runs on memory.
- [23]
The post reads Snippets as a Markdown extension, but says neither of its sources states whether MkDocs 2.0 supports it, and advises testing.
- [24]
The post says none of the three choices (stay on MkDocs 1.x, wait for Zensical, or move) makes a stale page true, so audit and fix accuracy first: stale pages migrate with you, and the fixes count under any choice.
Sources
1 independent publisher whose own reporting we read for this story.
- dev.toMaterial for MkDocs maintenance mode: keep your docs accurate now
1 article · October 11, 2026
Topics and entities
Follow any of these and your For You feed starts watching them — no settings page required.