The Slow Collapse of MkDocs

On January 11, 2014, Mia Kimberly Christie (then known as Tom Christie, using the GitHub handle @tomchristie, now @lovelydinosaur) pushes the first commit to what would become MkDocs, with the message “Hell yeah”. A flurry of commits follow in the next few months.

The burst of activity doesn’t last very long. By mid-2014, their activity in the repo stops completely.

Others join the project, like @d0ugal and @waylan. @lovelydinosaur remains inactive, and for the period between July 2016 and July 2021 @waylan seems to be the sole maintainer of the project.

The project becomes more and more popular, and by mid-2022 the project accumulates well over 14,000 stars on GitHub.

On Apr 27th of 2020 a new contributor @oprypin, makes their first contribution to the project; a proposed bugfix. @waylan agrees with the changes

and merges the PR. After his first contribution, @oprypin isn’t involved with the project for about half a year, after which a long period of frequent activity follows; bugfixes, features, you name it.

There seems to be quite some friction between @oprypin and @waylan. For example, here when @oprypin does not get a response on the changes he made to his Pull Request:

Or a scenario where @waylan disagrees with a potential proposed performance improvement by @oprypin:

The frustration of @oprypin grows, eventually culminating in him opening a discussion thread titled “Concerns about maintainership of MkDocs”. In this lengthy message, he accuses @waylan of gatekeeping the project and dismissing contributions without technical justification, and proposes an alternative maintainership model where there is less responsibility for a single maintainer.

He posts a copy of the thread in his own fork of the repository. There isn’t too much activity in both threads, but the consensus seems to be that although it is hard to distinguish between facts and opinions, the post is unnecessarily personal, as is also mentioned by the original - and mostly inactive - author of the project:

The same day @oprypin creates the discussion, @waylan announces his departure from the project:

Now that @waylan is no longer the maintainer of the project, new maintainers are needed. @lovelydinosaur opens a discussion asking for suggestions on the maintainership situation. @oprypin jumps in to announce that he is willing to take over maintenance of the project.

@lovelydinosaur does not immediately take him up on that offer, but @oprypin wants to continue development on the project, so a few weeks later he returns to the thread:

After a while @lovelydinosaur of seeming a bit reluctant to grant @oprypin write access to the project, and being on the slow side with their responses, @squidfunk, the original author and maintainer of Material for MkDocs, jumps in;

after which @lovelydinosaur invites a group of maintainers to MkDocs:

About a year later, @oprypin asks for elevated permissions on the Github repository and the PyPI project:

After getting Owner rights, @oprypin becomes the primary maintainer of MkDocs. For the next two years he steadily works on the project alongside the other maintainers and contributors. Bug fixes, dependency updates, a handful of new features, the project keeps moving.

A routine documentation issue turns into something else when @squidfunk uses the thread to call out Read the Docs for profiting from MkDocs without contributing back. @oprypin seizes the moment:

@squidfunk responds:

What follows is a lengthy public airing of their history: @oprypin insisting he did nothing wrong, @squidfunk recounting how he had once been @oprypin‘s first sponsor, vouched for him joining the MkDocs team despite their differences, and eventually chose to limit their communication to public channels after repeated personal conflicts.

The issue is marked as completed when the minor documentation fix is applied.

We’re circling back to the thread in which @lovelydinosaur announced that they added @oprypin, @squidfunk and @ultrabug as maintainers to the project.

On March 16th, @squidfunk posts:

It turns out that @oprypin had single-handedly made that decision:

This is frowned upon by community members, and later @lovelydinosaur joins the conversation and reinstates @squidfunk‘s membership to the MkDocs organisation. In addition, they remove @oprypin‘s ownership rights to the repository.

On April 6th, @lovelydinosaur writes:

Three hours later, @oprypin announces that he is stepping down from MkDocs. In his post, he elaborates on his disagreements with @squidfunk, his frustration with @lovelydinosaur‘s intervention, and the loneliness of maintaining the project:

He decides to help the team with releasing 1.6.0 on April 20th 2024, which, except for a 1.6.1 release on August 30th that year, is still the last release at the time of writing.

Two days after @oprypin stepped down, @pawamoy, an active community member and author of mkdocstrings, invites roughly 25 plugin and theme authors to help maintain MkDocs in a thread with the ambitious title “Taking MkDocs to the next level”. The response is warm. @squidfunk wrote that he was “really psyched to see this happening.” He also added:

On April 23, a few days after @oprypin‘s last release, @lovelydinosaur posts that they will be returning as lead maintainer. By this time, it has been eight full years since their last Pull Request to the repository was merged. Their stated goal: MkDocs should have “strong and independent leadership distinct from Material for MkDocs.” They tag 28 community members and schedule a Saturday call.

The call happens. @squidfunk declines to join. Two people show up. That’s the last visible activity in the thread for the eighteen months that follow.

@lovelydinosaur is back to actively contributing to the project for the first time in many years.

In this period @squidfunk seems to be the only other active maintainer. While @lovelydinosaur is making some contributions to MkDocs, they also start working on a redesign of MkDocs in the mkdocs/sketch repository.

@lovelydinosaur shares a demo of their proposed MkDocs redesign to the MkDocs core team. While MkDocs currently builds the whole site at once, the proposed redesign builds pages on-the-fly when requested. There are concerns from the maintainers and core contributors:

In an unrelated thread, @lovelydinosaur shares that they are working towards a redesign of MkDocs that does not require plugins at all:

The downvotes on the post signal that this is not really what the community is hoping for.

MkDocs 1.6.1 is released. Up until today, this is still the latest release and the repository has not seen any active development other for one or two fixes in the documentation and an updated CI badge.

Plugin author @facelessuser opens a discussion with a direct question:

He notes that bug fix PRs have been sitting unreviewed for months despite active sponsors.

The response from @pawamoy paints a very clear picture of what had happened since April 2024. He describes trying to build a collaborative maintenance model around @lovelydinosaur‘s return, finding that @lovelydinosaur showed little interest in the current codebase and was focused instead on a redesign. While @pawamoy was working on grooming the backlog and trying to maintain the project, @lovelydinosaur went silent when tagged on PRs.

@lovelydinosaur replies that they had been focused on httpx 1.0, now in early prerelease, and was considering whether they had time to free up for MkDocs. The response:

On August 3rd, about ten days later, @oprypin resurfaces in the thread for the first time since his departure. His offer to return comes with one condition:

@lovelydinosaur did not respond.

While the users of MkDocs were asking for bugfixes, @lovelydinosaur continues working on a redesign of MkDocs in yet another repository: encode/mkdocs. At that time, the repository is not yet public.

On November 11th, 2025, mkdocs-material 9.7.0 is released, and it is announced that Material for MkDocs is entering maintenance mode. Alongside it comes the announcement of Zensical: a modern static site generator, rewritten from scratch by the Material for MkDocs team. It reads existing mkdocs.yml files natively, rebuilds 5x faster, and ships with a completely redesigned search engine.

In the maintainership thread from April 2024, which had been quiet for months, a link to the blogpost is posted alongside the question if Material for Mkdocs going into maintenance mode meant that MkDocs required a fresh start. @oprypin resurfaces and points out that Zensical is the fresh start. With regards to MkDocs, he says:

On January 14, 2026, @lovelydinosaur mentions that they are open to others creating a 1.6.2 release of MkDocs, while they are working on MkDocs v2 in private.

Then on January 21, @lovelydinosaur opens a discussion announcing MkDocs version 2:

The reactions are overwhelmingly negative. The major disadvantage of the proposed MkDocs 2.0 according to the community is the lack of support for plugins. It’s what made MkDocs great in the first place;

@facelessuser puts into words what many in the community are thinking:

Community members note that the MkDocs version 2 repository is placed in the encode organisation instead of the MkDocs organisation. The contributing guidelines of the encode organisation explicitly discourage opening issues or pull requests. They also point out that not opening up the source code goes against the principles of Open Source software development. @lovelydinosaur eventually explains the reason for the repo being private:

On February 13, @lovelydinosaur removes the notice that work is planned to make MkDocs 2.x backwards compatible with MkDocs 1.x.

On February 18, the Material for MkDocs team publishes a detailed blog post with their full analysis of why v2 is incompatible with their work and the broader plugin ecosystem; from the removal of the plugin system to the missing license.

On February 18, Material for MkDocs starts showing a warning during every mkdocs build, informing users of the potential future incompatibility issues with MkDocs 2 and linking to the blogpost mentioned above.

@oprypin’s earlier request of gaining ownership access to PyPI has been granted sometime in the past. While his rights from the GitHub repository have been stripped after stepping down in 2024, this is not true for his rights on the PyPI repository.

On March 9, in what he describes as a last resort to prevent an unwanted MkDocs 2.0 upgrade from breaking users’ projects, he uses his access to remove all other maintainers from the project, including those of the original author, @lovelydinosaur. He announces the takeover in two GitHub discussions: one in mkdocs (since edited) and one in mkdocs-community (the organisation has since been renamed to ProperDocs). His primary justification is that a silent v2 release would reach users running pip install mkdocs and unexpectedly break their projects. He creates a new repo at mkdocs-community/mkdocs, announces that future PyPI releases will come from there, and calls for community support.

@lovelydinosaur files a PyPI support ticket and blocks @oprypin from the MkDocs GitHub org.

Within 24 hours, @oprypin backs down:

@lovelydinosaur regains PyPI access.

In a separate discussion, @Andre601 voices his worry about the state of the project and asks various questions regarding the future of the maintainership of the project, to which @lovelydinosaur responds:

Six days after the PyPI takeover, @oprypin publishes the formal launch of ProperDocs: a drop-in replacement for MkDocs 1.x. Replace pip install mkdocs with pip install properdocs, replace mkdocs build with properdocs build. Existing plugins work without code changes. The project ships a warning redirecting users away from MkDocs 2.0.

A few days later, @jaywhj announces MaterialX, a continuation of Material for MkDocs.