Skip to content

请求变更

Material for MkDocs 是一个用于创建漂亮且功能齐全的项目文档的强大工具。作为一个拥有超过 20,000 名用户的项目，我们理解我们的项目服务于各种用例，因此我们创建了以下指南。

请设身处地地考虑一下 - 对于这样一个规模的项目来说，在不断添加新功能的同时维护现有功能可能是一项挑战。我们非常重视社区中的每一个想法或贡献，并恳请您在提交变更请求之前花时间阅读以下准则。这将帮助我们更好地理解您提出的变更请求以及它对社区的益处。

本指南是我们尽力解释在评估变更请求并考虑将其实施时的标准和理由的最佳努力。

创建问题之前

在您投入时间填写和提交变更请求之前，请您花些时间回答一些问题，以确定您的想法是否适用于 Material for MkDocs，并与项目的理念和风格相匹配。

请在创建问题之前找到以下问题的答案。

这不是一个错误，而是一个功能

变更请求旨在提出小的调整、新功能的想法，或者影响项目的方向和愿景。需要注意的是，变更请求不适用于报告错误，因为它们缺少调试所需的关键信息。

如果您想报告错误，请参考我们的错误报告指南。

灵感来源

如果您在其他静态网站生成器或主题中看到了您的想法的实现，请确保在提交之前收集足够的关于其实现的信息，这样我们可以更快地评估其潜在适应性。解释您对实现的喜欢和不喜欢之处。

对社区的益处

我们的讨论板块是与我们社区联系的最佳地方。在评估新想法时，从其他用户那里寻求意见并考虑其他观点是至关重要的。这种方法有助于以使大量用户受益的方式实现新功能。

  开始讨论

问题模板

现在，您已经花时间进行了必要的初步工作，并确保您的想法符合我们的要求，邀请您创建一个变更请求。以下指南将引导您完成所有必要的步骤，以帮助您提交一个全面而有用的问题：

标题

一个好的标题应该是简短和描述性的。它应该是对这个想法的一句话执行摘要，以便从标题中可以推断出潜在的影响和对社区的益处。

示例
清晰 在搜索中索引自定义前置元数据
啰嗦 添加一个功能，允许作者定义要在搜索中索引的自定义前置元数据
不清楚 改进搜索
泛泛 请帮助

上下文 可选

在描述您的想法之前，您可以提供额外的上下文，以便我们了解您试图实现的目标。解释您使用 Material for MkDocs 的情况以及您认为可能相关的内容。请不要在此处写有关变更请求的内容。

为什么这可能有帮助：某些想法可能只对特定的设置、环境或边缘情况有益，例如，当您的文档包含数千个文档时。通过一些上下文，可以更准确地确定变更请求的优先级。

描述

接下来，详细而清晰地描述您的想法。解释为什么您的想法与 Material for MkDocs 相关，并且必须在这里实现，而不是在其依赖项之一中实现：1

  • 解释是什么，而不是为什么 – 不要在这里解释您的想法的益处，我们马上就要谈到这个了。专注于尽可能准确地描述所提议的变更请求。

  • 保持简短和简洁 – 在描述您的想法时要简洁明了，没有必要过多描述。维护者和未来的用户会感谢您少读一些。

  • 一次一个想法 – 如果您有多个不相关的想法，请为每个想法单独创建变更请求。

伸展目标 – 如果您有一种自定义或其他方式来添加所提议的变更，您可以在我们维护者将其添加到我们的代码库之前，在此处与其他用户分享。

为什么我们需要这个：为了理解和评估您提议的变更，我们需要对您的想法有清晰的理解。通过提供详细而准确的描述，您可以帮助您和我们节省时间，避免在评论中进一步讨论您的想法的澄清。

相关链接

请提供与您的变更请求相关的任何问题、讨论或文档部分的链接。如果您（或其他人）已经在我们的讨论板块与社区讨论过这个想法，请同时包含该讨论的链接。

为什么我们需要这个：相关链接帮助我们通过提供额外的上下文来全面了解您的变更请求。此外，链接到先前的问题和讨论使我们能够快速评估社区已经提供的反馈和意见。

用例

解释您的变更请求从作者和用户的角度来看将如何工作 - 预期的影响是什么，为什么它不仅对您有益，而且对其他用户也有益？有多少用户会受益？此外，它是否可能破坏现有功能？

为什么我们需要这个：了解想法的用例和益处对于评估其对项目和用户的潜在影响和有用性至关重要。这些信息帮助我们了解想法的预期价值以及它如何与项目的目标相一致。

可视化效果 可选

现在，我们已经有了对您的想法的清晰而详细的描述，包括其潜在的用例和相关上下文的信息。如果您有任何可视化效果，比如草图、截图、模型或外部资产，您可以在此部分展示它们。

您可以将文件拖放到此处，或包含指向外部资产的链接。

此外，如果您在其他静态网站生成器或主题中看到了这种变更、功能或改进的使用方式，请提供一个示例，展示它是如何实现和结合的。

为什么我们需要这个：图示和可视化效果可以帮助我们维护者更好地理解和设想您的想法。截图、草图或模型可以提供额外的细节和清晰度，仅凭文本可能无法传达。此外，了解您的想法在其他项目中的实现方式可以帮助我们了解它在 Material for MkDocs 中的潜在影响和可行性，这有助于我们维护者评估和审查变更请求。

清单

感谢您遵循变更请求指南并创建了一个高质量的变更请求。这一部分确保您已经阅读了本指南，并尽力提供了我们需要的每一个信息来审查您对 Material for MkDocs 的想法。

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

  1. 有时，用户在我们的问题跟踪器上提出的想法涉及到我们的上游依赖项，包括MkDocs、Python Markdown、Python Markdown Extensions或第三方插件。思考一下您的想法是否对其他主题有益，将变更请求上游化以获得更大的影响是个好主意。 ↩