The Slow Collapse of MkDocs
Posted by fpgmaas@reddit | Python | View on Reddit | 135 comments
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.
IAmASquidInSpace@reddit
Welp. At least that finslly settles the decision between Sphinx and MkDocs for my current project.
HommeMusical@reddit
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.
TheTomatoes2@reddit
The syntax is quite confusing but once you learn it (or use Claude) it's a powerful engine.
HommeMusical@reddit
Why not just use an existing format?
It's a terrible format, and not one for which a proper parser exists, so it means it doesn't integrate with your tooling.
TheTomatoes2@reddit
Ngl, I use Claude Code to write 95% of my docs, and then I edit the rest, mostly in markdown.
The only RST stuff I had to learn are the custom directive 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.
beisenhauer@reddit
I've had pretty good luck with MyST-parser. No RST, everything's in Markdown.
HommeMusical@reddit
Hey, neat idea!
Atlamillias@reddit
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.
IAmASquidInSpace@reddit
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.
pyhannes@reddit
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.
Tcamis01@reddit
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.
UUDDLRLRBadAlchemy@reddit
So you picked Zensical, right?
IAmASquidInSpace@reddit
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.
UUDDLRLRBadAlchemy@reddit
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.
pyhannes@reddit
Been staying on Sphinx anyway, seems it was a good choice :) Don't really understand the hype about mkdocs anyway.
pacific_plywood@reddit
I think it’s pretty straightforward, RST is a minor pain compared to markdown. I die a little every time I type double backticks
Orchid_Buddy@reddit
The only lesson I got from all this drama is to never trust @oprypin with admin powers...
ecstatic_carrot@reddit
You don't think the owner is also detrminental to the project?
TheTomatoes2@reddit
Both have clear social issues.
Orchid_Buddy@reddit
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.
Achill1es@reddit
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.
pydry@reddit
This is a shame. mkdocs + material is hands down the best markdown-to-html documentation generator out there.
Grintor@reddit
Better than sphinx with the readthedocs theme and myst-parser plug-in?
TheTomatoes2@reddit
Nah, Sphinx is pretty decent. You can do anything with custom HTML and CSS. And the maintainers aren't crazy.
Standardw@reddit
Check Out zensical
ColdPorridge@reddit
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.
Toph_is_bad_ass@reddit
lol what's the principle that would prevent you from using Zensical?
ColdPorridge@reddit
That the last major project this guy was in charge of crashed and burned with maintainer drama, forcing everyone to migrate off of it?
s_santeria@reddit
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.
readonly12345678@reddit
This is the material for mkdocs team, not meterial. I believe it includes squidfunk; is that whom you’re concerned about ?
mhindery@reddit
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.
readonly12345678@reddit
I recommend trying zensical out. I actually like it quite a bit.
pydry@reddit
Whether it's bad faith or not, there are 1000 static site generators out there.
Of them about 5% have non ugly skins.
Of them about 10% actually bother to help maintain their best skins.
danielgafni@reddit
I already migrated one my of projects to Zensical and couldn’t be happier. I now get instant and incremental builds - absolutely amazing DevEx.
anentropic@reddit
Unfortunately there's still a lot missing
I'm sure they'll get there though
TheSpaceCoffee@reddit
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.
JimDabell@reddit
Seems somewhat related to Anyone know what's up with HTTPX??
fpgmaas@reddit (OP)
Yup... Similar situation there it seems; the original author is mainly focused on a redesign in a separate repository instead of maintaining the existing product. But the blogpost I wrote already was very much on the lengthy side so I decided to leave that out. I also wanted the blogpost to focus on the MkDocs situation and not turn out in a smear campaign against the original author of both projects.
readonly12345678@reddit
Which author is this?
TheOneWhoPunchesFish@reddit
Mia Kimberly Christie aka lovelydinosaur.
I don't really like them. They put pictures of dead insects everywhere in the readme and documentation. A few people bought up how it triggers their phobia, and how the injuries on the insect make them sad, and his response was basically telling them to fuck off and deal with it.
Which is extremely hypocritical for someone who claims to care about social issues and doesn't want to create unwelcome spaces.
I've avoided their projects (httpx, mkdocs) completely because of that, and am glad I did because both of those projects are abandonware now.
TheTomatoes2@reddit
Well they clearly have a mental issue of some sorts... Their latest comments (last few days) are bizarre.
readonly12345678@reddit
Hmm interesting. They seem to come up with great ideas, but then struggle, or…
HommeMusical@reddit
There's a simple explanation for all of these: open source turned out to be a scam to rip off developers for the benefit of capitalism.
I've worked on open source for almost twenty years now: https://github.com/rec
I never expected to make money out of any of it! But had I known that my hard work, and the hard work of all these people including all these volunteers in this story, was going to be used to train AIs to put us out of a job, I would never have done it.
These people have put thousands of hours of work into MkDocs, and what has been their reward? More work!
No wonder they are bitchy and neurotic. In their hearts, they feel robbed, and why shouldn't they?
countnfight@reddit
You're describing problems with capitalism, not open source
ghostofwalsh@reddit
He's describing problems with technology not with capitalism. Technology advances and the game changes. Some people win and some people lose. But it's just gonna happen whether you like it or not.
AI is useful therefore people will use it. If AI takes your job that's not the fault of some "greedy capitalist" it's just bad luck that your job happens to be one that AI can do.
t1010011010@reddit
Well in Communism, innovation would be banned
spinwizard69@reddit
yeah just look at how backwards Russia is fighting a regional war.
No_Soy_Colosio@reddit
Russia hasn't been communist for 33 years
spinwizard69@reddit
Well in name maybe, it is a failed state for the same reasons.
HommeMusical@reddit
Yes, indeed. Capitalism is 100% the issue. The idea behind open source is just great, but it got hijacked by the billionaires; and our own work was used against us to destroy our careers.
I love open source, the idea: it's extremely social and mutually beneficial. But had I known it was going to be used against not just programmers, but all of humanity, I would not have participated.
And yet when I finish browsing reddit, I'm going to go back to my latest open source project, https://github.com/rec/fing
I need what it does, and it will be very useful for wind instrument players (and I know quite a few of them, including me).
I love open source; I work on it almost every day; I'm just enraged that capitalism turned it into a weapon against The People.
chaoticbean14@reddit
The idea behind lots of things are or have been great (open source not withstanding); billionaires have the funds to hijack just about anything they want. Look at the car industry? We The People, have been able to get 50-60-70 (some argue as high as 100) mpg out of carb driven ICE cars for over 80 years! But a car company (i.e. the rich folks) bought the patents and shelved them, so their 12-15mpg engine would sell. Ta-da. Their shitty engine wins because they have the money to do that. This applies to, well, lots of things. Not all rich people /companies are this way - but like most things, the few ruin it for the many.
Capitalism isn't the issue either. It's what makes the world go around. It's not perfect, but it's better than alternatives. It gives 'the people' their best opportunities - not always in obvious ways - but it does. How do we know this? The others have failed, terribly, many, many times over. Time and again, they have always failed. Even on small scales, even on wildly tiny scales they fail - every time. Not saying we can't come up with something better, but as of now? Be realistic.
Also, you're being really exhaustive with the whole "they put us out of a job" talk - and calling LLM's "AI"? You should know better. There is nothing artificial, or intelligent about them. They're a close system incapable of thinking or creating novel new ideas or approaches to things. It's literally impossible! They're an algorithm that has more information to base it's answers on than we as humans are capable of remembering - that's it. Helpful with being able to do trivial things? Yes. Can they do some boilerplate for you? Of course. Once a project gets any kind of complexity? They hallucinate and become worthless - mostly because they cannot conceptualize, imagine or think. Again, they are NOT intelligent, and should STOP being called such.
Your post comes across as dramatic, for the sake of drama. As a programmer you should know all this about LLM's and shouldn't be calling them AI. Relax. Take a breath. It will be okay. Open source is still a net good. Not everything is doom and gloom. It sounds like mainstream media has gotten to you, don't let that happen.
No_Soy_Colosio@reddit
I'm not reading all that. But saying "It's not perfect but it's what we got" just betrays a lack of intellectual curiosity. I'm sure some really close minded people said the same back in feudalist days.
chaoticbean14@reddit
The fact you responded with what you did, then call it "lack of intellectual curiosity" is hilarious. Nowhere do I say "it's not perfect but it's what we got", quite different in fact. I say it's not perfect, but it is better than alternatives - sure. Those two statements are distinctly different. You talk about lack of intellectual curiosity, while not even reading what is all of 4 small paragraphs. Wow. The irony in your statement is clearly lost on you, otherwise I don't think you would have written what you did. With that in mind, I'm glad you chose not to read it - who knows what else you might have typed and misinterpreted.
HommeMusical@reddit
Before I start, I want to emphasize that I am a massive, massive opponent of LLM technology. I absolutely detest it, I think it is likely to collapse and take down the economy, and I think other less likely but possible outcomes from it are even worse. In no way does my upcoming refutation in any way indicate any sort of approval of this shit technology.
I first heard this story almost fifty years ago: https://en.wikipedia.org/wiki/Charles_Nelson_Pogue - check out the patents yourself.
It just isn't true, of course. Engineering is hard: there is no magic carburetor or other trick. If there were, China or Japan would build it and in China's case, ignore the law.
Car efficiencies steadily improved over decades - and then dropped like a stone because of massive SUVs. Car companies make somewhat more efficient cars, encouraging people to buy more cars, net increasing the demand for gasoline.
Capitalism is literally destroying our ecosystem at an exponential rate. It's hard to imagine a worse outcome than decimating our biosphere.
You: "Everyone else in the world uses this word wrong! Only I use it right!"
AI does not mean artificial general intelligence or superhuman competence. We called silly llittle programs like ELIZA "AI".
And LLMs long ago passed the Turing Test. They perform the imitation of fairly complicated and complex reasoning.
For example, I can give any of the major LLMs instructions on how to build a slightly complicated program, in English, and it will spit out a program that will work, a lot of the time, and a rational explanation of how it works.
This is certainly the impression of intelligent behavior! Until 2003, had you shown me this, I'd have been 100% convinced that that answer would have had to have been written by a human.
So to say, "Oh, there's nothing there," is not logically sound. It is a fairly convincing simulation of intelligence - the average person is wowed almost 100% of the time. Programs like ELIZA are called AI
It is much like the joke about a dog that's playing poker and winning. Someone says to the owner, "Wow, that's one smart dog!" and the owners says, "Are you kidding? He's drawn twice on an inside straight just today!"
Two completely unsupported claims.
Finally some sort of argument, but unfortunately, not a valid one. Why is it that a complicated enough algorithm and a lot of information couldn't perform some given behavior that you think of as intelligent? Maybe it couldn't - maybe it could.
Many people claim to be able to dramatically improve their output using LLMs. My experiments have not convinced me that it's so, personally. While it's quite astonishing how quickly one can write a fairly good program/function/module, it has a lot of bad habits, it creates subtle alien bugs, and as you point out, the LLM itself does not learn from experience, though contexts are effecting in providing a local, temporary illusion of learning.
Some people seem to make very fast progress on generating test features using fleets of these LLMs, some more or less to correct the flaws of others.
It's my belief that this will quickly become impossible - the technical debt will overpower them. I am however not certain of this belief.
Three unsupported claims! I tend to believe these claims, but you need to make some sort of argument for them.
Which part, specifically?
I don't see this as either respectful, or advancing your argument.
This is condescending, and does not advance your argument.
This is condescending, and does not advance your argument. (Also the phrase "mainstream media" has often been used with me by people with beliefs that were contrary to the fact, like vaccine and climate deniers, free energy, and, well, magic carburetors.)
Up until mid-December, I had a functioning career, and then I was summoned into a video conference, asked to describe my AI competences, and when they were limited, shown the door. Now every it seems single job matching my fairly wide array of skills wants AI, though I keep looking.
I believe I have been involuntarily retired. So why shouldn't I be pissed off? What are your feelings about having an income, yourself?
AI has over ten times as much money invested in it as went into the dot com boom.
If it collapses, on top of the energy crisis and the tariff crisis, it will tank the world economy for a long time, fscking a lot of people.
If it is moderately successful, it's going to destroy a lot of jobs, putting huge downward pressure on all other salaries, and also, an evaporation of value from all the massively overvalued AI companies.
And if it's totally successful, the majority of us will never work again, and have to depend on the charity of people like Bezos, Altman and Zuckerberg to eat. I'm waiting for my check already!
chaoticbean14@reddit
There's so much to unpack here - like you saying it's completely unsupported that LLM's are a closed system. Like, they're literally trained on human documentation and writings and findings. That's it. There's nothing more. That brings with it the limitations therein - they will never, ever come up with novel new ideas or things they haven't already 'learned' (been trained on).
The long and short of it is: It knows the information we've given it. It cannot come up with 'new' ideas outside of that information. That makes it a closed system. I've ran into way too many times, when any level of complexity begins to happen with a project? It hallucinates and it's answers become shit. If you prove it wrong or tell it how it's not following best practices, etc. eventually you work yourself into a circle with any of these AI's. Why? Because they cannot work up novel new approaches. They spit out what they have been trained on. It's literally how they are made and designed.
They're a glorified google search that can respond with context specific answers that cuts through the cruft of searching this site or that site and reading through lots of user-generated answer content. It summarizes it all in a pretty way that makes you go, "wow, it's smart!", no it's just a good algorithm that got you the information you wanted.
If you don't know what you don't know? It gets shit wrong in bad ways. I can't count how many times it will get me 'close enough' then I have to fix it because I know the circular bullshit it's producing doesn't follow any best practices. No matter how I ask, or how many times I explain to it as if it were a junior developer, it gives me some variety of the same answers. It cannot reason, it cannot think. It is at it's core, a great sentence completion algorithm combined with all the human generated/created knowledge we can train it on. It won't go out of those bounds, because it's incapable of that. That's not unsupported, that's literally because of the logic limitations of the system. It cannot.
HommeMusical@reddit
Your whole response is a series of unsupported claims and "does not follow" arguments.
Why? Because you say so?
Why? Because you say so?
etc. etc. etc.
You addressed precisely ZERO of my arguments. Indeed, I don't believe you read a word of it.
You simply make unsupported claims as if they are a logical argument. It's like arguing with a child. What a waste of my time.
chaoticbean14@reddit
"unsupported claims"
They have to 'train' LLM models on data - where does that data come from? Does it just poof into existence? It's human writing, documentation, art, music, etc. things created BY HUMANS that they are trained on - because that's what we have. This is not unsupported, it's literally how it is trained.
You really don't have any idea how LLM's work, how they are trained and the logical limitations that imposes on a system based on 1's and 0's.
By your answers, I imagine you're either a bot yourself (silly bot) or I can understand why you were let go if your office wanted someone with at least an entry level LLM knowledge, because it's clear there is a skill gap in that area.
I'm down for discussion, but arguments like this where you're going to nit-pick semantics with zero understanding of what you're discussing? Nope. Good day.
spinwizard69@reddit
Capitalism has nothing to do with AI in this context. Programming is actually a simple task for AI thus the over weight of the impact on programmers. Given that programming as a job will not go away, programmer will just become more productive.
Why do I say this? Get outside of the hard tech world and your average manager doesn't have a chance in hell of interacting with AI and getting good results. Frankly we are talking about people with very limited abilities to understand software (or anything else for that matter).
In other words you are looking at this the wrong way, AI is there to make your career easier. Sure a different skill set is required but this is no different than the machining industry shift away from manual machining into the world of CNC machines and CAD/CAM. Sure some machinist got left behind other made millions. Today's automation of programming is no different, you either adapt or you find a different career.
countnfight@reddit
Wow, you have some really wild & cool projects and I'm glad they're open source in spite of everything! But I think what you're describing is true of lots of technology, right? People develop something like drones or painkillers or social media or neural networks, something that could be cool and beneficial, and capitalists turn it into a weapon or a vector for propaganda. I'm happy you're in open source
HommeMusical@reddit
Sure, I guess it's leopards eating my face sort of thing - "Oh, I didn't expect I'd get burnt by this. [surprised O]"
Thanks for the kind words!
IncidentalIncidence@reddit
This is kind of a ridiculous thing to say though. I don't disagree with you about the AI companies cannibalizing everything to produce slop sucks, but how is it a scam? You really think Stallman and Torvalds and Hartman and all of those guys were playing the long game because they knew that 30 years later somebody was going to invent the LLM and they were scheming to generate enough human-produced software so a bunch of kids who weren't even born yet at the time would have training data? Is it at least possible that they (and the thousands of other OSS contributors over the decades) genuinely believed in the ideals of FOSS?
larsga@reddit
I always wonder what people actually mean by the term "capitalism" in statements like these. Serious question.
max123246@reddit
Open source is amazing when everyone is given the resources to live a fulfilled life from the very get-go, and resources are not hoarded by a small subsection of the populus.
So it doesn't matter if they're paid by their open source work from the good-will of some few benefactors, they can just do their best work because they want to. Because they are not dependent on work for survival.
spinwizard69@reddit
OK who is hoarding resources when it comes to computing? Nobody. Being a programmer is one of the most versatile of jobs out there. The opportunities are literally endless and all you need is a computer and a compiler to get started. There literally is no hoarding of software technology, the vast majority of programming languages are developed in the open.
This is no different than in any other industry, there is no hoarding to be come a plumber, becoming a doctor only requires the investment in education, hell even sending your favored project to space is more affordable than it ever has been. No matter which way you look opportunity for the average guy has never been more accessible. If you have a good idea and no money that isn't even a problem as venture capital is also more accessible than ever.
In other words the idea that there is excessive resource hoarding is absolute B.S.
max123246@reddit
You're out of touch. 60% of working adults in the US do not have a bachelor's degree. They do not have accessible access to VC funding.
Yes, software engineering is lucrative, but your company makes so much more money than they give you, because your work is worth more than they pay you.
That's what I mean by resource hoarding. Nvidia profits $2 million per employee and yet the median salary is $300k there.
spinwizard69@reddit
So?
Whole industries where started by farm boys leaving the fields. As for VC funding, the money will find you if you have the evidence of a new product with potential.
You are frankly nuts, if you think Nvidia isn't sharing in a way that is very lucrative to employees. $300K is an extremely good salary. Beyond that they have an ESPP that allows employees to buy discounted shares in the company. That is what capitalism is all about, owners of the company are the ones that benefit. Now if an NVidia employee failed to take advantage of the ESPP, then whos fault is that? Such a plan is the exact opposite of resource hoarding.
Right now in the USA we have the most robust stock exchange world wide. Taking part in the economy has never been easier. People that failed to do so apparently have failed high school math class.
Honestly I'm not sure how your opinion got formed (brain washed maybe). We live in a time of unlimited opportunity. All one has to do is find a way that fits personal abilities and engage with the economy.
spinwizard69@reddit
Many people have no idea what capitalism is. If they did they would be investing in the growth stocks of today to set themselves up for a bright future.
larsga@reddit
The people replying here certainly have no idea what it is, which is kind of the hypothesis I wanted to test. Capitalism is what we make it -- it's not some immutable Marxian entity.
HommeMusical@reddit
I don't want to be mean, I am using the standard definition of a very standard word.
Dictionaries exist and wikipedia exists: e.g. https://en.wikipedia.org/wiki/Capitalism
AggieBug@reddit
The one that exists in real life. It is famously analyzed by Marx in the book Capital, which you can read for free here.
TheTomatoes2@reddit
I'm so happy I went with Sphinx.
doc720@reddit
MkDocs is dead! All hail Zensical!
mjh2901@reddit
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.
Voxandr@reddit
The same guy that abandoned HTTPX over nonesense dramas.
galateax@reddit
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 mkdocsstrings), and the fact that they were able to be successful despite the drama going on upstream makes it all the more impressive.
Beanesidhe@reddit
Been using Quarto for a while, science oriented, markdown, allows embedding code fragments for examples and the like.
Salty_Horror2068@reddit
Amazing blog!
ai-software@reddit
Mir war das dann auch zu blöd. Ich habe nun Wire programmiert: https://wire.wise-relations.com/workshop/
EastAppointment4561@reddit
This is a great opportunity to gain resume experience working with AI.
Python SWE
Part-Time
Hourly contract
$100 per hour
Remote
Apply Here: https://t.mercor.com/LBkdx
AI_Tonic@reddit
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)
Erik-Benson@reddit
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).
AI_Tonic@reddit
i was happy to click on the link you shared , nice find
sys_exit_0@reddit
Any thoughts on properdocs ?
Toby_Wan@reddit
This might be a solid alternative? https://zensical.org/docs/get-started/
saverus1960@reddit
What is the alternative for a mike+mkdocs combo for zensical?
OaksFromAcorns@reddit
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.
VEMODMASKINEN@reddit
Docusaurus is OK too.
https://docusaurus.io/
NotSoProGamerR@reddit
i find astro quite nice, especially the default starlight theme for docs https://astro.build
adosztal@reddit
We use it internally, I can only recommend it. Well documented, great built-in features, and nice plugins (e.g. Mermaid support, lunr-search).
_predator_@reddit
The last thing I want my docs page to use is React.
adosztal@reddit
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.
evdw_@reddit
this is literally what the linked blogpost is about
Standardw@reddit
Migration is really easy, especially with copilot
yup_its_me_again@reddit
I've been using this, its fine
ase1590@reddit
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.
readonly12345678@reddit
Aside from the drama, I do think zensical is quite a nice replacement for Mkdocs + mkdocs material
chub79@reddit
I have switched to a different stack altogether and I've used Astro for a while now (mkdocs-material was frustrating at times).
chub79@reddit
I had not seen such drama in the Python ecosystem for a while. What a mess.
iamevpo@reddit
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.
CanaryWundaboy@reddit
Why does Opensource development just dissolve into what appears from the outside to be playground politics so often?
IcedThunder@reddit
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.
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).
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.
-techno_viking-@reddit
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)
tensouder54@reddit
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.
EatThemAllOrNot@reddit
It looks like he has some mental issues
ColdPorridge@reddit
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.
daredevil82@reddit
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
-techno_viking-@reddit
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.
EatThemAllOrNot@reddit
That’s so strange to read here this reasonable explanation and not bullshit about capitalism, AI, Trump or aliens.
slayer_of_idiots@reddit
It happens to every product with weak and poor leadership. Leadership by committee isn’t really possible. It’s possible if each member has their own area of autonomy and are each able to exercise leadership in that area — algorithms, build systems, documentation, contributor outreach, api, etc.
It’s hard for one person to be committed to a project for 10-20 years. And most leaders are not good at handing off leadership and transitioning leadership well.
wRAR_@reddit
Humans.
Coretaxxe@reddit
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.
HommeMusical@reddit
Good question!
I answered this elsewhere on this page.
Kamouflage@reddit
Because group tasks often do, but open source development is also public so you get to watch.
VEMODMASKINEN@reddit
Because programmers lack management skills.
anentropic@reddit
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
bdu-komrad@reddit
I’ll probably do the same
notParticularlyAnony@reddit
What do people think of starlight as an alternative?
ddanieltan@reddit
Really well written blog! Love the timeline layout
yojimbo_beta@reddit
I think that blog is using blowfish (Hugo)
iliasreddit@reddit
Good read, do you use mkdocs for your blogposts? They look sharp.
yojimbo_beta@reddit
It's a modified version of Blowfish for Hugo
NoKaleidoscope3508@reddit
lol
ghoztz@reddit
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. Open to all feedback/contrubutions. It’s open source.
quantinuum@reddit
Your post cuts off, IP
emilyriederer@reddit
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
TheCaptain53@reddit
Seeing this from two perspectives:
spursbob@reddit
I'm starting to use Zensical now though others in my org are using Writerside.
Black_Magic100@reddit
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
KayakJulie@reddit
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
mr_claw@reddit
Good read.
markvii_dev@reddit
Great blog post
ChemEngandTripHop@reddit
Really sad, first OS project I donated too (and many others did as well) and it still dies
WillAdams@reddit
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.
ADGEfficiency@reddit
Can you not just pin to pre 2.0 and find an alternative? I guess that is a hassle.
aqsis@reddit
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.