tl;dr: See only the last section.
This post is duplicated here for backup

For some background, I am a frequent contributor in the overall MkDocs ecosystem.

• MkDocs plugins
• Contributions or evangelism

I am coming here out of frustration that MkDocs as a project is stalled purely because its maintainer's main activity seems to be to respond to every request with "you shouldn't want MkDocs to let you do this". (This is oversimplified, but the post expands on the details).

I'm not looking to create drama, but I view this as my last chance to change something in a project that I can't bring myself to leave but is also very painful to stick with. And I did first try to resolve this privately.

First, a personal example. Consider my contribution #2272.
The topic of performance is very dear to me, as I want to make MkDocs viable for large API documentation sites, but I have seen multiple users of it complain to me foremost that it's unbearably slow.

I have fully proven the safety of this change (a ton of work went into proving the correctness to @waylan, much more than general work), then (after that PR stalled) I even split out any possible breaking changes into a separate PR #2296 (again putting a lot of work into that) so that the main one can become purely optimization.

And after all that, @waylan comes out of nowhere and blindly closes my PR. Once he made that decision, he 100% dismissed both my factual arguments and my feelings. There was no technical argument why the change is unacceptable, or consideration that further reworking it could help.

Well, since that was closed, and having spent another few months in anguish, I decided to send that contribution again (now further improved) in a new pull request, as nothing was shown to be wrong with the previous one. I have no idea if he's just going to lash out and insta-close it, or something worse. (Which is also why I'm sending out this post along with that pull request).

I have also sent an email directly to Waylan to discuss such organizational topics but got no reply (there's a possibility that it wasn't received, but more likely that it's more convenient to ignore), and I'm also getting no reply whenever I publicly mention such topics.

Of course, I'm not the only one who gets ignored.
Consider this thread with 3 other persons interested in a technical discussion about how to improve convenience for contributors. Well, @waylan is not interested in a technical discussion or others' convenience, he doesn't need to engage, because he's already convinced about something different (based only on preconceptions as far as I can tell) and he can win any argument by just closing it.

And I'm also not the only one frustrated.
#2311 (comment)

Now consider this contribution.
#2347
It is very simple, fully correct and compatible, and fixes an actual oversight. But @waylan wastes everyone's time with his cargo-cult arguments, and again, does whatever it takes to not admit that he was wrong. What does he do in the end? Replaces all usages of that (common) dependency with 2 new dependencies, so it's technically solved without admitting that fix (which should've been merged first in either case).

Then there's the big matter that he ignores the users' perspective, not just the contributors'.

Just consider the totally tone-deaf and uninformed replies to #1979.
And then the last phrase.

Given the above, I am going to leave this issue closed.

Yes... even though his conclusions for most of the conversation were based on the complete lack of understanding (and he didn't really try to understand), he just does whatever it takes to never admit that he was wrong.

I can also talk at length on plugins vs core features. Again, he never considers how much work it is to maintain a plugin vs adding a few lines to MkDocs. And the difference in discoverability of these two alternatives. Well, those are the main points, let's leave it at that; the rest is already said there.

This particular reload issue certainly causes confusion quite frequently, I've seen it a few times first-hand. An easily accessible config (or even a default) would be such a big benefit, as people often don't realize for a while that they're being hit by an outdated stylesheet. But he's not really a user of MkDocs, so he doesn't get it. And he's not interested whatsoever in figuring out how it can work (and it certainly can work, but he's already set on trying to prove that it can't).

Which also brings me to the next point. @waylan, as far as I can tell, is not an active user of MkDocs. He has no personal interest in improving it (must've already implemented all that he needed), and his perspective is very limited.

The largest site I have is less than 20 pages. I have the perception that my sites build instantly on my very old machine. Personally I see no need for performance improvements.

#2272 (comment)

His interest seems to lie in minimizing the effort for him. Every suggestion's first evaluation is "does absolutely every user of MkDocs benefit greatly from this" (in his opinion) and, even more so, "do I expect to be annoyed by this".
His personal convenience seems to have an oversized weight in the evaluation of benefits versus disadvantages. He doesn't see that there are thousands of users of MkDocs, and that if each of them gets a slightly better experience, the world overall becomes significantly better.

Meh. Not a priority. The amount of gain is not worth the extra burden.

#2272 (comment)

You may also say that he has a right to all this, because he's the only maintainer of MkDocs, and we can't afford to have him burn out.

But I'll tell you what -- I think that having @waylan as the gatekeeper is no longer the best option for MkDocs overall, compared to another universe where contributors are actually allowed to get something done.

There are certainly quite a few people popping up who could become good stewards for MkDocs development. But, they never get a chance to shine; I think people usually just leave after seeing how pointless it is.
I mean, when facing @waylan, you're facing a gatekeeper foremost, and you immediately have to take a defensive stance on everything, because his initial stance is always to try to prove that your change isn't worth his time. It's a mentally taxing game where in any given discussion anything you say can arbitrarily permanently sway his opinion towards dismissing you.

So, this perpetuates the situation where @waylan remains the only maintainer, and he gets to complain that he has little time.

Certainly, in the time that I spent pointlessly trying to convince @waylan of anything, I could've already brought the project far forward.

So, why don't I just fork MkDocs and move on? I definitely have the technical ability and the time to maintain MkDocs if it comes to that. And I do already persist some modifications locally.

However, a fork has almost 0 chance of taking off, so there's no point to it. A big issue is actually a technical one: it would be impractical to install such a fork through pip. If I use a different PyPI identifier for the project (mkdocs2 as a horrible theoretical example), then all plugins still depend on mkdocs, causing duplication and conflicts. And if I use the same module name (without being able to go to PyPI), then there's no nice way to install it (installing directly from Git is very underdeveloped in pip, as there's no support for versioning, upgrades, caching, etc.; and secondary package indexes are also not supported).

(So, the position of @waylan as the only person who decides which features MkDocs gets to have is permanently cemented.)

This is not supposed to be a situation where @waylan should feel obligated to defend himself. There's no point to it and he may as well just ignore this too; nobody's going to listen to what I say anyway.

The point is to gauge whether there's interest in a better maintenance model for MkDocs. One that is based on experience of people who use and develop against MkDocs. Based on considering factual pros and cons -- and with the weights accounting for the benefit of the collective user base, rather than the opinion of 1 person.

Namely, I suggest technical decisions to be immediately made open for input from prominent contributors and plugin authors. If they review a pull request, they can formally approve it, which at the beginning might be just a signal for @waylan to withhold his veto power. The same would apply to responding to user-reported issues.

And I sure hope that a decision is made for MkDocs to be more welcoming; it's honestly better for everyone, even likely @waylan, as he will no longer need to bear the weight alone.
Perhaps it'd be useful for pull requests to receive feedback from other people. Currently it's mostly @waylan (who doesn't like meddling in his business, so I gave up on that as well). And @waylan's words are often hurtful -- I believe only unintentionally, but still.

In any case, I definitely prefer a solution that includes @waylan, as he is still the most valuable contributor.

If you support an initiative where you become one of the reviewers on MkDocs, among equally respected peers, please react here with a "Rocket" emoji.
(Other "reactions" are still open for arbitrary use)