Material for MkDocs 贡献指南Issue 模板、最小复现与 Pull Request 全流程实战【免费下载链接】mkdocs-materialDocumentation that simply works项目地址: https://gitcode.com/GitHub_Trending/mk/mkdocs-material本文以 Material for MkDocs 官方贡献文档为骨架系统讲解如何通过 Issue、最小复现、翻译和 Pull Request 参与这个开源文档主题的维护与演进。读完本文你将掌握四类 Issue 模板的正确用法、用内置 info 插件一键生成可复现的.zip压缩包以及从 Fork 到合并的完整 PR 协作流程并能理解维护者评审与治理背后的规则逻辑。贡献渠道全景六大路径快速导航Material for MkDocs 是一个持续活跃演进的开源项目社区每天都会产生大量 Issue 与讨论Issue 追踪器与讨论板事实上沉淀成了一座知识库是官方文档之外的重要补充。为了让维护者能更快定位问题、评估变更请求并修复缺陷项目围绕创建 Issue和参与贡献两条主线设计了六条标准路径分别对应docs/contributing/目录下的六份专项指南路径适用场景对应文档报告 Bug某个功能不工作了需要附上可复现样例reporting-a-bug.md报告文档问题文档缺信息、有错误或前后不一致reporting-a-docs-issue.md提出变更请求提议新功能、改进建议或方向性想法requesting-a-change.md社区提问有疑问或需要帮助去讨论板交流讨论板添加翻译为已支持语言补翻译或新增一种语言adding-translations.md创建 Pull Request提交代码、文档或新功能等待维护者评审合并making-a-pull-request.md仓库根目录的 CONTRIBUTING.md 与docs/contributing/index.md内容互为镜像前者面向 GitHub 仓库访客后者作为站点文档的贡献章节渲染。无论从哪个入口进入流程完全一致。互动前的自我检查清单在创建 Issue、提问或评论之前请先对照下列问题逐条自查。这套清单的目的是确保你选用了正确的模板、提供了维护者需要的全部信息从而让沟通一次到位。创建 Issue 前是否选用了最合适的 Issue 模板是否存在另一个更贴合你诉求的模板是否已搜索确认没有相似的 Bug 报告或变更请求是否找到了可能相关的旧 Issue是否按要求填满了每个字段并提供了维护者理解问题所需的全部附加信息提问之前这个话题是适合讨论板的问题还是应该作为 Bug 报告 / 变更请求提交到 Issue 追踪器是否已存在相关的开放讨论如果有你的问题和该讨论的方向是否一致还是应该另开新讨论是否向社区提供了足够的信息让对方能快速理解并帮助你评论之前你的评论是否与当前页面、帖子、Issue 或讨论主题相关还是更适合新建一个 Issue 或讨论你的评论是否给对话增加了价值是否建设性、尊重社区与维护者是否其实可以用一个表情符号回复reaction代替!!! warning Issue、讨论与评论是永久性的 你在社区里写下的每一条内容都是永久可见的。请始终保持友善与建设性遵守贡献指南和行为准则。创建 Issue四类模板与使用场景报告 Bug八要素模板docs/contributing/reporting-a-bug.md详细规定了 Bug 报告的八个组成部分[标题]、[上下文可选]、[Bug 描述]、[相关链接]、[复现]、[复现步骤]、[浏览器可选]与[检查清单]。这套模板是维护者处理超过 1600 个 Issue 的经验结晶。报告前的三步准备工作决定你的报告是否会被认真对待升级到最新版本Bug 可能已在后续版本修复因此报告前务必先升级。注意维护者不提供向后移植backport只有最新版本中出现的 Bug 才会被处理。升级方式参考 upgrade.md。移除自定义将mkdocs.yml中的theme.custom_dir、hooks、extra_css、extra_javascript四个设置全部移除后复现。如果 Bug 随之消失说明问题出在你的自定义代码上可以逐项加回设置来缩小根因范围。大版本升级后还要确认所有被覆盖的 partials 已适配新版本。搜索解决方案依次搜索项目文档、Issue 追踪器和讨论板很可能已经有人遇到并解决了相同问题。务必记录你使用的搜索词和相关链接这些信息要写进 Bug 报告——它能帮助维护者发现文档术语与用户用语之间的差异从而改进文档。模板各字段要点标题一句话说清问题本质让人能从标题推断影响与严重程度。好标题示例Built-intypesetplugin changes precedence of nav title overh1避免Title does not workHelp这类含糊标题。上下文可选说明你在什么场景下使用 Material for MkDocs不描述 Bug 本身。某些错误只在特定设置或边缘场景出现例如文档包含数千个页面时。Bug 描述讲清楚是什么而非怎么做尽量简短一两句能说清最好一个 Issue 只报一个 Bug无关问题请分开提交。额外加分项如果你找到了临时 workaround请一并分享。同时要判断这个 Bug 是否属于 Material for MkDocs 本身——它也可能来自上游依赖MkDocs、Python Markdown、Python Markdown Extensions 或第三方插件。一个实用的判别技巧是把theme.name从material改成mkdocs或readthedocs如果问题依然存在那大概率是上游问题应提交给上游项目。相关链接给出你查阅过的、可能与 Bug 相关的文档章节链接以及你在 Issue 追踪器和讨论板中找到的相关讨论。每个链接都是一个 backlink能引导未来的维护者和其他用户。复现一份最小复现是高质量 Bug 报告的心脏具体制作流程见下文第四节。制作完成后会得到一个.zip文件理想情况下不超过 1 MB直接拖拽进该字段即可自动上传。注意项目不接受链接到某仓库的方式因为内置 info 插件生成的压缩包已包含所有必要的环境信息。该字段对 Bug 报告是强制项。复现步骤用最简单的语言列出观察 Bug 的具体步骤不要遗漏任何环节——某些 Bug 只在特定视口或条件下出现。浏览器可选仅当 Bug 只在特定浏览器出现时才需要填写。请先在无痕模式下复现一次排除浏览器插件干扰。检查清单确认你已读完本指南并尽力提供了全部信息。报告文档问题五要素模板项目文档由 80 多个页面组成涵盖功能、配置与自定义的大量信息。发现文档不一致或需要改进时按 reporting-a-docs-issue.md 提交它比 Bug 报告简单——不需要复现只需五个部分标题一句话描述包含关键词以便检索。好示例Clarify social cards setup on Windows。描述简明陈述不一致之处或需要改进的章节说明严重程度同样遵循简短一次一个问题原则。相关链接指向具体文档章节尽量使用锚点链接永久链接方便定位。拟议修改可选可以勾勒粗略想法也可以写出具体修改方案对其他遇到同样问题的用户很有价值。检查清单确认已提供全部信息。变更请求七要素模板与路线图管理变更请求用于建议小的调整、新功能想法或影响项目方向与愿景的建议不用于报告 BugBug 信息不足以支撑调试。提交前请先读一遍项目哲学确认想法与项目基调契合。提交前的准备如果你在别的静态站点生成器或主题中见过类似实现请收集其实现细节说明你喜欢和不喜欢的地方这能加速评估到讨论板与社区交流听取不同视角这有助于新功能惠及更多用户同样记录搜索词与相关链接它们会用在变更请求中。模板七要素标题、上下文可选、描述、相关链接、用例、视觉素材可选、检查清单。要点包括描述讲是什么而非为什么一条请求只提一个想法用例部分要从作者与读者两个视角说明预期影响、受益人群以及是否会破坏现有功能视觉素材可拖拽草图、截图、原型或外部素材也可展示其他项目中的同类实现。维护者如何管理变更请求requesting-a-change.md 的官方流程阅读并评审请求理解想法可能留下评论澄清意图或建议替代方案若想法超出项目范围关闭请求并说明原因若想法与项目愿景一致归类为变更请求并加入专门的 backlog 看板无论结果如何都会关闭请求保持 Issue 追踪器干净、聚焦于开放 Bug。注意Issue 被关闭不代表被遗忘——进入 backlog 的变更请求仍属于长期规划的一部分。该做法的收益是Bug 与功能请求分离用户能更清晰直观地看到项目的维护活跃度相关想法在 backlog 中聚合便于追踪进度与关联关系。如果你的变更请求被拒绝了文档给出的七条评估原则不分先后值得任何贡献者提前了解与项目愿景和基调的契合度与现有功能和插件的兼容性与所有屏幕尺寸和浏览器的兼容性实现与维护的成本对大多数用户的实用性简单易用性可访问性Accessibility被拒绝并非终点——你完全可以借助自定义机制自行实现或在讨论板上询问是否已有人做过。最小复现高质量 Bug 报告的灵魂一份**最小复现reproduction**是 Bug 的简化版本只包含复现该 Bug 所必需的极简设置与文档越简单越好。creating-a-reproduction.md 给出了从零搭建的完整流程其产物是上报 Bug 时必须在Reproduction字段上传的.zip文件——Bug 报告强制要求而提问和变更请求也建议附上可运行的样例以加速沟通。搭建隔离的虚拟环境推荐使用 Python 虚拟环境任何安装或升级的包都只作用于该环境出问题可随时删除重建# 创建虚拟环境 python3 -m venv venv激活环境macOS / Linux. venv/bin/activateWindows. venv/Scripts/activate激活后终端提示符前会出现(venv)表示已进入虚拟环境退出用deactivate。四步搭建最小复现项目升级到最新版本Bug 可能已修复pip install --upgrade --force-reinstall mkdocs-material初始化全新空项目注意必须是新建的空目录mkdocs new .然后写入最小配置 mkdocs.ymltheme: name: material只添加复现 Bug 所必需的设置。如果是渲染类 Bug只创建必要数量的 Markdown 文档。反复精简直到能稳定观察到 Bug。打包前再次检查删除所有删掉后 Bug 就不出现的非必要配置行与文件。用内置 info 插件一键打包Material for MkDocs 9.0.0 起内置了专为生成复现包而设计的 info 插件。在mkdocs.yml中加入plugins: - info运行mkdocs build插件会自动收集所有相关文件并生成压缩包同时打印摘要并退出。官方文档给出的输出示例如下INFO - Started archive creation for bug report INFO - Archive successfully created: example/.dependencies.json 859.0 B example/.versions.log 83.0 B example/docs/index.md 282.0 B example/mkdocs.yml 56.0 B example.zip 1.8 kB把生成的.zip直接拖入 Bug 报告模板的 Reproduction 字段即可。源码视角info 插件到底做了什么从实现看info 插件的全部逻辑集中在 src/plugins/info/plugin.py其配置项定义在 src/plugins/info/config.py。on_config钩子以event_priority(100)的优先级最早执行plugin.py整个流程体现了先守规矩、再打包的设计版本校验插件会请求最新 Release 信息将当前安装版本与最新版本比对不一致时打印升级提示并退出plugin.py自定义拦截检测到theme.custom_dir或hooks设置时打印请移除提示并中止因为这属于无法官方支持的自定义行为plugin.py路径校验确保mkdocs.yml、docs_dir、自定义目录、INHERIT继承配置等路径都位于当前工作目录root之下否则拒绝打包防止生成无法独立运行的复现包plugin.py智能排除自动排除site_dir、已激活与未激活的虚拟环境目录通过扫描pyvenv.cfg识别、projects 插件的构建目录以及包含sitemap.xml.gz的目录plugin.py、plugin.py交互式命名打包前会提示Please name your bug report (2-4 words)压缩包以版本号 关键词形式命名plugin.py环境信息兜底自动写入requirements.lock.txt当前环境全部已安装包及其版本与platform.json系统、架构、Python 版本、工作目录、启动命令、PYTHONPATH/VIRTUAL_ENV环境变量、sys.path、被排除条目并将用户名替换为USERNAME占位符以保护隐私plugin.py安全提示压缩包超过 1 MB 时警告超过推荐上限包含.dotpath隐藏文件/目录时提醒可能含敏感信息请人工核验后再上传plugin.py。info 插件共有四个配置项config.pyenabled默认true整体开关、enabled_on_serve默认false控制mkdocs serve预览时是否启用便于快速迭代复现包、archive默认true是否生成压缩包仅用于调试插件本身、archive_stop_on_violation默认true违反上述规则时是否中止打包。最后一个选项仅供报告文档明确提到过的自定义功能相关 Bug 时使用此时应设为false并在报告中说明理由。完整配置说明见 docs/plugins/info.md。翻译贡献让更多语言被支持Material for MkDocs 在社区帮助下已被翻译成60 多种语言维护者无力逐语言跟进新功能也时常需要新翻译。如果你发现自己的语言缺少翻译或想新增一种语言按 adding-translations.md 操作即可。动手前先检查确认语言可用性在站点语言列表中检查你的语言是否已支持——已支持则补缺失翻译通常只需 5 分钟未支持则帮助新增搜索 Issue 追踪器可能已有其他贡献者提交了同语言的翻译待整合避免重复劳动。翻译 Issue 模板四要素标题更新既有语言可保留原标题新增语言时把预填标题中的...替换为语言名例如 Add translations for German翻译内容标有图标的行表示缺失翻译翻译后移除该图标不确定的行可留给其他贡献者完成。为保证准确性可对照英文基准翻译仓库中所有语言的模板都位于src/templates/partials/languages/目录国家旗帜可选在图标与表情符号搜索页中搜索flag找到旗帜 shortcode 填入。注意 Twemoji 仅提供 260 个国家的旗帜国家的下级行政区省、州、地区不支持此时请选最合适的替代旗帜检查清单确认信息齐全。署名机制通过模板提交翻译后你会在提交中被记录为共同作者co-author无需再走 Pull Request 流程。Pull Request 工作流从 Fork 到合并making-a-pull-request.md 给出了完整的 PR 流程。核心原则是动手写代码之前先与社区讨论清楚你想做什么——疑似 Bug 先报 Bug 报告文档改动先建文档问题新功能先提变更请求。你的目标可能已能通过配置或自定义实现提前沟通能避免无效劳动。准备变更与草稿 PR整体流程可用下面的时序图概括fork → clone → topic branch → 迭代提交 → 同步上游 → 草稿 PR → 评审具体步骤Fork 仓库在 GitHub 上 Fork Material for MkDocs 仓库获得可推送的副本注意同一仓库同时只能有一个 fork。建议在仓库名后追加-fork后缀并补充描述让路过的人明白这是一个临时分支副本克隆到本地开始修改创建 topic 分支所有贡献都应在一个描述工作内容的主题分支上进行便于同时进行多项工作也向他人明确这是进行中的代码如需改动代码按开发环境搭建指引准备环境迭代编辑与提交按有意义的提交块分批提交不要一次全提交。细粒度的增量提交远比跨多文件的大改动容易评审务必写有意义的提交信息定期推送到你的 fork持续同步上游长时间工作时尤其重要创建 PR 前至少必须合并一次上游并发变更以降低冲突风险创建草稿 PRdraft引用引发工作的讨论或 Issue尽早获得维护者和其他人的反馈可在关键节点显式请求评审以评审者视角自查审视 diff 是否足够小、是否符合项目编码风格、是否破坏了docs目录下项目自身文档的构建有反馈则按需迭代。定稿、评审与合并当你认为改动已可作为正式贡献时将 PR 转为**定稿finalize**状态请求维护者评审squidfunk维护者可能提出评论请保持尊重地讨论。要理解维护者往往从多年维护的长期视角看问题而你更聚焦于眼前的 Issue 或功能并非所有 PR 都会被合并——它可能暴露阻塞集成的新问题或揭示更好的通用方案这些都有助于项目进步按反馈修改并推送到 forkPR 会自动更新可能需要多轮迭代评审满意后维护者将其合并进主分支master过程中可能squash压缩你的提交并编辑提交信息。此时你已成功贡献改动将以你的名义出现在主分支合并后清理先在 fork 上删除分支从主仓库把改动 pull 回 fork 的 master 分支删除本地 clone 的 topic 分支把改动 pull 到本地 master 分支。关键命令速查开发最好在独立的 topic 分支上进行# 创建并切换到新分支 git switch -c name # 推送到 fork 并建立跟踪关系-u --set-upstream git push -u origin name工作周期较长时把上游仓库注册为upstream远程git remote add upstream https://github.com/squidfunk/mkdocs-material.git之后显式从上游拉取并发变更git pull upstream master该命令会把master分支的变更取回并合并进当前 topic 分支。PR 合并后清理分支git switch master git branch -d name后续再做新 PR 时务必从最新历史起步——最稳妥的做法是删除 fork 重新 Fork或通过 GitHub UI 同步 fork 后 pull 到本地 master。测试与评审三个冒烟测试提交前至少在三类项目上验证改动Material for MkDocs 自身的文档按开发环境指引搭建后mkdocs serve应持续构建docs目录确认无报错、理想情况下无新增警告代表该 Bug 或新功能的项目如果是响应 Bug 报告可直接使用已制作的最小复现新功能则构建一个充当测试套件的项目它同时可当作功能演示文档官方示例仓库Material for MkDocs Examples中的相关示例确认仍然构建正常。Dos and Donts不要提交毫无说明的裸改动要先与社区讨论意图让改动理由在写码前就清晰要链接相关讨论或 Issue 提供上下文要不确定就提问要自问改动是否惠及更广社区、让项目变得更好要权衡改动成本与收益——有些改动收益甚微却增加复杂度、可能破坏现有行为或让后续改动脆弱要频繁合并并发变更把冲突概率降到最低。维护者的权利与责任社区治理机制docs/contributing/index.md的最后一部分明确了社区治理规则理解它有助于你判断什么样的互动是被期待的。维护者的职责维护者受社区委托管理沟通秩序有权关闭、移除、拒绝或编辑 Issue、讨论、评论与提交并对不符合贡献指南和行为准则的用户采取封禁措施以维护社区的正向氛围。行为准则与三级处置策略仓库根目录的 CODE_OF_CONDUCT.md 要求所有成员以尊重、包容的语言相待杜绝不当、冒犯或有害行为。对于违反者脚注定义了明确的三级流程首次警告对反复出现不当行为的用户发出首次警告作为正式通知永久有效二次警告与反思期行为持续则二次警告用户获得5 天反思期鼓励公开解释或道歉以澄清误解封禁二次警告后若无回应或改善保留封禁权利。封禁是最后手段仅在保护社区完整性所必需时使用。文档特别说明在绝大多数情况下这个社区非常积极封禁是极其罕见的例外——这体现了项目建设性对话与相互尊重优先的立场。不完整 Issue 与重复内容处理模板字段强制必填模板中每个字段都经过精心设计帮助维护者完整理解问题及其严重程度关闭不完整 Issue维护者保留关闭缺失关键信息如最小复现或不符合模板质量标准的 Issue 的权利补齐信息后可重新打开处理重复内容维护者保留关闭重复 Issue、锁定重复讨论的权利——同一问题多渠道提问会同时消耗多位成员的时间也保留立即关闭未提供新信息就被重新打开的 Issue/讨论的权利自动化工具有限性Lighthouse、无障碍检测工具等自动化工具的输出不构成完整的 Bug 报告——它们可能冗长且含误报需要人工评估。你可以附上生成的报告但它不能替代最小复现或对发现的深入讨论维护者有权将此类 Issue 标记为不完整并关闭。结语从创建 Issue 到合并 Pull RequestMaterial for MkDocs 的贡献流程高度模板化、规则清晰目的只有一个让维护者把时间花在真正有价值的问题上。对贡献者而言掌握这套流程意味着更低的沟通成本与更高的采纳概率——尤其是升级到最新版、移除自定义、附上最小复现这三板斧几乎适用于任何开源项目。想深入实践可以从docs/contributing/目录下的六份指南读起结合 docs/guides/creating-a-reproduction.md 亲手产出一个复现包这本身就是一次对项目工作机制的最佳体验。【免费下载链接】mkdocs-materialDocumentation that simply works项目地址: https://gitcode.com/GitHub_Trending/mk/mkdocs-material创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 
长河君 · 2026/9/10 20:44:42 · 阅读 1.2k Material for MkDocs 贡献指南：Issue 模板、最小复现与 Pull Request 全流程实战
Material for MkDocs 贡献指南Issue 模板、最小复现与 Pull Request 全流程实战【免费下载链接】mkdocs-materialDocumentation that simply works项目地址: https://gitcode.com/GitHub_Trending/mk/mkdocs-material本文以 Material for MkDocs 官方贡献文档为骨架系统讲解如何通过 Issue、最小复现、翻译和 Pull Request 参与这个开源文档主题的维护与演进。读完本文你将掌握四类 Issue 模板的正确用法、用内置 info 插件一键生成可复现的.zip压缩包以及从 Fork 到合并的完整 PR 协作流程并能理解维护者评审与治理背后的规则逻辑。贡献渠道全景六大路径快速导航Material for MkDocs 是一个持续活跃演进的开源项目社区每天都会产生大量 Issue 与讨论Issue 追踪器与讨论板事实上沉淀成了一座知识库是官方文档之外的重要补充。为了让维护者能更快定位问题、评估变更请求并修复缺陷项目围绕创建 Issue和参与贡献两条主线设计了六条标准路径分别对应docs/contributing/目录下的六份专项指南路径适用场景对应文档报告 Bug某个功能不工作了需要附上可复现样例reporting-a-bug.md报告文档问题文档缺信息、有错误或前后不一致reporting-a-docs-issue.md提出变更请求提议新功能、改进建议或方向性想法requesting-a-change.md社区提问有疑问或需要帮助去讨论板交流讨论板添加翻译为已支持语言补翻译或新增一种语言adding-translations.md创建 Pull Request提交代码、文档或新功能等待维护者评审合并making-a-pull-request.md仓库根目录的 CONTRIBUTING.md 与docs/contributing/index.md内容互为镜像前者面向 GitHub 仓库访客后者作为站点文档的贡献章节渲染。无论从哪个入口进入流程完全一致。互动前的自我检查清单在创建 Issue、提问或评论之前请先对照下列问题逐条自查。这套清单的目的是确保你选用了正确的模板、提供了维护者需要的全部信息从而让沟通一次到位。创建 Issue 前是否选用了最合适的 Issue 模板是否存在另一个更贴合你诉求的模板是否已搜索确认没有相似的 Bug 报告或变更请求是否找到了可能相关的旧 Issue是否按要求填满了每个字段并提供了维护者理解问题所需的全部附加信息提问之前这个话题是适合讨论板的问题还是应该作为 Bug 报告 / 变更请求提交到 Issue 追踪器是否已存在相关的开放讨论如果有你的问题和该讨论的方向是否一致还是应该另开新讨论是否向社区提供了足够的信息让对方能快速理解并帮助你评论之前你的评论是否与当前页面、帖子、Issue 或讨论主题相关还是更适合新建一个 Issue 或讨论你的评论是否给对话增加了价值是否建设性、尊重社区与维护者是否其实可以用一个表情符号回复reaction代替!!! warning Issue、讨论与评论是永久性的 你在社区里写下的每一条内容都是永久可见的。请始终保持友善与建设性遵守贡献指南和行为准则。创建 Issue四类模板与使用场景报告 Bug八要素模板docs/contributing/reporting-a-bug.md详细规定了 Bug 报告的八个组成部分[标题]、[上下文可选]、[Bug 描述]、[相关链接]、[复现]、[复现步骤]、[浏览器可选]与[检查清单]。这套模板是维护者处理超过 1600 个 Issue 的经验结晶。报告前的三步准备工作决定你的报告是否会被认真对待升级到最新版本Bug 可能已在后续版本修复因此报告前务必先升级。注意维护者不提供向后移植backport只有最新版本中出现的 Bug 才会被处理。升级方式参考 upgrade.md。移除自定义将mkdocs.yml中的theme.custom_dir、hooks、extra_css、extra_javascript四个设置全部移除后复现。如果 Bug 随之消失说明问题出在你的自定义代码上可以逐项加回设置来缩小根因范围。大版本升级后还要确认所有被覆盖的 partials 已适配新版本。搜索解决方案依次搜索项目文档、Issue 追踪器和讨论板很可能已经有人遇到并解决了相同问题。务必记录你使用的搜索词和相关链接这些信息要写进 Bug 报告——它能帮助维护者发现文档术语与用户用语之间的差异从而改进文档。模板各字段要点标题一句话说清问题本质让人能从标题推断影响与严重程度。好标题示例Built-intypesetplugin changes precedence of nav title overh1避免Title does not workHelp这类含糊标题。上下文可选说明你在什么场景下使用 Material for MkDocs不描述 Bug 本身。某些错误只在特定设置或边缘场景出现例如文档包含数千个页面时。Bug 描述讲清楚是什么而非怎么做尽量简短一两句能说清最好一个 Issue 只报一个 Bug无关问题请分开提交。额外加分项如果你找到了临时 workaround请一并分享。同时要判断这个 Bug 是否属于 Material for MkDocs 本身——它也可能来自上游依赖MkDocs、Python Markdown、Python Markdown Extensions 或第三方插件。一个实用的判别技巧是把theme.name从material改成mkdocs或readthedocs如果问题依然存在那大概率是上游问题应提交给上游项目。相关链接给出你查阅过的、可能与 Bug 相关的文档章节链接以及你在 Issue 追踪器和讨论板中找到的相关讨论。每个链接都是一个 backlink能引导未来的维护者和其他用户。复现一份最小复现是高质量 Bug 报告的心脏具体制作流程见下文第四节。制作完成后会得到一个.zip文件理想情况下不超过 1 MB直接拖拽进该字段即可自动上传。注意项目不接受链接到某仓库的方式因为内置 info 插件生成的压缩包已包含所有必要的环境信息。该字段对 Bug 报告是强制项。复现步骤用最简单的语言列出观察 Bug 的具体步骤不要遗漏任何环节——某些 Bug 只在特定视口或条件下出现。浏览器可选仅当 Bug 只在特定浏览器出现时才需要填写。请先在无痕模式下复现一次排除浏览器插件干扰。检查清单确认你已读完本指南并尽力提供了全部信息。报告文档问题五要素模板项目文档由 80 多个页面组成涵盖功能、配置与自定义的大量信息。发现文档不一致或需要改进时按 reporting-a-docs-issue.md 提交它比 Bug 报告简单——不需要复现只需五个部分标题一句话描述包含关键词以便检索。好示例Clarify social cards setup on Windows。描述简明陈述不一致之处或需要改进的章节说明严重程度同样遵循简短一次一个问题原则。相关链接指向具体文档章节尽量使用锚点链接永久链接方便定位。拟议修改可选可以勾勒粗略想法也可以写出具体修改方案对其他遇到同样问题的用户很有价值。检查清单确认已提供全部信息。变更请求七要素模板与路线图管理变更请求用于建议小的调整、新功能想法或影响项目方向与愿景的建议不用于报告 BugBug 信息不足以支撑调试。提交前请先读一遍项目哲学确认想法与项目基调契合。提交前的准备如果你在别的静态站点生成器或主题中见过类似实现请收集其实现细节说明你喜欢和不喜欢的地方这能加速评估到讨论板与社区交流听取不同视角这有助于新功能惠及更多用户同样记录搜索词与相关链接它们会用在变更请求中。模板七要素标题、上下文可选、描述、相关链接、用例、视觉素材可选、检查清单。要点包括描述讲是什么而非为什么一条请求只提一个想法用例部分要从作者与读者两个视角说明预期影响、受益人群以及是否会破坏现有功能视觉素材可拖拽草图、截图、原型或外部素材也可展示其他项目中的同类实现。维护者如何管理变更请求requesting-a-change.md 的官方流程阅读并评审请求理解想法可能留下评论澄清意图或建议替代方案若想法超出项目范围关闭请求并说明原因若想法与项目愿景一致归类为变更请求并加入专门的 backlog 看板无论结果如何都会关闭请求保持 Issue 追踪器干净、聚焦于开放 Bug。注意Issue 被关闭不代表被遗忘——进入 backlog 的变更请求仍属于长期规划的一部分。该做法的收益是Bug 与功能请求分离用户能更清晰直观地看到项目的维护活跃度相关想法在 backlog 中聚合便于追踪进度与关联关系。如果你的变更请求被拒绝了文档给出的七条评估原则不分先后值得任何贡献者提前了解与项目愿景和基调的契合度与现有功能和插件的兼容性与所有屏幕尺寸和浏览器的兼容性实现与维护的成本对大多数用户的实用性简单易用性可访问性Accessibility被拒绝并非终点——你完全可以借助自定义机制自行实现或在讨论板上询问是否已有人做过。最小复现高质量 Bug 报告的灵魂一份**最小复现reproduction**是 Bug 的简化版本只包含复现该 Bug 所必需的极简设置与文档越简单越好。creating-a-reproduction.md 给出了从零搭建的完整流程其产物是上报 Bug 时必须在Reproduction字段上传的.zip文件——Bug 报告强制要求而提问和变更请求也建议附上可运行的样例以加速沟通。搭建隔离的虚拟环境推荐使用 Python 虚拟环境任何安装或升级的包都只作用于该环境出问题可随时删除重建# 创建虚拟环境 python3 -m venv venv激活环境macOS / Linux. venv/bin/activateWindows. venv/Scripts/activate激活后终端提示符前会出现(venv)表示已进入虚拟环境退出用deactivate。四步搭建最小复现项目升级到最新版本Bug 可能已修复pip install --upgrade --force-reinstall mkdocs-material初始化全新空项目注意必须是新建的空目录mkdocs new .然后写入最小配置 mkdocs.ymltheme: name: material只添加复现 Bug 所必需的设置。如果是渲染类 Bug只创建必要数量的 Markdown 文档。反复精简直到能稳定观察到 Bug。打包前再次检查删除所有删掉后 Bug 就不出现的非必要配置行与文件。用内置 info 插件一键打包Material for MkDocs 9.0.0 起内置了专为生成复现包而设计的 info 插件。在mkdocs.yml中加入plugins: - info运行mkdocs build插件会自动收集所有相关文件并生成压缩包同时打印摘要并退出。官方文档给出的输出示例如下INFO - Started archive creation for bug report INFO - Archive successfully created: example/.dependencies.json 859.0 B example/.versions.log 83.0 B example/docs/index.md 282.0 B example/mkdocs.yml 56.0 B example.zip 1.8 kB把生成的.zip直接拖入 Bug 报告模板的 Reproduction 字段即可。源码视角info 插件到底做了什么从实现看info 插件的全部逻辑集中在 src/plugins/info/plugin.py其配置项定义在 src/plugins/info/config.py。on_config钩子以event_priority(100)的优先级最早执行plugin.py整个流程体现了先守规矩、再打包的设计版本校验插件会请求最新 Release 信息将当前安装版本与最新版本比对不一致时打印升级提示并退出plugin.py自定义拦截检测到theme.custom_dir或hooks设置时打印请移除提示并中止因为这属于无法官方支持的自定义行为plugin.py路径校验确保mkdocs.yml、docs_dir、自定义目录、INHERIT继承配置等路径都位于当前工作目录root之下否则拒绝打包防止生成无法独立运行的复现包plugin.py智能排除自动排除site_dir、已激活与未激活的虚拟环境目录通过扫描pyvenv.cfg识别、projects 插件的构建目录以及包含sitemap.xml.gz的目录plugin.py、plugin.py交互式命名打包前会提示Please name your bug report (2-4 words)压缩包以版本号 关键词形式命名plugin.py环境信息兜底自动写入requirements.lock.txt当前环境全部已安装包及其版本与platform.json系统、架构、Python 版本、工作目录、启动命令、PYTHONPATH/VIRTUAL_ENV环境变量、sys.path、被排除条目并将用户名替换为USERNAME占位符以保护隐私plugin.py安全提示压缩包超过 1 MB 时警告超过推荐上限包含.dotpath隐藏文件/目录时提醒可能含敏感信息请人工核验后再上传plugin.py。info 插件共有四个配置项config.pyenabled默认true整体开关、enabled_on_serve默认false控制mkdocs serve预览时是否启用便于快速迭代复现包、archive默认true是否生成压缩包仅用于调试插件本身、archive_stop_on_violation默认true违反上述规则时是否中止打包。最后一个选项仅供报告文档明确提到过的自定义功能相关 Bug 时使用此时应设为false并在报告中说明理由。完整配置说明见 docs/plugins/info.md。翻译贡献让更多语言被支持Material for MkDocs 在社区帮助下已被翻译成60 多种语言维护者无力逐语言跟进新功能也时常需要新翻译。如果你发现自己的语言缺少翻译或想新增一种语言按 adding-translations.md 操作即可。动手前先检查确认语言可用性在站点语言列表中检查你的语言是否已支持——已支持则补缺失翻译通常只需 5 分钟未支持则帮助新增搜索 Issue 追踪器可能已有其他贡献者提交了同语言的翻译待整合避免重复劳动。翻译 Issue 模板四要素标题更新既有语言可保留原标题新增语言时把预填标题中的...替换为语言名例如 Add translations for German翻译内容标有图标的行表示缺失翻译翻译后移除该图标不确定的行可留给其他贡献者完成。为保证准确性可对照英文基准翻译仓库中所有语言的模板都位于src/templates/partials/languages/目录国家旗帜可选在图标与表情符号搜索页中搜索flag找到旗帜 shortcode 填入。注意 Twemoji 仅提供 260 个国家的旗帜国家的下级行政区省、州、地区不支持此时请选最合适的替代旗帜检查清单确认信息齐全。署名机制通过模板提交翻译后你会在提交中被记录为共同作者co-author无需再走 Pull Request 流程。Pull Request 工作流从 Fork 到合并making-a-pull-request.md 给出了完整的 PR 流程。核心原则是动手写代码之前先与社区讨论清楚你想做什么——疑似 Bug 先报 Bug 报告文档改动先建文档问题新功能先提变更请求。你的目标可能已能通过配置或自定义实现提前沟通能避免无效劳动。准备变更与草稿 PR整体流程可用下面的时序图概括fork → clone → topic branch → 迭代提交 → 同步上游 → 草稿 PR → 评审具体步骤Fork 仓库在 GitHub 上 Fork Material for MkDocs 仓库获得可推送的副本注意同一仓库同时只能有一个 fork。建议在仓库名后追加-fork后缀并补充描述让路过的人明白这是一个临时分支副本克隆到本地开始修改创建 topic 分支所有贡献都应在一个描述工作内容的主题分支上进行便于同时进行多项工作也向他人明确这是进行中的代码如需改动代码按开发环境搭建指引准备环境迭代编辑与提交按有意义的提交块分批提交不要一次全提交。细粒度的增量提交远比跨多文件的大改动容易评审务必写有意义的提交信息定期推送到你的 fork持续同步上游长时间工作时尤其重要创建 PR 前至少必须合并一次上游并发变更以降低冲突风险创建草稿 PRdraft引用引发工作的讨论或 Issue尽早获得维护者和其他人的反馈可在关键节点显式请求评审以评审者视角自查审视 diff 是否足够小、是否符合项目编码风格、是否破坏了docs目录下项目自身文档的构建有反馈则按需迭代。定稿、评审与合并当你认为改动已可作为正式贡献时将 PR 转为**定稿finalize**状态请求维护者评审squidfunk维护者可能提出评论请保持尊重地讨论。要理解维护者往往从多年维护的长期视角看问题而你更聚焦于眼前的 Issue 或功能并非所有 PR 都会被合并——它可能暴露阻塞集成的新问题或揭示更好的通用方案这些都有助于项目进步按反馈修改并推送到 forkPR 会自动更新可能需要多轮迭代评审满意后维护者将其合并进主分支master过程中可能squash压缩你的提交并编辑提交信息。此时你已成功贡献改动将以你的名义出现在主分支合并后清理先在 fork 上删除分支从主仓库把改动 pull 回 fork 的 master 分支删除本地 clone 的 topic 分支把改动 pull 到本地 master 分支。关键命令速查开发最好在独立的 topic 分支上进行# 创建并切换到新分支 git switch -c name # 推送到 fork 并建立跟踪关系-u --set-upstream git push -u origin name工作周期较长时把上游仓库注册为upstream远程git remote add upstream https://github.com/squidfunk/mkdocs-material.git之后显式从上游拉取并发变更git pull upstream master该命令会把master分支的变更取回并合并进当前 topic 分支。PR 合并后清理分支git switch master git branch -d name后续再做新 PR 时务必从最新历史起步——最稳妥的做法是删除 fork 重新 Fork或通过 GitHub UI 同步 fork 后 pull 到本地 master。测试与评审三个冒烟测试提交前至少在三类项目上验证改动Material for MkDocs 自身的文档按开发环境指引搭建后mkdocs serve应持续构建docs目录确认无报错、理想情况下无新增警告代表该 Bug 或新功能的项目如果是响应 Bug 报告可直接使用已制作的最小复现新功能则构建一个充当测试套件的项目它同时可当作功能演示文档官方示例仓库Material for MkDocs Examples中的相关示例确认仍然构建正常。Dos and Donts不要提交毫无说明的裸改动要先与社区讨论意图让改动理由在写码前就清晰要链接相关讨论或 Issue 提供上下文要不确定就提问要自问改动是否惠及更广社区、让项目变得更好要权衡改动成本与收益——有些改动收益甚微却增加复杂度、可能破坏现有行为或让后续改动脆弱要频繁合并并发变更把冲突概率降到最低。维护者的权利与责任社区治理机制docs/contributing/index.md的最后一部分明确了社区治理规则理解它有助于你判断什么样的互动是被期待的。维护者的职责维护者受社区委托管理沟通秩序有权关闭、移除、拒绝或编辑 Issue、讨论、评论与提交并对不符合贡献指南和行为准则的用户采取封禁措施以维护社区的正向氛围。行为准则与三级处置策略仓库根目录的 CODE_OF_CONDUCT.md 要求所有成员以尊重、包容的语言相待杜绝不当、冒犯或有害行为。对于违反者脚注定义了明确的三级流程首次警告对反复出现不当行为的用户发出首次警告作为正式通知永久有效二次警告与反思期行为持续则二次警告用户获得5 天反思期鼓励公开解释或道歉以澄清误解封禁二次警告后若无回应或改善保留封禁权利。封禁是最后手段仅在保护社区完整性所必需时使用。文档特别说明在绝大多数情况下这个社区非常积极封禁是极其罕见的例外——这体现了项目建设性对话与相互尊重优先的立场。不完整 Issue 与重复内容处理模板字段强制必填模板中每个字段都经过精心设计帮助维护者完整理解问题及其严重程度关闭不完整 Issue维护者保留关闭缺失关键信息如最小复现或不符合模板质量标准的 Issue 的权利补齐信息后可重新打开处理重复内容维护者保留关闭重复 Issue、锁定重复讨论的权利——同一问题多渠道提问会同时消耗多位成员的时间也保留立即关闭未提供新信息就被重新打开的 Issue/讨论的权利自动化工具有限性Lighthouse、无障碍检测工具等自动化工具的输出不构成完整的 Bug 报告——它们可能冗长且含误报需要人工评估。你可以附上生成的报告但它不能替代最小复现或对发现的深入讨论维护者有权将此类 Issue 标记为不完整并关闭。结语从创建 Issue 到合并 Pull RequestMaterial for MkDocs 的贡献流程高度模板化、规则清晰目的只有一个让维护者把时间花在真正有价值的问题上。对贡献者而言掌握这套流程意味着更低的沟通成本与更高的采纳概率——尤其是升级到最新版、移除自定义、附上最小复现这三板斧几乎适用于任何开源项目。想深入实践可以从docs/contributing/目录下的六份指南读起结合 docs/guides/creating-a-reproduction.md 亲手产出一个复现包这本身就是一次对项目工作机制的最佳体验。【免费下载链接】mkdocs-materialDocumentation that simply works项目地址: https://gitcode.com/GitHub_Trending/mk/mkdocs-material创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考