You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: docs/blog/posts/mkdocs-2.0.md
+12-2Lines changed: 12 additions & 2 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -95,7 +95,14 @@ The moment we learned about these plans, [we immediately started working] on wha
95
95
96
96
For years, we were trying to improve MkDocs from within. We authored [12 plugins], which gave us a deep understanding of the plugin API's limitations. We conducted quantitative and qualitative analyses of the ecosystem to identify where MkDocs was falling short and talked to dozens of organizations and key ecosystem members. We raised these issues and repeatedly got nowhere. When the new direction of MkDocs 2.0 became apparent, the thinking was already done.
97
97
98
-
We considered forking MkDocs, but quickly realized it wasn't viable: every plugin in the ecosystem has a direct dependency on `mkdocs`, which means forking MkDocs would require forking every single one of its [300 plugins] – __like moving an entire city at once__.
98
+
We considered forking MkDocs, but quickly realized it wasn't viable: every plugin in the ecosystem has a direct dependency on `mkdocs`, which means forking MkDocs would require forking every single one of its [300 plugins] – __like moving an entire city at once__.[^1]
99
+
100
+
[^1]:
101
+
Forking is technically feasible by interposing on all MkDocs imports at runtime using Python's import hook machinery (i.e., custom `sys.meta_path` finders/loaders or `importlib` wrappers). In this model, one effectively shadows MkDocs modules by resolving import requests to alternative implementations, or by proxying and patching objects during module initialization.
102
+
103
+
However, this approach fundamentally relies on strict API and behavioral compatibility with MkDocs' internal module graph. Because imports are resolved dynamically and cached after first load, any divergence in function signatures, class layouts, side effects, or import order can introduce subtle breakage. As a result, all internal APIs – not just the public surface – must be preserved with near-exact fidelity.
104
+
105
+
In practice, this reduces the "fork" to a thin layer of indirection rather than a true divergence. Core functionality cannot be meaningfully refactored or redesigned without violating the implicit contracts embedded throughout the codebase. Consequently, the deeper systemic and structural limitations of MkDocs 1.x remain effectively unchanged under this strategy.
99
106
100
107
With forking being impractical, we had to start from scratch.
101
108
@@ -132,7 +139,10 @@ _If you have any questions, feel free to reach out to Kathi at hello@zensical.or
132
139
133
140
-__March 10, 2026__: Access to the `mkdocs` package for the maintainers removed on March 9 [seems to have been restored](https://github.com/orgs/ProperDocs/discussions/1#discussioncomment-16060966), including the original creator of MkDocs.
134
141
135
-
-__March 9, 2026__: One of the previous maintainers [changed ownership of the `mkdocs` package on PyPI](https://github.com/orgs/ProperDocs/discussions/1#:~:text=Summary%3A%0AI%20have%20retaken%20the%20mkdocs%20name%20on%20PyPI%20and%20will%20attempt%20to%20resume%20the%20maintenance%20of%20MkDocs%20at%20https%3A//github.com/mkdocs%2Dcommunity/mkdocs%20(new%20repo).), removing access for all other maintainers, including the original creator of MkDocs.
142
+
-__March 9, 2026__: One of the previous maintainers [changed ownership of the `mkdocs` package on PyPI](https://web.archive.org/web/20260310162839/https://github.com/mkdocs/mkdocs/discussions/4089)[^2], removing access for all other maintainers, including the original creator of MkDocs.
143
+
144
+
[^2]:
145
+
The link points to the web archive, as the original post has been edited multiple times by the previous maintainer.
136
146
137
147
-__March 4, 2026__: We added a paragraph explaining that prior attempts on resolving the situation were unsuccessful and why we decided to find a new path for our community.
0 commit comments