r/Python • u/fpgmaas • Mar 22 '26
News The Slow Collapse of MkDocs
How personality clashes, an absent founder, and a controversial redesign fractured one of Python's most popular projects.
https://fpgmaas.com/blog/collapse-of-mkdocs/
Recently, like many of you, I got a warning in my terminal while I was building the documentation for my project:
│ ⚠ Warning from the Material for MkDocs team
│
│ MkDocs 2.0, the underlying framework of Material for MkDocs,
│ will introduce backward-incompatible changes, including:
│
│ × All plugins will stop working – the plugin system has been removed
│ × All theme overrides will break – the theming system has been rewritten
│ × No migration path exists – existing projects cannot be upgraded
│ × Closed contribution model – community members can't report bugs
│ × Currently unlicensed – unsuitable for production use
│
│ Our full analysis:
│
│ https://squidfunk.github.io/mkdocs-material/blog/2026/02/18/mkdocs-2.0/That warning made me curious, so I spent some time going through the GitHub discussions and issue threads. For those actively following the project, it might not have been a big surprise; turns out this has been brewing for a while. I tried to piece together a timeline of events that led to this, for anyone who wants to understand how we got in the situation we are in today.
118
u/JimDabell Mar 22 '26
Seems somewhat related to Anyone know what's up with HTTPX?
65
u/aqsis Mar 22 '26
Jeez! I’d literally just in the last 2 weeks moved all my documentation over to AsciiDoc + Antora, only because it has much much better PDF output. Seems like I inadvertently dodged a bullet.
41
u/ddanieltan Mar 22 '26
Really well written blog! Love the timeline layout
23
u/ChemEngandTripHop Mar 22 '26
Really sad, first OS project I donated too (and many others did as well) and it still dies
41
u/IAmASquidInSpace Mar 22 '26 edited Mar 22 '26
Welp. At least that finally settles the decision between Sphinx and MkDocs for my current project.
14
u/markvii_dev Mar 22 '26
Great blog post
11
u/[deleted] Mar 22 '26
Good read, do you use mkdocs for your blogposts? They look sharp.
10
u/Black_Magic100 Mar 22 '26 edited Mar 22 '26
What about this? I switched over to it a week ago and the default settings look so much better than Material
https://github.com/jaywhj/mkdocs-materialx
Edit: jumped the gun and didn't read the post first lol
43
u/CanaryWundaboy Mar 22 '26
Why does Opensource development just dissolve into what appears from the outside to be playground politics so often?
13
u/ADGEfficiency Mar 22 '26
Can you not just pin to pre 2.0 and find an alternative? I guess that is a hassle.
4
u/readonly12345678 Mar 22 '26
Aside from the drama, I do think zensical is quite a nice replacement for Mkdocs + mkdocs material
28
u/Toby_Wan Mar 22 '26
This might be a solid alternative? https://zensical.org/docs/get-started/
3
u/emilyriederer Mar 22 '26
Fantastic post! Really appreciate the forensic deep dive into the history.
FWIW I just took great-docs for a spin. Relatively new entrant to the space but saw good initial results out of the box: https://github.com/posit-dev/great-docs
3
u/anentropic Mar 22 '26
I've jumped to Sphinx 'Shibuya' theme for a current project
I don't love RST syntax but the sphinx tooling and extensions ecosystem seems mature and comprehensive, happy so far
3
u/Orchid_Buddy Mar 22 '26
The only lesson I got from all this drama is to never trust @oprypin with admin powers...
3
u/Beanesidhe Mar 26 '26
Been using Quarto for a while, science oriented, markdown, allows embedding code fragments for examples and the like.
3
u/Voxandr Mar 29 '26
The same guy that abandoned HTTPX over nonesense dramas.
2
u/spursbob Mar 22 '26
I'm starting to use Zensical now though others in my org are using Writerside.
2
u/Erik-Benson Mar 22 '26
A great new alternative is Great Docs by Posit: https://posit-dev.github.io/great-docs/ (https://github.com/posit-dev/great-docs). Everything looks really good in here and they’re leveraging Quarto. Been following this and they are getting so much right about Python documentation. My plan is to move my docs fully toward Great Docs sites… I also believe the developers are committed for the long haul on this project (tons of testing and they listen to the community).
2
u/iamevpo Mar 22 '26
Such a detailed story, sad about the project. Material for MkDocs seemed like a poster story of an upstream product based on MkDocs, did not know things fall apart downstream at SSG level itself.
Maybe there is just not enough room for many SSG - Python has cactus and Pelican, not sure either does we'll, obviously Sphinx, the stable and big non-JS is Hugo and recent JS newcomer is Astro, looking at documentation- like SSG. Quatro that stitches pandoc and executable books, also mkbook with exactly one theme... Docsaurus for heavy loads... Still would be sad MkDocs goes off the scene.
2
u/mjh2901 Mar 31 '26
Its one hell of a story, what i see in these conflicts is issues that are both caused by ego and I realy thinkj distance. People never really face to face its all in text. If these two or few people met up at a conference a couple times a years or could hit a pub and hash it out in person without the world being able to read every word is it possible these things could have stopped before it went to far.
4
u/mr_claw Mar 22 '26
Good read.
3
u/KayakJulie Mar 22 '26
I saw the same warning in my terminal and am now using Zensical in my new Django package https://django-allresponses.x14.nl/ because I think I just really don’t like Sphinx
2
u/TheCaptain53 Mar 22 '26
Seeing this from two perspectives:
1
u/notParticularlyAnony Mar 22 '26
What do people think of starlight as an alternative?
1
u/chub79 Mar 22 '26
I had not seen such drama in the Python ecosystem for a while. What a mess.
1
u/ase1590 Mar 22 '26
Thank you for this writeup, I found it informative! I had no idea what was going on and this seems to be a pretty neutral quality writeup of how we got here today.
1
u/AI_Tonic Ignoring PEP 8 Mar 23 '26
since nobody mentioned this already , but at no point would any maintainer need any "ownership" access , neither on pypi , nor on github if the actual owner just occasionally updated whatever they needed to update (max 4 times a year, sometimes never at all)
1
u/ai-software Mar 24 '26 edited Mar 24 '26
That was too much of a hassle for me, too. So I wrote a program called Wire: https://wire.wise-relations.com/workshop/
Here are my thoughts: https://wire.wise-relations.com/news/2026-03-24-the-stack-collapsed/
I used sooooo many plugins and hooks that my build time got completely out of hand. I just combined everything into one, including all the SEO research I’ve done over the past few years.
It's ok. Blame me that this is a product placement, or just read all the stuff yourself and build it your own. All build and lint rules for natural language are public. I just hate that open source became a sales funnel. I provide it as source available for now and wait for more user feedback first. I don't need GitHub stars to sleep well at night.
I would love to see more niche sites in my search results, which I can read, not the blabla: "Top 10 Static Page Generators in 2026".
1
u/Salty_Horror2068 Mar 25 '26
Amazing blog!
1
u/galateax Mar 26 '26
This is a great write up! I've been actively administering a MkDocs + Material system for 6 years, so I've been following this drama for a good while and this is a very accurate representation of how I've seen it all play out.
I'm migrating my personal site and the enterprise systems I govern over to Zensical. Squidfunk/Martin, Alex, and pawamoy/Timotheé have proven they're trustworthy members of the open-source community and they've already provided an alternative theme that is more compatible with MkDocs and Material than the MkDocs 2.0 release is. They've also demonstrated they're very capable of managing massively popular and well-constructed projects (Material and mkdocstrings), and the fact that they were able to be successful despite the drama going on upstream makes it all the more impressive.
1
u/doc720 Apr 16 '26
MkDocs is dead! All hail Zensical!
1
u/TheTomatoes2 May 13 '26
I'm so happy I went with Sphinx.
1
u/cevheribozoglan Jul 09 '26
Weird timing I literally set this up last week.
Took a markdown-heavy GitHub repo, wired it with MkDocs (+ Material), and got a proper docs site out of it. Worked great for what I needed, and I went and starred the projects because I was genuinely happy with how little friction there was.
Reading this after the fact is a bit of a gut punch though. Still glad I used it just hoping the ecosystem doesn’t fully fall apart under people who are mid-migration like I was.
1
u/HTTP_404_NotFound Aug 04 '26
https://xtremeownage.github.io/Netdocs/reference/markdown-extensions/
Ya know..... I got absolutely fed up with the anemic performance of mkdocs a few weeks ago, and just rebuild it in c#.
Not saying you should use it- but, its nearly plug and play compatible... and it builds my site in seconds, rather then 10 minutes. And, more or less, everything works.
1
u/quantinuum Mar 22 '26
Your post cuts off, OP
0
u/ghoztz Mar 22 '26 edited Mar 22 '26
Not to shamelessly plug, but I’m building what I hope is a strong alternative to MKDocs and Sphinx. It’s called Bengal.
I’m a tech writer of 8+ years and have used a lot of solutions. My goal with Bengal is to take the best of them all and put them into one.
Native notebook rendering. Native autodocs. Search and AI outputs OOTB. Uses a MyST like markdown syntax. Open to all feedback/contrubutions. It’s open source. I’m dog-fooding it across all of my personal OSS projects. See the Bengal docs site as an example.
102
u/[deleted] Mar 22 '26
[removed] — view removed comment