报告错误

Material for MkDocs 是一个积极维护的项目，我们不断努力改进它。在这样一个规模和复杂度的项目中，可能会出现错误。如果您认为发现了错误，您可以通过按照本指南在我们的公共问题跟踪器中提交一个问题来帮助我们。

创建问题之前

由于有超过 20,000 个用户，每天都会创建问题。我们维护者正在努力尽快修复错误，以保持未解决问题的数量较少。通过按照本指南操作，您将了解到我们需要哪些信息来帮助您快速解决问题。

但是在创建问题之前，请尝试以下操作。

升级到最新版本

您发现的错误可能已经在后续版本中修复。因此，在报告问题之前，请确保您正在运行 Material for MkDocs 的最新版本。请参考我们的升级指南了解如何升级到最新版本。

不会回溯修复错误

请理解，只有在Material for MkDocs的最新版本中出现的错误才会得到解决。此外，为了减少重复工作，修复程序无法回溯到早期版本。

删除自定义内容

如果您正在使用自定义内容，例如[额外的 CSS]、JavaScript或主题扩展，请在报告错误之前从mkdocs.yml中删除它们。我们无法为可能隐藏在您的覆盖中的错误提供官方支持，因此请确保从mkdocs.yml中省略以下设置：

• theme.custom_dir
• theme.hooks
• extra_css
• extra_javascript

如果在删除这些设置后，错误消失了，那么错误很可能是由于您的自定义内容引起的。一个好的方法是逐渐将它们添加回来，以缩小问题的根本原因。如果您进行了主要版本升级，请确保调整了所有您已覆盖的部分。

在我们的文档中提到的自定义内容

Material for MkDocs 提供的一些功能只能通过自定义内容来实现。如果您在任何我们明确提到的自定义内容中发现错误，当然鼓励您报告。

如果遇到问题，请不要犹豫在我们的讨论板上寻求帮助。

搜索解决方案

在这个阶段，我们知道问题在最新版本中仍然存在，并且不是由您的自定义内容引起的。但是，问题可能是由配置文件（例如mkdocs.yml）中的小错误或语法错误导致的。

在您费力地创建一个可能会立即被关闭并附上相关文档部分链接、已经报告或关闭的问题或讨论的 bug 报告之前，请花些时间进行一些研究：

1. 搜索我们的文档，查找可能与您的问题相关的部分。如果找到了，请确保您正确配置了所有内容。¹

2. 搜索我们的问题跟踪器，因为其他用户可能已经报告了相同的问题，甚至可能已经有了已知的解决方法或修复方法。因此，无需创建新的问题。

3. 搜索我们的讨论板，了解其他用户是否遇到类似的问题，并与我们伟大的社区共同努力找到解决方案。许多问题都在这里得到解决。

跟踪所有搜索词和相关链接，您在 bug 报告中会需要它们。²

---

在这一点上，如果您仍然没有找到解决方案，我们鼓励您创建一个问题，因为现在很可能您遇到了我们尚不知道的问题。阅读下一节，了解如何创建一个完整和有帮助的 bug 报告。

问题模板

我们创建了一个新的问题模板，以尽可能简化和提高社区和我们的效率。它是我们回答和修复了 1600 多个问题（并且还在继续）的经验总结，包括以下部分：

• 标题
• 上下文 可选
• 描述
• 相关链接
• 复现
• 复现步骤
• 浏览器 可选
• 清单

标题

一个好的标题应该简短且描述性。它应该是对问题的一个句子的执行摘要，以便从标题中可以推断出您要报告的错误的影响和严重性。

	示例
清晰	内置的typeset插件将导航标题的优先级高于h1
啰嗦	内置的typeset插件改变了导航标题在文档标题之上的优先级
不清楚	标题不起作用
泛泛	请帮助

上下文 可选

在描述错误之前，您可以提供额外的上下文，以便我们了解您试图实现的目标。解释您使用 Material for MkDocs 的情况以及您认为可能相关的内容。请不要在这里描述错误。

为什么这可能有帮助：某些错误仅在特定设置、环境或边缘情况下出现，例如当您的文档包含数千个文档时。

描述

现在，请描述您要报告的错误。提供一个清晰、专注、具体和简洁的摘要，说明您遇到的错误，并解释为什么您认为这是一个应该报告给 Material for MkDocs 而不是其依赖项之一的错误。³ 遵循以下原则：

• 解释是什么，而不是如何 – 不要在这里解释如何重现错误[^复现步骤]，我们接下来会讲到。重点是尽可能清楚地表达问题及其影响。

• 保持简短和简洁 – 如果错误可以在一两句话中准确解释，那就太好了。不要夸大它 - 维护者和未来的用户会感谢您少读一些。

• 一次一个错误 – 如果您遇到几个不相关的错误，请为它们创建单独的问题。不要在同一个问题中报告它们，这样会导致归因困难。

---

额外目标 – 如果您找到了解决方法或修复错误的方法，您可以在我们维护者修复错误之前，帮助其他用户暂时缓解问题。

为什么我们需要这个：为了我们能够理解问题，我们需要对问题进行清晰的描述，并量化其影响，这对于问题的分类和优先级很重要。

相关链接

当然，在报告错误之前，您已经阅读了我们的文档并且没有找到有效的解决方案。请分享我们文档中可能与错误相关的所有部分的链接，因为这有助于我们逐步改进文档。

此外，由于在报告问题之前您已经搜索了我们的问题跟踪器和讨论板，并且可能找到了几个问题或讨论，请也包含它们。每个问题或讨论的链接都会创建一个反向链接，指导我们维护者和其他用户。

---

额外目标 – 如果您还包括您在搜索解决方案时使用的搜索词，您将更容易帮助我们维护者改进文档。

为什么我们需要这个：相关链接帮助我们更好地理解您试图实现的目标，以及我们的文档是否需要进行调整、扩展或彻底改进。

复现

一个最小的复现是每个良好编写的错误报告的核心，因为它使我们维护者能够快速重现必要的条件来检查错误并快速找到其根本原因。事实证明，具有简明和小型复现的问题可以更快地修复。

  创建复现

---

创建复现之后，您应该有一个.zip 文件，最好不超过 1MB。只需将.zip 文件拖放到此字段中，它将自动上传到 GitHub。

为什么我们需要这个：如果一个问题没有最小复现，或者只包含一个指向包含数千个文件的存储库的链接，维护者需要花费很多时间来尝试重现正确的条件，甚至无法检查错误，更不用说修复它了。

不要共享存储库链接

虽然我们知道在开发者中，将存储库链接包含在错误报告中是一个好的做法，但我们目前在我们的流程中不支持这些链接。原因是由 内置信息插件 自动生成的复现包含了通常被遗漏的所有必要环境信息。

此外，Material for MkDocs 有许多非技术用户，他们在创建存储库时可能遇到困难。

复现步骤

此时，您已经为我们提供了足够的信息来理解错误，并且您已经给出了我们可以运行和检查的复现。然而，当我们运行您的复现时，我们可能无法立即看到如何看到错误。

接下来，请列出在运行您的复现时应该遵循的具体步骤，以观察错误。保持步骤简洁明了，确保不遗漏任何内容。使用简单的语言，就像向一个五岁的孩子解释一样，并关注连续性。

为什么我们需要这个：我们必须知道如何导航到您的复现以观察错误，因为某些错误只在特定的视口或特定条件下发生。

浏览器 可选

如果您报告的错误只在一个或多个特定浏览器中发生，我们需要知道受影响的浏览器是哪些。此字段是可选的，只有在您报告的错误不涉及预览或构建站点时才相关。

为什么我们需要这个：某些错误只在特定浏览器或版本中发生。由于现在几乎所有浏览器都是升级的，我们通常不需要知道发生错误的版本，但我们可能会在以后要求。如果有疑问，请在上面的字段中添加浏览器版本。

清单

感谢您遵循指南并创建了高质量和完整的错误报告 - 您几乎完成了。此部分确保您已经阅读了本指南，并尽力提供了我们所需的一切来帮助您。

接下来，我们将接手处理。

不完整的问题

请理解，我们保留关闭不完整的问题的权利，这些问题不包含最小复现，或者不符合本文档中提到的质量标准和要求。当提供缺失信息后，问题可以重新打开。

---

1. 在添加行到 mkdocs.yml 时，请确保保留文档中提到的缩进，因为 YAML 是一种对空白敏感的语言。许多报告的问题最终都被证明是配置错误。 ↩

2. 我们的文档可能使用与您不同的术语，但表示的意思是相同的。当您在 bug 报告中包含搜索词和相关链接时，您帮助我们调整和改进文档。 ↩

3. 有时，用户在我们的问题跟踪器上报告由我们的上游依赖项（包括MkDocs、Python Markdown、Python Markdown Extensions或第三方插件）引起的错误。一个好的经验法则是将 theme.name 更改为 mkdocs 或 readthedocs，并检查问题是否仍然存在。如果问题仍然存在，则该问题可能与 Material for MkDocs 无关，应该向上游报告。如果有疑问，请使用我们的讨论板寻求帮助。 ↩