Reviving the maintenance of MkDocs

[oprypin]

• Update 1: The plan of taking over the PyPI package is cancelled

• Update 2: Development continues here as the ProperDocs project!

Prior content

Summary:
I have retaken the mkdocs name on PyPI and will attempt to resume the maintenance of MkDocs at https://github.com/mkdocs-community/mkdocs (new repo).
I need your support.

(Cross-posted at mkdocs/mkdocs#4089)
(UPDATE: I have just been blocked from github.com/mkdocs, so I will not be able to further reply there.)

Hi folks,

By now, it is easy to see that the person who has taken control of github.com/mkdocs 2 years ago has no interest in maintaining the project. They completely disregard all feedback and all incoming issues. Offers to take over maintenance have been also ignored.
I don't see what their motivations are - possibly they want to just reuse the project's name - but it is at least clear that there's 0 overlap with the goals of the community. They also openly state that there is a gender preference in place, leaving everyone very puzzled.
As I understand, this person is working alone, or at least it appears that all the people who were initially welcoming the switchover have since left.

---

Just now, I did the last thing I could still do to try to preserve MkDocs' usefulness for the users:
I kicked all other people from the "mkdocs" project on PyPI. (I was able to do that because I've been listed there the whole time. And yes, it had to be all people, because we can't take any chances at this point. I do apologize). See before vs after.

At the bare minimum and regardless of what happens next, this step had to be attempted in order to prevent some questionable unrelated software dubbed "Version 2" from being dropped onto users one day as an update - because that'd be an even worse state of things than the current state where the project is merely unmaintained for 2 years. My actions will not hinder the "Version 2" project in any way, because this software will in any case be better off under a different PyPI name rather than squatting on the PyPI name "mkdocs". (Nobody who currently runs pip install mkdocs will be expecting to see this project popping up). Whereas for us that name is extremely important, because every single plugin has a direct reference to it.

I also encourage the current holder of github.com/mkdocs/mkdocs to release control of it and give it back to the community. I think the new "Version 2" project would also be completely fine to move forward without overwriting the history of user feedback on MkDocs.

---

2 years ago I did not willingly leave, it's just that my only other choice was to be on a "team" of this unfamiliar person after they removed my admin rights.
Yes, this "unfamiliar" person is the same person (or at least the same GitHub account) who wrote the initial versions of MkDocs in the year 2014, but since then they had little to no involvement with the project (see "lovelydinosaur" in the graphs). And it is indeed also the same person who granted me the rights in the first place at one point. But I still say "unfamiliar" because nobody has actually worked with them in 10 years and I've been here less than that.

I consider the events of their comeback 2 years ago to be illegitimate. I have been extremely sad the whole time that the community so easily accepted that I was thrown away in an instant despite being the only available maintainer. Apparently, social media outreach and polished communication was all that mattered. Everyone heard the one-sided story and after that point literally anything I could've written to try to defend myself would only dig me in deeper.

---

What we have now:
If this situation settles (or even if it doesn't), we can take the opportunity to revive maintenance of MkDocs, if anyone is interested.
I welcome everyone's input.

• https://github.com/orgs/mkdocs-community/discussions/1
• https://github.com/mkdocs-community/mkdocs (the repository I've just created)

You're free to support me or not support me. If people want me to leave, I can even offer that afterwards.
But at the moment it is in everyone's best interest to throw all possible support behind this, because this is our last hope of keeping the project alive with any amount of traction. We can surely expect the situation with the PyPI name mkdocs to come to a dispute and possibly be reversed again, and then all the circumstances would be against us. But no matter what, a fork needs to happen, because the current holder of github.com/mkdocs has made it fully clear that they will not give the repository back -- there's nothing left to wait for. Worst case, we will at least have the interested people gathered at https://github.com/orgs/mkdocs-community/discussions/1.

I involve myself in this situation again because I am concerned (and have been concerned the whole time) just how much work of the community is being thrown away, and how all the users have been betrayed.

@2mustange @Andre601 @EddyLuten @facelessuser @fralau @GarfieldJiang @Guts @humitos @jaywhj @JosePizarro3 @kamilkrzyskow @lyz-code @mkusz @ssbarnea @timvink @twardoch @ultrabug
Anyone still here? I need as much support as I can get 🙏

[Andre601]

I personally am welcoming this change.

lovelydinosaur has, to put it nicely, been very bad at keeping the project maintained, even at stuff such as maintaining dependencies or answering questions/issues.

Personally, I would be willing to offer assistance in regards to documentation, which imo does require a bit of rework as it feels a bit odd imo.
Tho, personally would this first require input from the community to see what parts may cause headaches and confusion to them, to then tackle.

[EddyLuten]

Oh my, that's a bold move!

I'm still here, still maintaining my little plugins. I do believe continued work on the existing codebase is important and "Version 2" does feel like a rug pull.

Yet, I don't have faith in the project's current governance, and share your concern that when I run pip install mkdocs at some later time this year, I get a completely incompatible mess, breaking the entire ecosystem. Less than that, I am worried about not having had a release since 2024 while there are 100+ issues filed and 30+ PRs.

We can surely expect the situation with the PyPI name mkdocs to come to a dispute and possibly be reversed again, and then all the circumstances would be against us. But no matter what, a fork needs to happen, because the current holder of github.com/mkdocs has made it fully clear that they will not give the repository back -- there's nothing left to wait for.

I'm also certain a dispute will be filed soon, but you're right; a fork needs to happen regardless. I've registered mkdocs-community.org after this repo's org name to prevent others from sniping it. @oprypin email me if you want it.

Edit: the dispute has been filed.

[lovelydinosaur]

It's not a "bold move". It's theft.

[ssbarnea]

TBH, what makes the move even move legitimate. I will always value more those that value collaboration, community and project survival.

[LandonTClipp]

@ssbarnea I agree with you but nothing will stop @lovelydinosaur from nuking this community from orbit. Nobody has the authority to stop them. Unless someone can find a way to remove their authority for good and is willing to fund a possible legal battle, nothing will stop this sabotage. The community needs to move away from mkdocs and towards a project with a more sustainable and effective governance model, one preferably without active disdain for a specific gender of people.

[oprypin]

I have just been blocked from github.com/mkdocs, so I will not be able to further reply there.

[lovelydinosaur]

Andre, the content you were blocked for was the persistent ongoing project trashing on multiple occasions.

[lovelydinosaur]

Both of you should have been blocked a long time ago, but here we are. Anyways please enjoy your nonsense somewhere else.

[LandonTClipp]

@lovelydinosaur you have taken an actively hostile stance to the open source community and it's clear your only goal is to further your own agenda that nobody here wants. You've alienated your single most important collaborator @squidfunk and you are actively torpedoing what used to be a great ecosystem. Now you're marking every comment criticizing you as "disruptive" and being insulting to male-identifying people.

mkdocs/mkdocs#4088 (comment)

mkdocs is dead. Its governance is highly chaotic and its creator @lovelydinosaur is self-nuking it into oblivion. Everyone should move to Zensical or to a mkdocs fork so that @lovelydinosaur cannot be involved any longer.

[Andre601]

Andre, the content you were blocked for was the persistent ongoing project trashing on multiple occasions.

I cannot see where I trashed the project. I was criticising its state of maintainership, which is a concern many others were sharing.
The only other project I really went negative with was the v2, but even there was my main focus clear criticism and not outright hate or insults like you did... on more than one ocassion.

But whatever. I personally don't care too much about this.
If anything will I put more focus on this org and repo and maybe contribute something to it, if there's something I can help with (not python tho. Python is scary).

[Andre601]

Yes, I saw the comments of yours that you deleted.

Just for the sake of context are here web archive links, in case the comments get removed/altered (They don't seem to be when I now checked):

• https://web.archive.org/web/20260309184150/https://github.com/mkdocs/mkdocs/discussions/4088#discussioncomment-16054713
• https://web.archive.org/web/20260309234629/https://github.com/mkdocs/mkdocs/discussions/4077#discussioncomment-15687765

[EddyLuten]

Here's a link to the expected PyPI dispute.

[LandonTClipp]

@oprypin forcefully taking over pypi is not the way to solve this. You will eventually lose access to it and your changes will be reverted. Nobody can stop @lovelydinosaur from nuking the ecosystem if they want to. It's best to just move on and let mkdocs die a slow death.

[oprypin]

Too many people have given their time to this, it was my duty to try whatever I can.
And you have to remember that @lovelydinosaur forcefully took over the GitHub in the first place.

[oprypin]

Hi everyone.

I am backing off completely here. I'm sorry.

I've now realized that there may indeed remain an ongoing threat to the forked project no matter what. And maybe even a target on my back to expect the whole time, which I would not be able to withstand.
The continuation of the project will need to come from agreement, not disagreement; I was wrong to think any other way.

There's also not any kind of a great vision left in me for the project anyway (after a long delay and also in general), so maybe I'm not the right person from that perspective either.

I'll now restore the accesses that existed prior to today and step away. It was an accident that it was possible to do this, so let's not be too disappointed in letting it go.

I hope an agreement can somehow be reached to maintain MkDocs. And I still hope that @lovelydinosaur comes to their senses and does not overwrite the project https://pypi.org/project/mkdocs/. But I can only hope.

[d0ugal]

If you want to fork you should fork. This wasn't the way.

[Andre601]

Listen @oprypin

While I understand your points, now restoring the status quo is not the aproach to have.
It only supports lovelydinosaur's position in keeping the project in this state.

It's like when a child wants candy, you refuse, it cries and you give it candy to make it shut up.
(For the record, I do not accuse lovelydinosaur of being/acting like a child. It was just the best example I can think of.)

As for motivation and ideas: That's where the community can step in.
I for my part have one or two ideas that have not been discussed really on the original project.
And since I'm blocked there - unless lovelydinosaur decides to change this - can I not further discuss this there.

This org and project SHOULD exist and be maintained. We shouldn't let this situation return to what it has been for the past year: an unmaintained project that only seems to act as a springboard to promote a v2 that throws out core parts of the original project, and that is maintained by what seems to be a misandrist (not mysoginist. They are different).

I REALLY hope this project here will remain.
I don't want MkDocs to die, but with its state on the original repo will it eventually die, resulting in the community losing a big project.

[mkusz]

The biggest problem I can with current approach to MkDocs is that it seems that the project is more or less dead. Is there something happening behind the scene? I don't know. I don't want to insinuate anything but if you take a look at hhtpx that is a project maintained by the same person, and that it's open version is stuck on v0.2x in December 2024, but there is a some private repo with v1.x that probably will be somehow paid or closed, I'm afraid that something similar can happen to MkDocs. What's more, there already been some moves made by most active developers (see Zensical) that are a "bad" sign.

[Andre601]

The biggest problem I can with current approach to MkDocs is that it seems that the project is more or less dead. Is there something happening behind the scene? I don't know. I don't want to insinuate anything but if you take a look at hhtpx that is a project maintained by the same person, and that it's open version is stuck on v0.2x in December 2024, but there is a some private repo with v1.x that probably will be somehow paid or closed, I'm afraid that something similar can happen to MkDocs. What's more, there already been some moves made by most active developers (see Zensical) that are a "bad" sign.

There is a v2 by lovelydinosaur.
It's primary focus as of right now seems to be about themes, while not providing any support for plugins (and even extensions I believe).
It's bare bones. And while that is to be expected from an early build, there was/is no mention that a plugin API will be added back. And according to squidfunk does the themeing API even lack stuff they used in MkDocs Material.

That's kinda all I know from it.

[Samoed]

and that it's open version is stuck on v0.2x in December 2024, but there is a some private repo with v1.x that probably will be somehow paid or closed

Here is open repo for httpx https://github.com/encode/httpnext. I didn't dig deep, but main change is splitting httpx to sync and async versions ahttpx

[DevTwilight]

As a user of MkDocs, I want to share a perspective from someone who depends heavily on this project and the ecosystem that has grown around it.

MkDocs has become much more than a simple static site generator. Over the years, a large ecosystem has formed around it — plugins, themes, integrations, and tooling that many developers and organizations rely on for their documentation. A huge amount of work has gone into building that ecosystem, and many projects depend on it being stable and maintained.

Because of that, what is happening right now is deeply concerning from a user perspective. The long period without releases, the growing backlog of issues and pull requests, and the visible conflict around the direction and governance of the project create a great deal of uncertainty for people who rely on MkDocs in production environments. Documentation infrastructure is something many teams expect to be stable and predictable, and the current situation makes that stability feel increasingly uncertain.

What worries me most is that the MkDocs ecosystem appears to be slowly getting destroyed. Not necessarily by a single decision or action, but through a combination of stalled maintenance, unresolved governance conflicts, and the absence of a clear and stable path forward for the project. When a project reaches this level of uncertainty, the damage often happens gradually: contributors lose confidence, maintainers step away, and users begin looking for alternatives even if they would prefer to stay.

The discussion around v2 increases that concern even further. From what has been publicly shared so far, v2 appears to significantly change the structure and priorities of the project. The current ecosystem is heavily built around plugins, themes, and extensions, and many existing projects depend on that flexibility. If v2 removes or fundamentally changes those capabilities without a clear compatibility path, it risks breaking a large part of the ecosystem that has taken years to build.

The plugin and extension system in particular is one of the core strengths of MkDocs. Many commonly used features today exist only because plugin authors and contributors built them on top of MkDocs' extensibility. If those extension points disappear or become incompatible, many of the things people rely on today may simply stop existing or require large rewrites.

At the same time, the current state of the project raises difficult questions about maintainership and governance. Healthy open source projects usually rely on collaboration between maintainers and the broader community. When contributors feel blocked, unheard, or unable to participate constructively, it can weaken the entire project. Seeing contributors being blocked from discussions and conflicts escalating publicly makes many users wonder whether the current governance model is sustainable in the long term.

This is not about attacking any individual, but about recognizing that the health of a large open source project depends heavily on trust, communication, and openness to community participation. When those things break down, the ecosystem around the project often begins to suffer as well.

What many users need right now is clarity and stability:

• whether the current MkDocs codebase will continue to be maintained
• what the long-term roadmap actually looks like
• how v2 is expected to interact with or support the existing ecosystem
• whether plugin and theme compatibility will remain a priority
• how contributors and ecosystem maintainers can meaningfully participate in shaping the future of the project

The MkDocs ecosystem represents years of effort from many contributors across the community. Plugin maintainers, theme authors, documentation writers, and users have all invested time and energy into building what exists today. It would be a real loss if that ecosystem continues to deteriorate because of uncertainty and conflict rather than technical limitations.

I sincerely hope a constructive path forward can be found that restores stability, improves collaboration, and allows MkDocs to continue thriving instead of slowly fragmenting.

[DevTwilight]

Hey, if it’s possible, I’d love to join the new org as a member. I can help with things like:

• Testing – checking releases, plugins, and themes for compatibility
• Documentation – writing small guides or instructions for users and plugin authors
• Community feedback – collecting input from users and plugin maintainers
• Discussions and coordination – joining conversations and helping keep things organized

I’d like to contribute more directly rather than just following along, but no pressure — I can help wherever it’s useful.

[oprypin]

Hi @DevTwilight , so far I only add people who have had long prior presence in related communities. I haven't seen you around at any previous point 😅

However your contributions will not be hindered by that, you can already do the listed things.

• For example, right now actually see Please try out our reestablished project #18

[ghost]

hmm I want of joining team for ProperDocs also, becoz @Andre601 say thi is community proejct 😞 but no? I have help with name a lot?

[Andre601]

hmm I want of joining team for ProperDocs also, becoz @Andre601 say thi is community proejct 😞 but no? I have help with name a lot?

Sorry, but your messages so far make no real sense. I assume you're using a bad translator here...
Tho, in general do we not add people simply because they want to be added, but because they made notable contributions to the open source community and especially the ecosystem that this project is living in.

Also, it was mentioned multiple times already, that this cannot be a "true democracy" managed project, meaning everyone has a say here.
We will try to engage with the community and regularely ask for feedback where it may be wanted, but this won't mean that everything done here will be done by the community's consensus.

[ghost]

do u sitll want me 2 help with logo? i like 2 make more opensource conrtibutions.

[oprypin]

Hi @ofek. This is misleading. The linked page literally says that most of (even popular) extensions are not supported. And none of the themes are supported.
The easiest migration path is to keep using the same project but just in a well-kept state. If you don't like that we make that option available, you can just ignore it.

[Andre601]

I'll mark this post as off-topic, as not only is it misleading for what oprypin mentioned, but it simply feels like a shameless ad for a product that currently (ab)uses the situation MkDocs is in, to promote itself to others, while nowhere being near a state that would allow someone to switch over without major drawbacks.