错误报告¶

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

创建问题之前¶

随着用户超过 20,000，问题几乎每天都会被创建。该项目的维护者正在努力通过尽快修复错误来减少未解决问题的数量。遵循本指南，您将确切了解我们需要哪些信息以快速帮助您。

但首先，请在创建问题之前执行以下操作。

升级到最新版本¶

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

移除自定义设置¶

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

• theme.custom_dir
• hooks
• extra_css
• extra_javascript

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

如果您遇到问题，请不要害羞，在我们的 讨论区 上寻求帮助。

搜索解决方案¶

在此阶段，我们知道问题在最新版本中仍然存在，并且不是由于您的自定义设置引起的。然而，问题可能是由于配置文件中的小错误或语法错误引起的，例如 mkdocs.yml。

现在，在您创建一个错误报告之前，可能会立即得到回答并关闭，并附上相关文档部分的链接或其他已报告或已关闭的问题或讨论，您可以通过进行一些研究为我们和您节省时间：

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

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

3. 搜索我们的讨论区，了解其他用户是否遇到类似问题，并与我们优秀的社区一起努力寻找解决方案。许多问题在这里得到解决。

记录所有 搜索词 和 相关链接，您将在错误报告中需要它们。²

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

问题模板¶

我们创建了一个新的问题模板，以使错误报告过程尽可能简单和高效，方便我们的社区和我们。这是我们回答和修复超过 1,600 个问题（并且还在增加）的经验的结果，包含以下部分：

• 标题
• 上下文 可选
• 错误描述
• 相关链接
• 重现
• 重现步骤
• 浏览器 可选
• 检查清单

标题¶

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

上下文 可选¶

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

为什么这可能有帮助: 一些错误仅在特定设置、环境或边缘情况下表现出来，例如，当您的文档包含成千上万的文档时。

错误描述¶

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

• 解释 什么，而不是 如何 – 不要在这里解释 如何重现错误，我们会到达那里。专注于尽可能清晰地表达问题及其影响。

• 保持简短和简洁 – 如果错误可以用一两句话准确地解释，完美。如果可以，不要夸大 – 维护者和未来的用户会感谢您减少阅读量。

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

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

我们需要这个的原因: 为了让我们理解问题，我们需要对其进行清晰的描述并量化其影响，这对于分类和优先级非常重要。

相关链接¶

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

此外，由于您在报告问题之前已经搜索了我们的 问题跟踪器 和 讨论区，并可能发现了几个问题或讨论，也请将它们包括在内。每个指向问题或讨论的链接都会创建一个反向链接，引导我们维护者和其他用户未来的工作。

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

我们需要这个的原因: 相关链接帮助我们更好地理解您试图实现的目标，以及我们的文档部分是否需要调整、扩展或彻底修改。

重现¶

最小重现是每个编写良好的错误报告的核心，因为它允许我们维护者立即重现检查错误所需的条件，以快速找到其根本原因。事实证明，具有简洁和小型重现的问题可以更快地修复。

创建重现

在您创建重现后，您应该有一个 .zip 文件，理想情况下不超过 1 MB。只需将 .zip 文件拖放到此字段中，它将自动上传到 GitHub。

我们需要这个的原因: 如果一个问题没有最小重现或只是指向一个包含成千上万文件的存储库的链接，维护者将需要投入大量时间来尝试重现正确的条件以检查错误，更不用说修复它。

重现步骤¶

在这一点上，您已经向我们提供了足够的信息以理解错误，并提供了我们可以运行和检查的重现。然而，当我们运行您的重现时，可能并不立即明显我们如何看到错误的实际情况。

因此，请列出我们在运行您的重现时应遵循的具体步骤，以观察错误。保持步骤简短而简洁，并确保没有遗漏。使用简单的语言，就像您在向五岁小孩解释一样，专注于连贯性。

我们需要这个的原因: 我们必须知道如何导航您的重现，以便观察错误，因为某些错误仅在特定视口或特定条件下发生。

浏览器 可选¶

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

隐私模式 – 请验证该错误不是由浏览器扩展引起的。切换到隐私模式并尝试重现错误。如果消失了，则是由扩展引起的。

我们需要这个的原因: 某些错误仅在特定浏览器或版本中发生。由于现在几乎所有浏览器都是常青的，我们通常不需要知道发生错误的版本，但我们可能会在后面询问。如果有疑问，请在上面的字段中添加浏览器版本作为第一步。

检查清单¶

感谢您遵循指南并创建高质量和完整的错误报告 – 您快完成了。检查清单确保您已阅读本指南，并尽您所能提供我们需要知道的所有信息，以帮助您。

我们会接手处理。