我们对 MkDocs 的延续

Source: Hacker News

介绍

你好，MkDocs 社区的朋友们！

你可能认识我，曾是 MkDocs 的前任（也是最近一次活跃的）维护者。

我欢迎大家加入我们从 MkDocs 停留之处继续前进的项目，名为 ProperDocs。你已经可以直接安装它，并将其作为 MkDocs 的直接替代品使用。

我们需要你的支持！请帮助传播这个消息，来打个招呼，并将相关问题提交给我们关注！

插件作者也可以帮助我们进一步向用户传播此警告。（更多信息请见帖子底部）

为什么需要这样做

可悲的是，当前 MkDocs 完全无人维护。原作者在过去的两年里一直掌控着项目，却完全忽视所有反馈和所有新提交的问题。提出接手维护的请求也被忽略。他们甚至公开声明存在性别偏好，让所有人感到非常困惑。

他们最新的计划是重新使用项目名称，并在其下发布一个全新的文档生成器。这将导致所有为 MkDocs 制作的主题和插件失效，且没有提供任何替代方案。社区的反馈也未受到欢迎。

因此，使用 pip install mkdocs 实际上是在进行一次持续的赌博——不确定何时会出现这种破坏。

为用户提供的解决方案

我们欢迎您切换到 ProperDocs，这是我们精心打造的 MkDocs 分支。目前它是 MkDocs 的完全兼容替代品，只是加入了一些关键的 bug 修复。后续仍在持续开发中。

注意
如果您不想看到在命令行运行 mkdocs 时出现的警告，可以通过设置环境变量 DISABLE_MKDOCS_2_WARNING=true 或 NO_MKDOCS_2_WARNING=true 来关闭它。

1. 替换依赖

如果您的项目中依赖了 mkdocs，请将其替换为：

# 替换前
pip install mkdocs mkdocs-foo-plugin

# 替换后
pip install properdocs mkdocs-foo-plugin

插件即使名称中包含 “mkdocs” 也保持原名。它们将照常工作，插件作者无需更改项目名称。

2. 替换命令

# 替换前
mkdocs build

# 替换后
properdocs build

命令行功能完全等价，仅可执行文件的名称发生了变化。

3. 可选后续操作

程序会提醒您这些事项，这里一并列出：

• 您可以将配置文件从 mkdocs.yml 重命名为 properdocs.yml，但这不是必须的。
• 如果您使用主题 “mkdocs” 或 “readthedocs”，需要单独安装。这是唯一的破坏性更改；目前没有默认主题。

我们特别欢迎大家贡献新的主题。

技术背景

长期以来，人们认为分叉不可行，因为每个插件都直接依赖 mkdocs。我意识到可以克服这些问题，但这一认识直到最近才出现。

对插件作者

我们邀请所有插件作者加入我们的努力。

注意
我们并不要求您让仍在使用原项目的 MkDocs 用户受到影响，也不需要以只能在 ProperDocs 上工作为前提进行迁移。您的插件已经可以在 ProperDocs 下与 MkDocs 一起使用。

我们需要做的是宣传。插件可以通过以下方式帮助：

1. 编辑其依赖项：

   # Change from
   mkdocs >=1.2.3
   # to
   mkdocs >=1.2.3,