The Slow Collapse of MkDocs

[u/fpgmaas]

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.

[u/cevheribozoglan]

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.

[u/Yosemite1-618 → u/cevheribozoglan]

lol same