为 MkDocs 贡献代码

介绍如何为 MkDocs 项目做出贡献。

MkDocs 项目欢迎来自开源社区的开发者和用户的贡献。贡献可以通过多种方式进行，以下是一些例子：

• 通过拉取请求进行代码修补
• 改进文档
• 错误报告和补丁审查

有关可用通信渠道的信息，请参阅我们 GitHub 存储库中的 README 文件。

报告问题

请尽可能详细地描述问题。告诉我们您的平台和 MkDocs 版本。如果问题是视觉上的（例如，主题或设计问题），请添加截图。如果您收到错误，请包含完整的错误消息和回溯。

如果问题报告涵盖以下所有方面，将特别有用

1. 您想要实现什么目标？

2. 您的 mkdocs.yml 配置（+ 其他相关文件）是什么？最好缩减到最小的可重现示例。

3. 您期望在应用此设置时会发生什么？

4. 实际上发生了什么，以及它与您的预期有何不同？

尝试开发版本

如果您只想安装并尝试 MkDocs 的最新开发版本（以防它已经包含您问题的解决方案），您可以使用以下命令。如果您想为新功能提供反馈或想确认您遇到的错误是否在 git master 中已修复，这将非常有用。强烈建议您在 virtualenv 中执行此操作。

pip install git+https://github.com/mkdocs/mkdocs.git

安装用于开发

请注意，对于开发，您可以直接使用 Hatch，如下所述。如果您希望安装 MkDocs 的本地克隆，您可以运行 pip install --editable .。强烈建议您在 virtualenv 中执行此操作。

安装 Hatch

开发中使用的主要工具是 Hatch。它管理依赖项（在一个动态创建的 virtualenv 中），也是命令运行器。

因此，首先，安装它。理想情况下，使用 pipx install hatch（在 [安装 pipx] 之后）以隔离的方式安装它，或者以更通用的方式使用 pip install hatch。

运行所有检查

要在克隆的 MkDocs 存储库中运行 MkDocs 所需的 **所有** 检查，只需运行以下命令

hatch run all

这将涵盖下面提到的所有检查。

所有检查都必须通过。

运行测试

要运行 MkDocs 的测试套件，请运行以下命令

hatch run test:test
hatch run integration:test

它将尝试针对我们支持的所有 Python 版本运行测试。因此，如果您缺少一些版本，请不要担心。其余的将在您提交拉取请求时由 GitHub Actions 验证。

Python 代码风格

MkDocs 代码库中的 Python 代码使用 Black 和 Isort 进行格式化，并使用 Ruff 进行 lint 检查，所有这些都在 pyproject.toml 中配置。

您可以使用以下命令根据这些工具自动检查和格式化代码

hatch run style:fix

代码还使用 mypy 进行类型检查，它也在 pyproject.toml 中配置，可以像这样运行

hatch run types:check

其他风格检查

还有其他一些检查，例如拼写和 JS 风格。要运行所有检查，请使用以下命令

hatch run lint:check

MkDocs 本身的文档

在对 docs/ 目录下的文件进行编辑后，您可以使用以下命令在本地预览站点

hatch run docs:serve

请注意，任何“警告”都应在提交贡献之前解决。

文档文件也会由 markdownlint 检查，因此您也应该运行它

hatch run lint:check

如果您在 mkdocs.yml 中添加了一个新插件，则无需将其添加到任何“requirements”文件中，因为这是自动管理的。

.venv/bin/pip install -r requirements/requirements-docs.txt  # Exact versions of dependencies.
.venv/bin/pip install -r $(mkdocs get-deps)  # Latest versions of all dependencies.

翻译主题

要将主题本地化为您喜欢的语言，请遵循 翻译主题 中的指南。我们欢迎翻译拉取请求！

提交拉取请求

如果您正在考虑为 MkDocs 做出重大代码贡献，请最好先打开一个问题，以便在早期获得有关该想法的反馈。

当您认为代码已准备好进行审查时，将其推送到您的分支并发送拉取请求。对于要接受的更改，它很可能需要测试和文档，如果它是新功能的话。

在处理拉取请求分支时
除非另有约定，否则请优先使用 commit 而不是 amend，以及 merge 而不是 rebase。避免强制推送，否则审查历史将难以导航。对于最终结果，“不干净”的历史是可以的，因为大多数拉取请求在 GitHub 上都是压缩合并的。

不要添加到 release-notes.md 中，这将在稍后编写。

提交对内置主题的更改

当使用 i18n 支持安装时 (pip install 'mkdocs[i18n]')，MkDocs 允许主题支持被翻译成各种语言（称为语言环境），前提是它们遵循 Jinja 的 i18n 扩展，方法是用 {% trans %} 和 {% endtrans %} 标签包装文本占位符。

每次在主题模板中添加、删除或更改可翻译的文本占位符时，都需要通过运行 extract_messages 命令来更新主题的可移植对象模板 (pot) 文件。要更新两个内置主题的 pot 文件，请运行以下命令

pybabel extract --project=MkDocs --copyright-holder=MkDocs --msgid-bugs-address='https://github.com/mkdocs/mkdocs/issues' --no-wrap --version="$(hatch version)" --mapping-file mkdocs/themes/babel.cfg --output-file mkdocs/themes/mkdocs/messages.pot mkdocs/themes/mkdocs
pybabel extract --project=MkDocs --copyright-holder=MkDocs --msgid-bugs-address='https://github.com/mkdocs/mkdocs/issues' --no-wrap --version="$(hatch version)" --mapping-file mkdocs/themes/babel.cfg --output-file mkdocs/themes/readthedocs/messages.pot mkdocs/themes/readthedocs

更新后的 pot 文件应包含在 PR 中，其中包含更新后的模板。更新后的 pot 文件将允许翻译贡献者为他们喜欢的语言提出所需的翻译。有关详细信息，请参阅有关 翻译主题 的指南。

行为准则

在 MkDocs 项目的代码库、问题跟踪器、聊天室和邮件列表中进行交互的每个人都应遵守 PyPA 行为准则。