跳转至

MkDocs 的恩怨情仇史 🤔

原文：The Slow Collapse of MkDocs
译文：MkDocs 的缓慢崩溃，感谢 @维燕的数字花园 的辛苦翻译


给大家分享一篇来自 Florian Maas 在 2026 年 3 月 22 写的《The Slow Collapse of MkDocs》文章，看看性格冲突、创始人缺席以及备受争议的重新设计如何导致 Python 最受欢迎的项目之一分崩离析。

2026 年 3 月 9 日， MkDocs 的一位前维护者接管了 PyPI 代码库的控制权，并撤销了原作者的权限。原作者迅速作出回应：
collapse-mkdocs-1

然后他们提交了一份 PyPI 支持工单 以重新获得控制权，但在工单得到处理之前，问题就已得到了解决。

MkDocs 为超过 90,000 个 GitHub 项目提供文档支持，其中大多数项目都依赖于由 @squidfunk 开发的 Material for MkDocs 主题，该主题非常受欢迎，其获得的星标数甚至超过了 MkDocs 本身。

PyPI 被接管事件不过是更深层次问题的一个最为显眼的症状表现。如今，任何使用 Material for MkDocs 的人都会在终端中看到以下警告信息：
mkdocs-2-warning

MkDocs 项目已经超过 18 个月没有进行任何实质性的开发。Material for MkDocs 目前处于维护模式。而曾经两大主导工具携手共进的局面已不复存在，如今有多款工具竞相涌现，试图取而代之：如 ProperDocs、MaterialX（"新一代的 mkdocs-material"）以及 Zensical（"由 Material for MkDocs 开发者打造的现代化静态网站生成器"）。

我们怎么会走到这一步？要了解事情的全貌，我们需要稍微回顾一下过去 ……

2014年1月11日 - MkDocs 诞生

2014 年 1 月 11 日，Mia Kimberly Christie（ @lovelydinosaur ）提交了第一个代码 ，也就是后来的 MkDocs，并附上了 "Hell yeah" 的消息。接下来的几个月里，提交数量激增。

这种活跃期并没有持续太久。到 2014 年年中，他们在代码库中的活动就完全停止了。
lovelydinosaur-commits-2014

其他开发者也加入了这个项目，比如 @d0ugal 和 @waylan。@lovelydinosaur 此后便不再活跃，而在 2016 年 7 月至 2021 年 7 月期间，@waylan 似乎是该项目的唯一维护者。
waylan-commits

该项目越来越受欢迎，到 2022 年年中，该项目在 GitHub 上积累了超过 14,000 个星标 。

2020年4月27日 - oprypin 加入了该项目

2020 年 4 月 27 日，新贡献者 @oprypin 首次为该项目做出贡献：提交了一个 bug 修复方案。@waylan 同意了这些更改，并合并了 PR。

waylan-20200427

在首次提交贡献后，@oprypin 有大约半年时间未参与该项目，之后他又进入了一段长时间的高频活跃期；修复 bug、添加新功能等等，不一而足。

@oprypin 和 @waylan 之间似乎存在一些摩擦。例如，@waylan 就不同意 @oprypin 提出的一个 潜在的性能 改进方案：
waylan-oprypin-2104

2021年5月16日 - waylan 下台

@oprypin 的不满情绪日益加剧，最终他发起了一个题为 "关于 MkDocs 维护工作的担忧（Concerns about maintainership of MkDocs）" 的讨论帖。在这篇长文中，他指责 @waylan 对项目进行独断专行式的管控，且在没有技术依据的情况下拒绝他人贡献，并提出了另一种维护模式，以减轻单一维护者的责任负担。
oprypin-210516

他将该 帖子的副本 发布到他自己 fork 的仓库中。两个帖子均未引发过多讨论，但普遍共识是，尽管事实与观点难以分辨，但该帖子过于针对个人，项目原作者（且基本已不再活跃）也提到了这一点：
lovelydinosaur-210517

就在 @oprypin 发起讨论的同一天，@waylan 宣布退出该项目：
waylan-210517

2021年6月7日 - oprypin 接管

由于 @waylan 已不再担任项目维护者，因此需要新的维护者。@lovelydinosaur 发起了一项讨论，征求关于维护者人选的建议。@oprypin 立即表示他愿意接手项目的维护工作。
oprypin-210607

@lovelydinosaur 并没有立即接受他的提议，但 @oprypin 希望继续开发这个项目，所以几周后他又回到了这个帖子：
oprypin-210621

一段时间后，@lovelydinosaur 似乎不太愿意授予 @oprypin 项目写入权限，且回复迟缓，此时 Material for MkDocs 的原作者兼维护者 @squidfunk 也加入了讨论。
squidfunk-210703

之后，@lovelydinosaur 邀请了一群维护者加入 MkDocs：
lovelydinosaur-210705

大约一年后，@oprypin 请求提升对 Github 仓库和 PyPI 项目的权限：
oprypin-220602

获得所有者权限后，@oprypin 成为 MkDocs 的主要维护者。在接下来的两年里，他与其他维护者和贡献者一起稳步推进项目。修复 bug、更新依赖项、添加新功能，项目持续向前发展。
oprypin-commits-2024

请注意，由于 @oprypin 目前已被禁止参与该项目，因此无法在 MkDocs 存储库中找到上述图表中的数据，但仍然可以在 MkDocs 的分支中找到，例如这里。

2024年2月25日 - 紧张局势公开爆发

一次常规的文档问题讨论，因 @squidfunk 在帖子中指责 Read the Docs 从 MkDocs 项目中获利却未回馈社区而升级，演变成了另一回事。@oprypin 趁机表态：
oprypin-240226

@squidfunk 回复：
squidfunk-240229

随后，双方公开长篇追溯过往恩怨：@oprypin 坚称 自己并无过错，@squidfunk 则回忆 曾作为 @oprypin 的首位赞助者，力排众议推荐其加入 MkDocs 团队，但因多次个人冲突，最终选择将沟通限制在公开渠道。

在完成对文档小问题的修复后，该问题被标记为已解决。

2024年3月16日 - oprypin 将 squidfunk 从组织中移除

我们回到之前的帖子，@lovelydinosaur 在其中宣布他们已将 @oprypin、 @squidfunk 和 @ultrabug 添加为该项目的维护者。

3 月 16 日，@squidfunk 发帖：
squidfunk-240316

原来，这个决定是 @oprypin 独自做出的：
oprypin-240316

不久后，@lovelydinosaur 加入讨论，恢复了 @squidfunk 在 MkDocs 组织中的成员身份，并撤销了 @oprypin 对代码仓库的所有权。

2024年4月6日 - oprypin 下台

4 月 6 日，@lovelydinosaur写道：
lovelydinosaur-240406

三个小时后，@oprypin 宣布他将从 MkDocs 项目卸任。在他的帖子中，他详细阐述了他与 @squidfunk 的分歧、对 @lovelydinosaur 介入的不满，以及维护该项目的孤独感：
oprypin-240406

他决定协助团队于 2024 年 4 月 20 日发布 1.6.0 版本，除同年 8 月 30 日发布的 1.6.1 版本外，截至本文撰写时该版本仍是最新版本。

2024年4月8日 - 社区短暂集结

@oprypin 卸任两天后，活跃社区成员兼 mkdocstrings 作者 @pawamoy 在一个题为 "推动 MkDocs 迈向新高度" 的帖子中，邀请约 25 位插件和主题作者共同参与 MkDocs 的维护工作，反响热烈。@squidfunk 表示对此 "深感振奋（eally psyched to see this happening）"，他还补充道：
squidfunk-240422

4 月 23 日，在 @oprypin 发布最后一个版本几天后，@lovelydinosaur 发帖宣布 将回归担任首席维护者。此时，距离其 上一次向代码仓库提交的拉取请求被合并 已过去整整八年。其明确目标为：MkDocs 应拥有 "独立于Material for MkDocs的强有力领导团队"。他们标记了 28 位社区成员，并安排了周六的线上电话会议。

会议如期举行。@squidfunk 拒绝参加。仅两人到场。此后十八个月，该帖子再无公开活动记录。

2024年5月17日 - lovelydinosaur 回归

由于 @oprypin 不再参与该项目，MkDocs 的开发基本上停止了。
commits2024

在向 MkDocs 提交部分拉取请求的同时，他们还开始在 mkdocs/sketch 代码库中着手对 MkDocs 进行重新设计。

2024年8月1日 - 无需插件的重新设计

@lovelydinosaur 向 MkDocs 核心团队展示了其提出的 MkDocs 重新设计方案演示。MkDocs 目前会一次性构建整个站点，而新方案则按需动态生成页面。此提议引发了维护者及核心贡献者的担忧：
alexvoss-240801

在另一个无关的讨论帖中，@lovelydinosaur 表示其正致力于对 MkDocs 进行无需任何插件的重新设计。
lovelydinosaur-240820

该帖子收到的反对票表明，这并非社区真正希望看到的。

2024年8月30日 - MkDocs 的最新版本

MkDocs 1.6.1 版本已发布。截至目前，这仍是最新版本，除对文档进行一两次修订及更新持续集成（CI）徽章外，该代码库没有进行任何积极的开发。

2025年7月17日 - 这个项目被搁置了吗？

插件作者 @facelessuser 发起了一个直接提问的讨论：
facelessuser-250717

他指出，尽管有积极的赞助商，但修复 bug 的 PR 已经几个月没有经过审核了。

@pawamoy 的回应清晰呈现了自 2024 年 4 月以来发生的情况。他表示曾尝试围绕 @lovelydinosaur 的回归构建协作维护模式，却发现 @lovelydinosaur 对现有代码库兴趣寥寥，转而专注于重新设计。当 @pawamoy 致力于整理待办事项列表并尝试维护项目的同时，@lovelydinosaur 在被提及 PR 时却杳无音信。
pawamoy-250723

@lovelydinosaur 回复称，其一直专注于当前处于早期预发布阶段的 httpx 1.0 项目，并正在考虑是否有时间为 MkDocs 腾出时间。@facelessuser 回应如下：
facelessuser-250724

8 月 3 日，大约十天后，@oprypin 自离开后首次重新出现在该帖子中。他提出回归的条件只有一个：
oprypin-250803

@lovelydinosaur 没有回复。

2025年10月15日 - 幕后工作仍在继续

当 MkDocs 用户纷纷要求修复漏洞时，@lovelydinosaur 却在另一个尚未公开的代码库（encode/mkdocs）中继续推进 MkDocs 的重新设计工作。

2025年11月11日 - squidfunk 宣布推出 Zensical

2025 年 11 月 11 日，mkdocs-material 9.7.0 版本发布，同时宣布 Material for MkDocs 项目进入维护模式。与之同步发布的还有 Zensical —— 一款由 Material for MkDocs 团队全新打造的现代化静态网站生成器。团队表示，该工具可原生解析现有 mkdocs.yml 配置文件，重建速度提升5倍，并配备全新设计的搜索引擎。

在 2024 年 4 月的维护者讨论帖中（该帖已沉寂数月），有人发布了一篇博文链接，并询问 Material for Mkdocs 进入维护模式是否意味着 MkDocs 需要重新开始。@oprypin 再次出现，指出 Zensical 就是一个新的开始。关于 MkDocs，他说道：
oprypin-251107

在 Material for MkDocs 宣布进入维护模式几周后， @jaywhj 发布了 MaterialX 的第一个版本，它是 Material for MkDocs 的延续。

2026年1月14日 - MkDocs 2.0

2026 年 1 月 14 日，@lovelydinosaur 表示，欢迎他人发布 MkDocs 1.6.2 版本，而其正私下开展 MkDocs v2 的开发工作。

然后，在 1 月 21 日，@lovelydinosaur 发起了一个讨论 ，宣布推出 MkDocs 版本 2：
lovelydinosaur-260121

绝大多数用户都持负面态度。。社区认为，拟议的 MkDocs 2.0 主要缺点在于缺乏插件支持，而插件正是 MkDocs 最初成功的关键所在。
twardoch-260218

@facelessuser 道出了社区中许多人的心声：
facelessuser-260203

@oprypin 一个月前也表达了相同观点。社区成员注意到，MkDocs 2.0 版本代码库被放置在 encode 组织而非 MkDocs 组织下，且 encode 组织的贡献指南明确禁止提交 issue 或 pull request。他们还强调，不公开源代码违背了开源软件开发的原则。最终，@lovelydinosaur 解释了该代码库设为私有的原因：
lovelydinosaur-260203

2 月 13 日，@lovelydinosaur 删除了关于计划使 MkDocs 2.x 向后兼容 MkDocs 1.x 的通知。

2 月 18 日，Material for MkDocs 团队发布了一篇详尽的博客文章，全面分析了 MkDocs v2 版本为何与其工作及更广泛的插件生态系统不兼容，涵盖从移除插件系统到缺失许可证等诸多问题。

2026年3月9日 - PyPI 接管事件

2 月 18 日，Material for MkDocs 在每次 mkdocs 构建时均显示警告信息，提醒用户可能存在与 MkDocs 2 未来不兼容的问题，并附上上述博客文章链接。

@oprypin 此前提出的获取 PyPI 所有权的请求已于过去某个时间获得批准。虽然他在 2024 年卸任后，其对 GitHub 代码库的权限已被剥夺，但他对 PyPI 仓库的权限仍然有效。

3 月 9 日，为防止用户项目因意外升级至不受欢迎的 MkDocs 2.0 版本而受损，@oprypin 采取最后手段，利用其权限将所有其他维护者（包括原作者 @lovelydinosaur）移出项目。他在 GitHub 的两个讨论区宣布接管：一个在 mkdocs（后被编辑），另一个在 mkdocs-community（该组织后更名为 ProperDocs）。其核心理由是，静默发布 v2 版本会导致运行 pip install mkdocs 的用户意外地破坏他们的项目。他随后在 mkdocs-community/mkdocs 创建新仓库，宣布未来 PyPI 版本将由此发布，并呼吁社区支持。

@lovelydinosaur 向 PyPI 提交了支持工单 ，并将 @oprypin 排除在 MkDocs GitHub 组织之外。

6 小时内， @oprypin 做出让步并道歉：
oprypin-260310

@lovelydinosaur 重新获得 PyPI 访问权限。

在另一场讨论中， @Andre601 表达了他对项目现状的担忧，并就项目维护的未来提出了各种问题， @lovelydinosaur 对此作出了回应：
lovelydinosaur-260309

2026年3月15日 - oprypin 推出 ProperDocs

在接管 PyPI 六天后，@oprypin 正式发布 ProperDocs：一款可无缝替代 MkDocs 1.x 的工具。用户只需将 pip install mkdocs 替换为 pip install properdocs，将 mkdocs build 替换为 properdocs build 即可。现有插件无需修改代码即可使用。该项目还发布警告，引导用户远离 MkDocs 2.0。

那么，如今的情况又如何呢？

原 MkDocs 代码库已有 18 个月未进行实质性开发。其原作者兼唯一维护者 @lovelydinosaur 正在推进一项缺乏社区支持且会破坏现有插件生态系统的重新设计。encode/mkdocs v2 代码库自 2026 年 2 月 19 日起已停止更新。

与此同时，构建该生态系统最广泛使用组件的核心人员已转向其他项目。

@oprypin 表示，继续推进需要双方达成一致，但认为此举难以成功，因此独立启动了 ProperDocs 项目。该项目并未立即获得巨大成功，一周后，它在 GitHub 上获得了 21 个星标。

@jaywhj 正在维护 MaterialX，由于原项目 Material for MkDocs 进入了维护模式，该项目似乎在社区中获得了一些关注。

负责 MkDocs Material 的 @squidfunk 团队已停止开发，转而从零开始构建 Zensical。MkDocs 生态系统中最活跃的贡献者之一 @pawamoy 也加入了该项目。截至撰写本文时，Zensical 在 GitHub 上已获得超过 3700 个 star，目前看来是最受欢迎的项目，因此它也极有可能成功，并在未来取代 MkDocs。

MkDocs 生态系统正在实时分裂。三个继任者，三种愿景，以及一个需要决定押注哪一方的社区。