Details on forking and renaming the project (it's feasible!)

[oprypin]

Hi everyone,

The current thinking regarding what we could do in our situation is that we just have to fork and rename the project.

There simply isn't any option not to fork, because the owner of the original project has completely blocked or disregarded every possibility of a direct continuation. We need to assume that what you install as mkdocs will be replaced with the "Version 2" project. And while that is happening, we here will try to keep the MkDocs-based ecosystem working but just through a project with a different name.

(Even this GitHub organization's name is now to be considered just a placeholder. Please add your name ideas in #5)

Myself and a few others have been saying that a fork is not technically feasible. The specific problem is that because every plugin depends on the mkdocs package, it is guaranteed to be installed even if though it's entirely unwanted. This negative effect will pretty much always linger with us and nothing really can be done about it. However it's also not such a big problem, because that installed package can simply be ignored.

The other technical problems, while they may seem even worse, actually all have a clever workaround, which I've just tried out today:

• All themes are registered as mkdocs.themes entrypoints. (And they use mkdocs_theme.yml for the filename).

This one is actually trivial - we just support those names as well, but also give preference to our own new name.

• All plugins do import mkdocs.whatever in Python code and would have to be migrated.

Actually there's a way to run plugins without migrating them! The executable of our new project could set up interception for any attempts to import mkdocs.* and instead provide those imports itself. Not by physically providing the files, but with a metaimporter.

With this, existing plugins and themes will actually work under the new project without even any modification required.
Plugin authors can still use imports from mkdocs with no changes, and in that way be compatible with both projects for now.

We could encourage plugin authors to fully drop support of mkdocs and migrate to our namespaces, but we could do even better - make a coordinated effort of adding warnings that the "mkdocs" project has plans to break all usages and the users need to simply install this different project instead of mkdocs to stay safe, and it is guaranteed to be a drop-in replacement.
The plugins should also all pin mkdocs <= 1.6.1 for extra safety. Adding the unneeded dependency won't hurt because mkdocs will almost certainly be installed through something anyway.

Having all this, we will have a positive network effect where if at least 1 plugin is on our side, the user will get a warning to migrate to the continuation project and will be guarded against "Version 2".
This is much better than the negative network effect we were all imagining where if at least 1 plugin is not migrated, everything is broken.

[EddyLuten]

The specific problem is that because every plugin depends on the mkdocs package, it is guaranteed to be installed even if though it's entirely unwanted. This negative effect will pretty much always linger with us and nothing really can be done about it.

I think this is the biggest technical hurdle, as I've explored before here. Getting around this will be paramount since mkdocs without plugins isn't too much to write home about.

Actually there's a way to run plugins without migrating them! The executable of our new project could set up interception for any attempts to import mkdocs.* and instead provide those imports itself. Not by physically providing the files, but with a metaimporter.

I guess as long as you're installed first, you could maybe also symlink mkdocs -> mkdocs-community in the lib dir? A bit hacky, though.

[oprypin]

I haven't done research into replacing the executable, I just assumed it's not viable or unreliable or too hostile.
Instead, the strategy would be that: if you run the new project's executable directly, everything gets wired up correctly, whereas if you run "mkdocs", the participating plugins initiate loud warnings that you should be running the other executable.

[DevTwilight]

Thanks for taking the time to dig into this and test the approach.

The meta-importer idea to handle mkdocs.* imports is pretty clever, and it’s good to hear that existing plugins and themes could still work without immediate changes. That was one of my biggest concerns when the idea of a fork first came up.

The warning strategy through plugins also sounds like a practical way to help users avoid accidentally ending up on the incompatible version.

Happy to help if that would be useful.