关于组织网站变更的说明公告（学思学习讨论研究所[2026]02号）¶

2026年3月21日wilber-20130410提交今日的网站更新时发现Github Actions中有如下警告：

│ ⚠ Warning from the Material for MkDocs team
│
│ MkDocs 2.0, the underlying framework of Material for MkDocs,
│ will introduce backward-incompatible changes, including:
│
│ × All plugins will stop working – the plugin system has been removed
│ × All theme overrides will break – the theming system has been rewritten
│ × No migration path exists – existing projects cannot be upgraded
│ × Closed contribution model – community members can’t report bugs
│ × Currently unlicensed – unsuitable for production use
│
│ Our full analysis:
│
│ squidfunk.github.io/mkdocs-material/blog/2026/02/18/mkdocs-2.0/

---

WARNING: MkDocs may break support for all existing plugins and themes soon!

The owner of MkDocs has completely abandoned maintenance of the project, and instead is planning to publish a “version 2” which will not support any existing themes, plugins or even your configuration files. This v2 may eventually replace what you download with pip install mkdocs, suddenly breaking the build of your existing site.

To avoid these risks, switch to ProperDocs, a continuation of MkDocs 1.x and a drop-in replacement that supports your current MkDocs setup. Simply install it with pip install properdocs and build your site with properdocs build instead of the MkDocs equivalents.

Alternatively, to just skip this warning in the future, you can set the environment variable DISABLE_MKDOCS_2_WARNING=true.

For more info visit ProperDocs/properdocs#33 and properdocs.org/

(This warning was initiated by one of the plugins that you depend on.)

---

经调查发现，网站所使用的Mkdocs社区传来了噩耗，维护者放弃了Mkdocs 2.0对Mkdocs 1.x版本的兼容支持。

原代码维护者发表的博客原文翻译如下：

MkDocs 2.0 对你的文档项目意味着什么¶

最后更新：2026年3月10日——详见更新日志。

---

三周前，MkDocs 2.0 发布——这是对成千上万项目依赖的文档工具的彻底重写，带来了潜在重大的破坏性变更。

MkDocs的材料依赖于MkDocs作为其底层框架和核心依赖。我们维护MkDocs的材料，但对MkDocs本身没有控制权。

我们花时间对 MkDocs 2.0 预发布进行了全面评估和测试，并希望分享我们的发现，包括它对您的文档项目可能意味着什么，以及我们兼容 MkDocs 1.x 的新静态站点生成器 Zensical 在其中扮演什么角色。

如果你错过了：MkDocs 1.x 未维护，问题和 PR 不断堆积，过去 18 个月内没有发布，似乎也没有修复诸如活载存问题等长期存在的问题。更重要的是，目前尚不清楚安全问题是否会得到解决，以及项目未来是否会有任何更新。

请注意，MkDocs 2.0 仍处于预发布阶段，本文信息基于项目当前状态。我们会随着最新了解持续更新。

MkDocs 2.0 中有哪些变化¶

根据官方公告、已发布的路线图以及项目维护者的多项先前评论和声明，MkDocs 2.0 旨在从零开始重写项目以降低复杂性——同时也带来了一些重要的权衡：

• MkDocs 2.0 与 Material for MkDocs 不兼容——如果你的文档是用 Material for MkDocs 构建的，它将无法在 MkDocs 2.0 上使用。Material for MkDocs 广泛使用 MkDocs 1.x 的模板和插件系统，而 MkDocs 2.0 引入的变更不向下兼容。

• MkDocs 2.0 不会有插件系统——MkDocs 2.0 正在重写，重点是主题化，故意移除插件支持以简化代码库。我们相信插件生态系统是 MkDocs 成功和广泛采用的基石之一，其移除将影响团队长期以来建立的工作流程和定制。

• MkDocs 2.0带来了主题的重大变革——MkDocs 2.0带来了全新重写的主题系统。例如，导航以预渲染的HTML传递给主题，而非结构化数据。这使得技术上无法实现导航标签、可折叠部分及其他高级导航模式。

  它还限制了主题中导航的样式，因为导航的 HTML 无法调整以适应主题的结构和设计。

• MkDocs 2.0采用封闭贡献模式——MkDocs 2.0转向“维护者驱动的问题”模式，社区成员被要求不要打开问题或拉取请求，且“功能请求通常不被接受”。用户在遇到问题时应如何报告漏洞或寻求修复尚不清楚。

• MkDocs 2.0目前未获得许可——MkDocs 2.0没有明确规定许可，这会影响社区如何使用和贡献。这一决定背后的理由尚不清楚，但依赖MkDocs文档项目的团队和组织应当进行批判性评估。

• MMkDocs 2.0 采用了新的配置格式——MkDocs 2.0 使用 TOML 进行配置，这与 MkDocs 1.x 中使用的 YAML 格式不兼容。因此，现有mkdocs.yml文件目前无法在 MkDocs 2.0 上使用。现有项目没有迁移路径。

尚未公布上映日期，因此围绕具体时间表进行规划仍然困难。不过，维护者多次暗示了该方向，预发布版本已确认这些变更对现有项目的影响。

这对你意味着什么¶

值得关注的是：MkDocs的长期方向正在以与许多文档团队及其工具目前运作方式不同的方向转变。

虽然你现有的 MkDocs 项目今天应该能继续运行，但请注意，MkDocs 1.x 的未来更新可能性不大。MkDocs 2.0 目前的形式并非 MkDocs 1.x 的直接替代，也没有为现有项目提供明确的迁移路径。

如何禁用 MkDocs 2.0 不兼容警告

从Mkdocs 9.7.2的Material开始，在构建过程中会显示关于即将到来的MkDocs 2.0变更的警告。我们添加此警告，旨在确保用户了解 MkDocs 2.0 对其项目的潜在影响，并鼓励他们评估选项并据此规划。

要禁用此警告，请设置以下环境变量：

1	export NO_MKDOCS_2_WARNING=1

我们很早就提出了担忧¶

鉴于维护者在2024年8月的公开视频通话中已向我们展示了他的计划，这一切对我们来说并不意外。由于不确定维护者是否会执行这些计划，我们只在脚注中提及，但 MkDocs 2.0 的预发布版本确认现有项目将有重大破坏性变更：

以下是事件时间线的总结：

在我们向 MkDocs 维护者提出此问题后，维护者职位于 2024 年中期发生变化，开始从零开始重写，旨在解决加载缓慢的问题，仅渲染当前构建的页面。目前尚不清楚该重写将如何与现有插件的需求集成。复杂插件如 mkdocstrings 或我们内置的博客和标签插件需要协调构建所有页面，以准确解析页面间链接和计算资源，而这些数据必须先构建整个项目。

更新：新维护者现在公开表示，他正在开发一个不需要也不支持插件的新版本 MkDocs，并提到它将通过模板、主题和样式等自定义功能实现同样的功能，他在8月1日的团队会议中也向我们和其他几位用户提及了这一点。在这次电话会议中，我们多次提出反对意见，质疑这将如何影响生态系统，但都无济于事。没有提供插件支持的意图或路线图。这一发展与我们的目标相契合，旨在通过模块化赋能用户和组织将核心框架适应自身需求。我们正在努力解决这一问题，并为我们的社区提供前进的道路。

一旦得知这些计划，我们立刻开始着手开发后来成为Zensical的产品——一款新的静态站点生成器，设计上向下兼容MkDocs 1.x，并为现有文档项目提供可靠的长期归宿。

多年来，我们一直在内部改进MkDocs。我们编写了12个插件，这让我们深入理解了插件API的局限性。我们对生态系统进行了定量和定性分析，以找出MkDocs的不足之处，并与数十个组织和关键生态系统成员进行了交流。我们提出这些问题，但屡屡无果。当MkDocs 2.0的新方向显现时，思考已经完成。

我们曾考虑分叉 MkDocs，但很快意识到不可行：生态系统中的每个插件都直接依赖于 ，这意味着分叉 MkDocs 需要分支其 300 个插件中的每一个—— 就像一次性搬迁整个城市 一样。¹

由于分叉不切实际，我们不得不从头开始。

Zensical的用武之地¶

Zensical设计为 MkDocs 1.x的直接替代 ，目标是让你在不做任何更改的情况下构建现有项目。我们还没有完全达到那个目标——支持生态系统中最受欢迎的MkDocs插件是一项雄心勃勃的任务——但这是我们当前的重点，我们全力以赴实现目标。

与其把这当作营销推介，我们鼓励你阅读公告，如果你想了解Zensical与MkDocs的不同，以及你现在可以期待什么。此外，我们网站的兼容性部分还概述了哪些功能已支持且未做更改。

我们还鼓励您自行调研，评估对项目的影响，并考虑所有可用选项。如果您曾专业依赖 Material for MkDocs，重视我们的工作，并希望找到明确的前进路径，我们提供迁移的实际支持。

如果你有任何问题，欢迎随时联系 hello@zensical.org 的Kathi。

更新¶

• 2026年3月10日：我们发布了9.7.5版本，限制了MkDocs的版本范围。这确保了即使发布了 MkDocs 2.0，你的构建也能继续正常工作。

• 2026年3月10日：3月9日移除的维护者包访问权限似乎已恢复问权限似乎已恢复，包括MkDocs的原始创建者。

• 2026年3月9日：前任维护者更改了PyPI²上mkdocs包的所有权，移除了所有其他维护者，包括MkDocs原始开发者的访问权限。

• 2026年3月4日：我们添加了一段，说明之前试图解决这一问题的尝试均未成功，以及我们为何决定为社区寻找新的道路。

• 2026年3月3日：我们新增了一段关于MkDocs 2.0采用的新贡献模式，以及从我们角度看对用户和贡献者的影响。

• 2026年2月27日：我们在环境变量NO_MKDOCS_2_WARNING上添加了说明，以禁用Material for MkDocs中MkDocs 2.0不兼容警告。

• 2026年2月19日：发布的MkDocs 2.0路线图已被删除。链接现在指向一个问题评论，其中包含最后版本路线图的截图。

• 2026年2月13日：MkDocs 1.x 和 MkDocs 2.0 项目计划兼容的相关内容已从 MkDocs 2.0 README.md 中移除。

经过研究决定，网站决定从Mkdocs切换到properdocs，这是一个完美的替代品。

学思学习讨论研究所

2026年3月21日