May 6, 2026
Docs and disorder
Our Continuation of MkDocs
MkDocs fans split as abandoned project gets a dramatic community rescue
TLDR: ProperDocs was launched as a community backup plan for MkDocs after claims that the original project is stalled and could change in a way that breaks people’s sites. Commenters split between popcorn-fueled drama watching, frustration with slow maintainers, and people saying they’ve already moved on.
A sleepy software tool announcement turned into full-on open-source soap opera this week after the former active maintainer of MkDocs unveiled ProperDocs, a new community-led continuation meant to be a near-identical replacement. The pitch is simple: the old project is allegedly stuck, the current owner isn’t listening, and users are being warned that a future update could suddenly break the themes and add-ons people rely on. Translation for normal humans: a popular website-building helper may be heading for chaos, so the community built an escape hatch.
And wow, the comment section immediately smelled drama. One person basically walked in asking, “Wait, isn’t this old news?”, pointing to the fact that the post first appeared months ago. Another tossed in a recent discussion, which only widened the rabbit hole. But the loudest energy came from the spectators treating it like prestige TV: “Two open source dramas in one week? Get the popcorn.” That was the mood—half concern, half front-row entertainment.
The hottest takes weren’t just about this one project, either. Some commenters used the mess to vent about a bigger problem: volunteer-run software slowing to a crawl while users race ahead. One argued that if maintainers merge a few changes a month while others can crank out a dozen a day, the math simply stops working. And in true internet fashion, one rebel skipped the feud entirely to say, essentially, we already left and found something better. In other words: some want a rescue, some want a revolution, and some are already happily dating the rebound.
Key Points
- •The article announces ProperDocs as a fork of MkDocs and presents it as a drop-in replacement.
- •The author says MkDocs is unmaintained and claims future changes under the MkDocs name could break plugin and theme compatibility.
- •Users are advised to replace the `mkdocs` package with `properdocs` and use the `properdocs` command instead of `mkdocs`.
- •Existing MkDocs plugins are described as compatible with ProperDocs without requiring plugin renaming.
- •Plugin authors are asked to cap their `mkdocs` dependency at version 1.6.1 and add ProperDocs as an additional dependency.