Skip to content

错误报告

¥Bug reports

Material for MkDocs 是一个积极维护的项目，我们不断努力改进。由于项目规模庞大且复杂，难免会出现一些 bug。如果您发现了 bug，可以按照本指南在我们的公共问题跟踪器中提交问题，以帮助我们。

¥Material for MkDocs is an actively maintained project that we constantly strive to improve. With a project of this size and complexity, bugs may occur. If you think you have discovered a bug, you can help us by submitting an issue in our public issue tracker, following this guide.

在创建问题之前

¥Before creating an issue

由于用户超过 2 万，几乎每隔一天就会出现新问题。本项目的维护人员正在努力通过尽快修复错误来控制未解决的问题数量。遵循本指南，您将准确了解我们需要哪些信息才能快速为您提供帮助。

¥With more than 20,000 users, issues are created every other day. The maintainers of this project are trying very hard to keep the number of open issues down by fixing bugs as fast as possible. By following this guide, you will know exactly what information we need to help you quickly.

但首先，请在创建问题之前做以下事情。

¥But first, please do the following things before creating an issue.

升级到最新版本

¥Upgrade to latest version

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

¥Chances are that the bug you discovered was already fixed in a subsequent version. Thus, before reporting an issue, ensure that you're running the latest version of Material for MkDocs. Please consult our upgrade guide to learn how to upgrade to the latest version.

错误修复未向后移植

¥Bug fixes are not backported

请理解，我们只会修复 Material for MkDocs 最新版本中出现的 bug。此外，为了减少重复工作，修复内容无法移植到早期版本。

¥Please understand that only bugs that occur in the latest version of Material for MkDocs will be addressed. Also, to reduce duplicate efforts, fixes cannot be backported to earlier versions.

删除自定义

¥Remove customizations

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

¥If you're using customizations like additional CSS, JavaScript, or theme extension, please remove them from mkdocs.yml before reporting a bug. We can't offer official support for bugs that might hide in your overrides, so make sure to omit the following settings from mkdocs.yml:

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

¥If, after removing those settings, the bug is gone, the bug is likely caused by your customizations. A good idea is to add them back gradually to narrow down the root cause of the problem. If you did a major version upgrade, make sure you adjusted all partials you have overridden.

我们的文档中提到的自定义

¥Customizations mentioned in our documentation

Material for MkDocs 提供的部分功能只能通过自定义来实现。如果您发现我们文档中明确提到的任何自定义功能存在 bug，我们当然鼓励您报告。

¥A handful of the features Material for MkDocs offers can only be implemented with customizations. If you find a bug in any of the customizations that our documentation explicitly mentions, you are, of course, encouraged to report it.

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

¥Don't be shy to ask on our discussion board for help if you run into problems.

搜索解决方案

¥Search for solutions

目前，我们知道该问题在最新版本中仍然存在，并且并非由您的任何自定义设置引起。但是，该问题可能是由配置文件（例如mkdocs.yml ）中的小拼写错误或语法错误引起的。

¥At this stage, we know that the problem persists in the latest version and is not caused by any of your customizations. However, the problem might result from a small typo or a syntactical error in a configuration file, e.g., mkdocs.yml.

现在，在您费力创建错误报告（该报告会立即得到答复并关闭，并带有指向相关文档部分或其他已报告或关闭的问题或讨论的链接）之前，您可以通过进行一些研究来为我们和您自己节省时间：

¥Now, before you go through the trouble of creating a bug report that is answered and closed right away with a link to the relevant documentation section or another already reported or closed issue or discussion, you can save time for us and yourself by doing some research:

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

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

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

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

¥Search our documentation and look for the relevant sections that could be related to your problem. If found, make sure that you configured everything correctly.1

此时，如果您仍未找到问题的解决方案，我们建议您创建问题，因为您很可能遇到了一些我们尚不清楚的问题。阅读以下部分，了解如何创建完整且实用的错误报告。

¥Search our issue tracker, as another user might already have reported the same problem, and there might even be a known workaround or fix for it. Thus, no need to create a new issue.

问题模板

¥Issue template

我们创建了一个全新的问题模板，旨在尽可能简化 Bug 报告流程，并提高我们和社区的效率。该模板是我们解答和修复超过 1,600 个问题（且仍在不断增加）的经验总结，包含以下部分：

¥Search our discussion board to learn if other users are struggling with similar problems and work together with our great community towards a solution. Many problems are solved here.

标题

¥Title

好的标题应该简短且具有描述性。它应该用一句话概括问题，以便从标题中推断出您要报告的错误的影响和严重程度。

¥Keep track of all search terms and relevant links, you'll need them in the bug report.2

例子

¥Example

清除

¥ Clear

内置typeset插件改变了导航标题相对于h1优先级

¥Built-in typeset plugin changes precedence of nav title over h1

罗嗦

¥ Wordy

内置typeset插件改变了导航标题在文档标题之上的优先级

¥The built-in typeset plugin changes the precedence of the nav title over the document headline

不清楚

¥ Unclear

标题不起作用

¥Title does not work

无用

¥ Useless

帮助

¥Help

上下文可选

¥Context optional

在描述错误之前，您可以提供一些额外的背景信息，以便我们了解您尝试实现的目标。请解释您在什么情况下使用 Material for MkDocs，以及您认为可能相关的内容。请勿在此处描述错误。

¥At this point, when you still haven't found a solution to your problem, we encourage you to create an issue because it's now very likely that you stumbled over something we don't know yet. Read the following section to learn how to create a complete and helpful bug report.

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

¥

Why this might be helpful: some errors only manifest in specific settings, environments or edge cases, for example, when your documentation contains thousands of documents.

错误描述

¥Bug description

现在，谈谈您要报告的 Bug。请提供清晰、重点突出、具体且简洁的 Bug 摘要。解释为什么您认为该 Bug 应该报告给 Material for MkDocs，而不是其依赖项。3 .遵循以下原则：

¥We have created a new issue template to make the bug reporting process as simple as possible and more efficient for our community and us. It is the result of our experience answering and fixing more than 1,600 issues (and counting) and consists of the following parts:

  • 解释问题所在，而不是如何解决——不要在这里解释如何重现错误，我们只是在解决问题。重点是尽可能清晰地阐明问题及其影响。

  • 保持简短明了——如果bug能用一两句话准确解释，那就完美了。不要夸大其词——维护者和未来的用户会感激你少读一些内容。

  • 一次解决一个错误– 如果您遇到多个不相关的错误，请为它们创建单独的问题。请勿将它们放在同一个问题中报告，因为这会增加归因难度。

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

¥A good title is short and descriptive. It should be a one-sentence executive summary of the issue, so the impact and severity of the bug you want to report can be inferred from the title.

为什么我们需要这样做：为了理解问题，我们需要清楚地描述它并量化其影响，这对于分类和优先排序至关重要。

¥

Why we need this: in order for us to understand the problem, we need a clear description of it and quantify its impact, which is essential for triage and prioritization.

¥Related links

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

¥Before describing the bug, you can provide additional context for us to understand what you were trying to achieve. Explain the circumstances in which you're using Material for MkDocs, and what you think might be relevant. Don't write about the bug here.

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

¥Why this might be helpful: some errors only manifest in specific settings, environments or edge cases, for example, when your documentation contains thousands of documents.

延伸目标——如果您还包括在搜索问题解决方案时使用的搜索词，那么我们维护人员就可以更轻松地改进文档。

¥Now, to the bug you want to report. Provide a clear, focused, specific, and concise summary of the bug you encountered. Explain why you think this is a bug that should be reported to Material for MkDocs, and not to one of its dependencies.3 Adhere to the following principles:

我们为什么需要这个：相关链接帮助我们更好地了解您想要实现的目标以及我们的文档部分是否需要调整、扩展或彻底修改。

¥

Why we need this: related links help us better understand what you were trying to achieve and whether sections of our documentation need to be adjusted, extended, or overhauled.

生殖

¥Reproduction

简洁的复现是每一份精心编写的 Bug 报告的核心，因为它能让维护人员立即重现必要的条件来检查 Bug，从而快速找到其根本原因。事实证明，简洁、简短的复现可以更快地修复问题。

¥Explain the what, not the how – don't explain how to reproduce the bug here, we're getting there. Focus on articulating the problem and its impact as clearly as possible.

创建复制品

¥Keep it short and concise – if the bug can be precisely explained in one or two sentences, perfect. Don't inflate it – maintainers and future users will be grateful for having to read less.

创建复本后，您应该会得到一个.zip文件，理想情况下大小不超过 1 MB。只需将.zip文件拖放到此字段中，即可自动将其上传到 GitHub。

¥One bug at a time – if you encounter several unrelated bugs, please create separate issues for them. Don't report them in the same issue, as this makes attribution difficult.

我们为什么需要这个：如果一个问题不包含最小复制或仅包含一个包含数千个文件的存储库的链接，那么维护人员将需要投入大量时间来尝试重新创建正确的条件以检查错误，更不用说修复它了。

¥

Why we need this: if an issue contains no minimal reproduction or just a link to a repository with thousands of files, the maintainers would need to invest a lot of time into trying to recreate the right conditions to even inspect the bug, let alone fix it.

不要分享存储库链接

¥ Stretch goal – if you found a workaround or a way to fix the bug, you can help other users temporarily mitigate the problem before we maintainers can fix the bug in our code base.

虽然我们知道开发人员在错误报告中包含指向仓库的链接是一种很好的做法，但我们目前不支持这样做。原因是内置信息插件自动生成的复现包含了所有必要的环境信息，而这些信息经常被人们遗忘。

¥Why we need this: in order for us to understand the problem, we need a clear description of it and quantify its impact, which is essential for triage and prioritization.

此外，许多 Material for MkDocs 的非技术用户在创建存储库时遇到了麻烦。

¥Of course, prior to reporting a bug, you have read our documentation and could not find a working solution. Please share links to all sections of our documentation that might be relevant to the bug, as it helps us gradually improve it.

复现步骤

¥Steps to reproduce

至此，您已向我们提供了足够的信息来理解该错误，并提供了可供我们运行和检查的复现版本。然而，当我们运行您的复现版本时，可能无法立即看出该错误的具体表现。

¥Additionally, since you have searched our issue tracker and discussion board before reporting an issue, and have possibly found several issues or discussions, include those as well. Every link to an issue or discussion creates a backlink, guiding us maintainers and other users in the future.

因此，请列出我们在运行您的复现程序以观察错误时应遵循的具体步骤。请保持步骤简短明了，并确保不遗漏任何内容。请使用像向五岁小孩解释一样简单的语言，并注重连贯性。

¥ Stretch goal – if you also include the search terms you used when searching for a solution to your problem, you make it easier for us maintainers to improve the documentation.

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

¥

Why we need this: we must know how to navigate your reproduction in order to observe the bug, as some bugs only occur at certain viewports or in specific conditions.

浏览器可选

¥Browser optional

如果您报告的错误仅发生在一个或多个特定浏览器中，我们需要知道哪些浏览器受到了影响。此字段是可选的，因为只有当您报告的错误不会导致网站在预览或构建时崩溃时，它才有意义。

¥Why we need this: related links help us better understand what you were trying to achieve and whether sections of our documentation need to be adjusted, extended, or overhauled.

隐身模式– 请确认该错误并非由浏览器扩展程序引起。请切换到隐身模式并尝试重现该错误。如果错误消失，则表明该错误是由扩展程序引起的。

¥A minimal reproduction is at the heart of every well-written bug report, as it allows us maintainers to instantly recreate the necessary conditions to inspect the bug to quickly find its root cause. It's a proven fact that issues with concise and small reproductions can be fixed much faster.

为什么我们需要这个：有些错误只会在特定的浏览器或版本中出现。由于现在几乎所有浏览器都是常青树，我们通常不需要知道错误出现在哪个版本，但以后可能会询问。如有疑问，请在上面的字段中添加浏览器版本作为第一步。

¥

Why we need this: some bugs only occur in specific browsers or versions. Since now, almost all browsers are evergreen, we usually don't need to know the version in which it occurs, but we might ask for it later. When in doubt, add the browser version as the first step in the field above.

清单

¥Checklist

感谢您遵循本指南并创建了高质量且完整的错误报告——您即将完成。这份清单确保您已阅读本指南，并已尽最大努力向我们提供所有需要的信息，以便我们更好地帮助您。

¥ Create reproduction

我们就从这里开始。

¥After you have created the reproduction, you should have a .zip file, ideally not larger than 1 MB. Just drag and drop the .zip file into this field, which will automatically upload it to GitHub.

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

  2. 我们文档中使用的术语可能与您的不同，但我们的意思是一样的。如果您在错误报告中包含搜索词和相关链接，将有助于我们调整和改进文档。↩

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