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.
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.
2
u/inouthack Aug 06 '26
u/aqsis thanks for the helpful comment.
I just visited the demo site. This is so much better organized.
https://antora.gitlab.io/demo/docs-site/component-b/2.0/index.html
I'll set this up over the weekend!
41
23
u/ChemEngandTripHop Mar 22 '26
Really sad, first OS project I donated too (and many others did as well) and it still dies
26
u/WillAdams Mar 22 '26
It was useful while you used it, and unlike all the commercial software I paid for in the past, the code lives on in a fork.
1
u/inouthack Aug 06 '26
in the commercial context, a VC evaluates the team.
In the community space the currency is ethics and every donor must evaluate the project founder's ethics and commitment towards the community!
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.
58
u/HommeMusical Mar 22 '26
I've been programming for over fifty years now.
RST, the "markup format" for Sphinx, is one of the worst data formats I have ever seen, bar none.
The Sphinx ecosystem is miserably confusing if you want to do anything slightly different. I wondered in a previous project why the Sphinx guy had so many difficulties, and then in another project I ended up being that guy, and I stopped wondering.
10
u/IAmASquidInSpace Mar 22 '26
I gotta say, I can't really defend reST. It is horribly confusing. But I am used to it, I know what I am getting myself into, and together with Sphinx it has some really useful features that I rely on heavily.
5
u/pyhannes Mar 22 '26
Fully agree. Tried switching to mkdocs a few times but I'm used to Sphinx for over 10 years and I know all festures I usually need. Only thing I really hate about rst is the unstandardized way of defining headings. MD is straightforward here. I'm not even using Myst parster because the ::::::::: hell for directives is f***ing ugly compared to the .. syntax in rst IMO.
15
u/beisenhauer Mar 22 '26
I've had pretty good luck with MyST-parser. No RST, everything's in Markdown.
1
4
u/Atlamillias Mar 22 '26
I thought it was just me. I was messing with Sphinx a couple weeks ago to create documentation for my project and found it to be complete ass. I spent more time trying to figure crap out than I would've simply writing a script to do what I wanted instead.
1
u/TheTomatoes2 May 13 '26
The syntax is quite confusing but once you learn it (or use Claude) it's a powerful engine.
1
u/HommeMusical May 14 '26
Why not just use an existing format?
RST is a terrible format, and not one for which a proper parser exists, so it means it doesn't integrate with your tooling.
2
u/TheTomatoes2 May 15 '26
Ngl, I use Claude Code to write 50% of my docs, and then I edit the rest, mostly in markdown. So I don't have to think about syntax much, only the content.
The only RST stuff I had to learn are the custom directives (basically custom reusable components) and the doc refs. The syntax is odd but it's so little to memorise, it's not an issue. The rest of the document is Markdown anyway.
For styling it's just good old CSS, fighting with Furo is a bit annoying but nothing the browser Dev Tools or Claude can't handle.
I'll take that any day over a crazy maintainer team or a dependency/plugin hell.
4
u/Tcamis01 Mar 22 '26
I recently moved from sphinx to docusaurus and have been quite happy. I found doing anything advanced in sphinx like custom hooks / plug-ins difficult since like nothing is documented and there aren't many examples.
8
u/pyhannes Mar 22 '26
Been staying on Sphinx anyway, seems it was a good choice :) Don't really understand the hype about mkdocs anyway.
7
u/pacific_plywood Mar 22 '26
I think it’s pretty straightforward, RST is a minor pain compared to markdown. I die a little every time I type double backticks
4
u/UUDDLRLRBadAlchemy from __future__ import 4.0 Mar 22 '26
So you picked Zensical, right?
9
u/IAmASquidInSpace Mar 22 '26 edited Mar 22 '26
I'll consider it once I am sure it won't follow the same fate as MkDocs. I have adopted too many shiny new tools only to see them become abandoned half a year later to blindly rely on them now. I gotta say though: it looks really nice!
16
u/UUDDLRLRBadAlchemy from __future__ import 4.0 Mar 22 '26
To my understanding, the material for mkdocs "theme" and mkdocstrings devs ditched mkdocs to build Zensical exactly in anticipation of what happened now.
Essentially when they did, mkdocs was dead in the water already, since its main use-case was deploying those two extensions. I put "theme" in quotes, since it was implementing a ton of functionality mkdocs itself didn't have, and assumed to be there by most other extending modules.
I was in my second day of having deployed that whole thing on multiple projects when Zensical was announced, and it was like 2 hours to rewrite a single config to have the identical functionality up again.
They certainly don't have the track record of Sphinx, but if you were considering MkDocs for code documentation, the people you'd have put your trust in are the ones who built Zensical.
There's definitely a garbage fire in that development community, but unless I'm missing some important bit of drama, the Zensical team was kind of justified to pull the rug from under MkDocs and this is the inevitable collapse.
Personally I'd consider the choice to be between markdown and rst, since the labor-intensive bit will be to adapt the documentation itself, not the renderer. The workhorses for that are python-markdown and pymdown-extensions, and any future implementing python site generator will be able to read your syntax if you move to it. I don't think markdown doc is going to go away - I'd wager more people in the last generations of devs know Markdown than ReStructuredText.
14
11
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?
56
u/Kamouflage Mar 22 '26
Because group tasks often do, but open source development is also public so you get to watch.
42
u/-techno_viking- New Web Framework, Who Dis? Mar 22 '26
Multiple reasons.
But firstly, many don't. We only hear about the ones that do.
Second, we need to think about the people behind the screens. Programmers and sw engi's can be... weird. If you work in the industry I'm sure you've met some people with massive egos, some who can't/refuse to accept that others can also be right, etc, etc. Some who have trouble with other humans, social problems etc.
Third, we need to think about the people who do unpaid or low paid work working with foss. Many are very passionate about their project. They have their own vision that they want to implement. They spend a lot/all their time working for free. Some think only their idea to be the correct one and they've done all this work for free, everyone should listen to me, I'm correct.
Fourth, oss rarely has proper management unless it's controlled/supported by a corporation. It's a few guys who mainly talk through text. It's not really any consequence if you're an ass, you refuse to follow the rules etc. It's not like you can get fired and lose your income. Behaving like they did in this mkdocs drama in a paid job setting would've ment getting written up, getting fired and possible legal action due to hostile take over. Here it just ment having a blog post written about them. A proper management and project management would have avoided this drama (ofc impossible in foss work due to earlier reasons given)
10
u/EatThemAllOrNot Mar 22 '26
That’s so strange to read here this reasonable explanation and not bullshit about capitalism, AI, Trump or aliens.
4
u/tensouder54 Mar 22 '26
What I don't get about this situation though is why lovelydinosaur would want to restict things. I get maybe wanting to rewrite an engine for various reasons but I'm really not sure why as part of that you'd want to get rid of plugin eco-system. That seems like a contra-point to FOSS to me.
4
u/-techno_viking- New Web Framework, Who Dis? Mar 22 '26
I have no clue what his/her motivations are. None of what the person has been doing makes sense to me. We have to take into account that we don't know the person, we don't know their mental state etc. Some people let their small fame go go their heads, some people just like to feel that they have, a very tiny, level of power over others (like certain reddit mods) and don't want to give that up even if they don't want to contribute, some people are just plain a-holes, some people consider themselves the best/smartest and feel the need to do everything by themselves and refuse to accept or listen to the suggestions of others.
8
u/ColdPorridge Mar 22 '26
If I’m properly reading between the lines, lovelydinosaur thinks GitHub in general is overly male dominated space and doesn’t want to engage further. I think they are seeing all of these presumably male maintainers fighting over the direction of the project and want nothing to do with it, and I think any input from any males, valid or otherwise, is only pissing them off more.
I think it’s true there are historically (and presently) male dominated aspects of GitHub and OSS more broadly, but there are also many more advocates for empowerment of marginalized community members of all kinds.
Instead of hitting eject and thanking their product to closed source, it would be more sensible in my opinion to lift up these advocates and cultivate the culture they want to see. Right now this comes across like a very deeply personal issue. I really hate to use this term, but it feels like there is some amount of general man-hating behind this, based on the language they are using in their posts.
I can understand why someone would feel that way but it’s also very ick, anti-OSS, and I wouldn’t touch their projects with a 10 ft pole.
8
u/daredevil82 Mar 22 '26
they've done this in the past, with DRF to the point that they closed off the issue boards and removed access to all the history in there.
Combined with a number of other things, they're appearing to have some pretty substantial mental issues ongoing and end result is alot of chaos
2
72
u/wRAR_ Mar 22 '26
Humans.
1
u/Coretaxxe Mar 22 '26
I've only ever seen it happen from one spectrum tho and I honestly don't know why. However Im happy to retract that statement if its just bubble bias but I genuinely don't know any cases.
6
u/IcedThunder Mar 22 '26
To be fair, closed source has all the same problems you just don't hear about it as often.
I know ive sat thru meetings of people butting heads over design direction.
Or people just quit because they get tired of being ignored.
Office politics is very real.
How many commercial software products have been around for more than say 15 years and isn't considered worse today than it was before? (Because of things like enshittificiation, subscription models, etc). Often times stuff gets worse because they have to hire so many new people who don't really know the code base that well.
Open source isn't meant to stop people from having conflict. The whole point of open source is the knowledge isn't lost. Someone else can pick up the torch.
-7
u/HommeMusical Mar 22 '26
Good question!
I answered essentially this question elsewhere on this page.
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
1
u/chub79 Mar 22 '26
I have switched to a different stack altogether and I've used Astro for a while now (mkdocs-material was frustrating at times).
28
u/Toby_Wan Mar 22 '26
This might be a solid alternative? https://zensical.org/docs/get-started/
2
1
u/saverus1960 Mar 22 '26
What is the alternative for a mike+mkdocs combo for zensical?
4
u/OaksFromAcorns Mar 23 '26
I was looking for this too. For Zensical, seems like it's just waiting for them to implement it. It's on their roadmap page but does not have a ✅ yet.
-7
19
Mar 22 '26
[removed] — view removed comment
12
u/adosztal Mar 22 '26
We use it internally, I can only recommend it. Well documented, great built-in features, and nice plugins (e.g. Mermaid support, lunr-search); React support kicks ass if you need more complex stuff.
14
u/_predator_ Mar 22 '26
The last thing I want my docs page to use is React.
6
u/adosztal Mar 22 '26
if you need more complex stuff
It’s not mandatory. We don’t use it, our docs are fine with the built-in features and a few plugins.
2
u/NotSoProGamerR Mar 22 '26
i find astro quite nice, especially the default starlight theme for docs https://astro.build
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
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/ecstatic_carrot Mar 24 '26
You don't think the owner is also detrminental to the project?
2
u/Orchid_Buddy Mar 25 '26
Perhaps... But owners abandoning projects is not something uncommon. Visions diverging are also part of OSS culture: people are free to fork the project and develop the it in another direction.
But using your admin powers to lock your peers out is childish. Doing it twice is unforgivable.
2
u/Achill1es May 07 '26
Second time was reasonable though. The maintainer appears to be mentally ill and hostile to people, why not prevent him from endangering and bothering community.
1
1
u/inouthack Aug 06 '26
u/Orchid_Buddy all the three squidfunk, oprypin and lovelydinosaur are opportunist b*st*ds!
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
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).
1
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
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:
It's a shame when open source projects are ego driven and the maintainer is unable to get out of the way and let dedicated people help grow and maintain the project. Linus developed git over a couple of weeks for the Linux kernel, did what he needed then got out of the way. Now it's the most popular software version control system out there.
Point 1 is not a legal standpoint. If Mia wishes to print out the entire contents of the MkDocs repository, douse it in piss then consume it before taking it offline forever, that's her prerogative as its her intellectual property. And if people don't like it - well there are many alternatives now as a result of MkDocs NOT being actively maintained and developed.
1
1
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
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
1
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
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
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
Mar 22 '26
[removed] — view removed comment
45
u/Standardw Mar 22 '26
Check Out zensical
7
6
u/danielgafni Mar 22 '26
I already migrated one my of projects to Zensical and couldn’t be happier. I now get instant and incremental builds - absolutely amazing DevEx.
23
u/ColdPorridge Mar 22 '26
This is at the end of OP linked post but basically zensical is the product of all this drama. Personally I can’t really tell what’s bad faith or not. It seems there’s a whole lot of ego in here on all these projects and I don’t see myself touching any of the involved projects on principle.
3
3
u/Toph_is_bad_ass Mar 22 '26
lol what's the principle that would prevent you from using Zensical?
11
u/ColdPorridge Mar 22 '26
That the last major project this guy was in charge of crashed and burned with maintainer drama, forcing everyone to migrate off of it?
26
u/mhindery Mar 22 '26
The creators of zensical are not the creators of mkdocs itself. They created 'only' the plugin mkdocs-material. Having the core project being unmaintained and limiting what could be achieved with a plugin, they eventually created their own thing. Nothing what they did as far as I can see was wrong. In fact they've provided a migration path for people currently on mkdocs-material to smooth transitioning, and all of the mkdocs-material features that used to be paid have been made completely free. They haven't forced anyone to migrate. They simply are moving their development efforts to a new project which they own themselves as not to be restricted and dependent on a 'hostile' basis, which is completely fair.
4
u/readonly12345678 Mar 22 '26
This is the material for mkdocs team, not meterial. I believe it includes squidfunk; is that whom you’re concerned about ?
2
u/s_santeria Mar 25 '26
You should re-read the blog again - the creator of Zensical comes across pretty well IMO. Whereas I will not be migrated to mkdocs 2.0 for exactly that reason.
1
u/inouthack Aug 06 '26
i'd stay away from lovelydinosaur, squidfunk, oprypin and their shenanigans (and that includes any project they nucleate or conceptualize).
They are all opportunist b*st*rds!
5
u/Grintor Mar 22 '26
Better than sphinx with the readthedocs theme and myst-parser plug-in?
3
u/TheTomatoes2 May 13 '26
Nah, Sphinx is pretty decent. You can do anything with custom HTML and CSS. And the maintainers aren't crazy.
3
u/TheSpaceCoffee Mar 22 '26
Been using it for years, but recently eyeing towards Docusaurus - a bit more bootstrapping to do as it’s a full Next.js project and not just a simple CLI, but otherwise I reckon it may allow for more features as an SSG for docs, especially support for React components on top of Markdown in .mdx files. I think it lacks the amount of plugins that MkDocs/Material can benefit from.
118
u/JimDabell Mar 22 '26
Seems somewhat related to Anyone know what's up with HTTPX?