Material for MkDocs 内置 info 插件一条命令打包最小复现让 Bug 报告一次到位【免费下载链接】mkdocs-materialDocumentation that simply works项目地址: https://gitcode.com/GitHub_Trending/mk/mkdocs-material导读info是 Material for MkDocs 9.0.0 起内置的实用型插件唯一用途是在你报告 Bug或提交变更请求时自动收集项目环境与配置信息打包出一个可直接运行、自包含的最小复现.zip文件供维护者直接解压复现。读完本文你将掌握 info 插件的完整配置项、底层工作流程版本检查、自定义项拦截、路径校验、排除规则与归档生成并能用它在几秒内生成符合官方规范的高质量复现包。info 插件是什么info 插件是一个纯粹的工具型插件它不参与文档渲染也不改变构建产物而是作为一个“前置检查 打包器”存在。启用后执行mkdocs build会在正常构建之前介入校验你的项目是否满足复现规范然后把项目快照压缩成.zip文件并打印一份归档内容清单。它解决的问题非常具体维护者在排查 Bug 时最怕拿到一个“环境不明、依赖缺失、还混着大量自定义代码”的仓库链接。info 插件把复现所需的一切——配置、文档、依赖锁定文件、平台信息——统一收进一个.zip从而让报告 Bug与变更请求的沟通成本降到最低。在插件体系中它隶属于内置插件的Management管理类别与 group、meta、projects 并列官方文档对其定位是“帮助创建自包含最小复现让维护者更快修复已报告的 Bug”。工作原理info 插件在on_config事件中以最高优先级event_priority(100)即最早执行介入其核心逻辑位于 plugin.py。它通过收集项目环境与配置的必要信息来“强制”复现规范规范包含两条硬性要求升级到最新版本插件会请求 GitHub Releases 的 latest 重定向地址取出最新版本号与当前安装的mkdocs-material版本比对不一致则直接中止并提示pip install --upgrade --force-reinstall mkdocs-material。这能确保你不会报告一个已在后续版本中被修复的 Bug。移除自定义项插件会检测theme.custom_dir与hooks设置一旦存在就中止并列出需要移除的项目custom_dir、hooks、extra_css、extra_javascript避免把问题归结到你的覆盖代码上。只要这两条原则被满足你就可以确信报告的不是一个已经修复的问题也不是自定义代码引起的伪 Bug而插件最终输出的.zip文件就是你和维护者之间的“共同语言”。何时使用任何一次 Bug 报告都必须附带最小复现。官方在 reporting-a-bug.md 中明确最小复现是 Bug 报告的核心.zip建议不超过 1 MB直接拖拽上传到 issue 即可。此外即使只是提问、讨论或提出变更请求也建议附带可运行的最小复现——可运行示例能让沟通更高效让维护者有更多时间推进项目本身。快速开始info 插件是 Material for MkDocs 的内置组件随主题一起分发无需额外安装。只需在mkdocs.yml中加入plugins: - info然后在项目根目录执行mkdocs build插件会先完成版本校验与环境检查接着提示你为 Bug 报告起一个 2~4 个词的短名称该名称会被 slugify 并作为归档内目录名与.zip文件名最后在项目根目录生成example.zip。参考 creating-a-reproduction.md 中的真实输出构建日志大致如下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注意info是mkdocs.plugins入口点中的内置插件通过 pyproject.toml 的material/info material.plugins.info.plugin:InfoPlugin注册因此配置里的插件名info直接可用不需要pip install任何第三方包。配置参考info 插件共四个配置项全部为布尔类型均从 config.py 中解析。下文逐一说明默认值与适用场景。enabled版本9.0.0默认true控制插件在构建项目时是否启用。通常无需配置若需临时关闭使用plugins: - info: enabled: falseenabled_on_serve版本9.0.6默认false控制插件在预览站点mkdocs serve时是否启用。默认关闭以免干扰日常预览。当你需要快速迭代复现内容时可开启plugins: - info: enabled_on_serve: true开启后mkdocs serve同样会执行复现检查与归档生成省去“先改配置、再 build”的往返。插件在on_startup中通过command serve判断当前是否为预览模式见 plugin.py再结合此配置决定是否跳过执行。archive版本9.0.0默认true控制插件在版本检查通过后是否继续生成.zip归档。此选项仅用于调试插件本身plugins: - info: archive: false从源码看当archive: false时插件在版本校验之后立即sys.exit(1)跳过整个归档流程。archive_stop_on_violation版本9.0.0默认true控制当复现要求未满足如检测到自定义项、路径越界时插件是否立即中止。默认中止仅当你报告的 Bug 恰恰与文档中明确提到的自定义项相关时才应关闭它plugins: - info: archive_stop_on_violation: false若在报告 Bug 时使用此配置请在 issue 中说明为何必须包含自定义代码不确定时先通过官方讨论区确认。源码中_help_on_versions_and_exit、_help_on_customizations_and_exit、_help_on_not_in_cwd三个辅助方法都会检查该开关关闭时只打印提示而不退出允许复现包继续生成。底层流程从mkdocs build到example.zip理解插件内部流程能帮你准确预判它在什么情况下会“拦截”构建。以下均可在 plugin.py 中逐行印证。1. 版本校验插件请求https://github.com/squidfunk/mkdocs-material/releases/latestallow_redirectsFalse从响应头location中解析最新版本号与importlib.metadata.version(mkdocs-material)对比。若当前版本不是最新版的前缀匹配则打印升级指引并默认退出。2. 自定义项拦截对config.theme.custom_dir与config.hooks做检测命中即提示“Please remove custom_dir setting”等并列出custom_dir、hooks、extra_css、extra_javascript四项需要移除的内容。这是保证复现“干净”的关键闸门。3. 路径校验插件将config_file_path、docs_dir、custom_dir、projects 插件的projects_dir、INHERIT继承配置路径以及各 hook 路径统一转为绝对路径_convert_to_abs再断言它们都是当前工作目录cwd的子路径。任何越界路径都会触发_help_on_not_in_cwd报错确保解压后的复现包能独立运行。值得一提的是插件对INHERIT配置做了特殊处理由于 MkDocs 加载后会合并父配置、抹掉该键插件用自定义 YAML 加载器_load_yaml重新解析配置链递归收集所有继承文件并纳入路径校验与归档避免复现包因缺少父配置而无法运行。4. 排除规则插件通过get_exclusion_patterns()见 patterns.py获得一组正则排除模式并在运行时动态追加规则项目根下的site_dir构建输出目录激活的虚拟环境目录通过site.PREFIXES判定遍历目录树时发现的、处于非激活状态的pyvenv.cfg所在目录即“可能未激活的 venv”会先打印提示再排除使用 projects 插件时各子项目的site_dir从子项目配置文件中解析。静态排除模式包括__pycache__、.DS_Store、生成的.zip、.cache文件/目录以及.vscode、.vs、.idea等 IDE 自动生成目录。所有模式基于 POSIX 化路径、以^前缀限定做re.search匹配目录路径统一带结尾/以便与文件区分。此外插件对.dotpath以.开头的文件/目录并不排除而是高亮提示并记录——因为.dependencies.json、.versions.log等本身就是复现包的有用成分但它会警告可能包含敏感信息提醒你提交前检查。5. 归档生成与元数据插件以内存BytesIO作为临时归档使用ZipFile(..., ZIP_DEFLATED)压缩遍历当前工作目录写入文件保持相对目录结构统一放入以复现名命名的顶层目录下。同时自动写入两份关键元数据文件requirements.lock.txt当前 Python 环境全部已安装发行版的名称版本锁定列表来自importlib.metadata.distributions()让维护者能精确还原依赖platform.json以 JSON 记录操作系统与架构platform.platform()、platform.architecture()、Python 版本、cwd、触发构建的完整命令行、PYTHONPATH、VIRTUAL_ENV、sys.path以及被排除的条目列表并对当前用户名做USERNAME占位替换避免泄露隐私。最后将内存归档落盘为example.zip按文件名排序打印归档内每个文件及压缩后大小并给出总量。若归档超过 1 MB会警告“超出推荐的 1 MB 上限”若包含.dotpath会再次提示检查敏感信息。随后插件以sys.exit(1)结束不会继续执行正常构建——这正是它“专门用于产出复现包”的定位体现。实战完整的最小复现工作流结合 creating-a-reproduction.md一套推荐的完整流程如下创建隔离环境可选但推荐用虚拟环境隔离运行时遇到问题可直接重建python3 -m venv venvmacOS / Linux 激活. venv/bin/activateWindows 激活. venv/Scripts/activate退出deactivate确保版本最新pip install --upgrade --force-reinstall mkdocs-material全新初始化骨架项目务必从空项目开始mkdocs new .并在mkdocs.yml中写入最小配置theme: name: material逐步添加复现所需的最小配置只保留能复现问题的设置与 Markdown 文档反复迭代直到 Bug 可稳定观察。清理非必要内容逐条检查配置与文档删除任何“去掉后 Bug 消失”的冗余项。启用 info 插件并打包plugins: - info执行mkdocs build得到example.zip。提交将.zip理想情况下不超过 1 MB直接拖入 issue 的 Reproduction 字段同时遵循 reporting-a-bug.md 填写标题、Bug 描述、相关链接、复现步骤等并勾选提交前清单。常见问题与注意事项构建被中途打断、没有产出.zip大概率命中了版本校验或自定义项拦截。请先升级到最新版、移除custom_dir/hooks再重新构建。提示“One or more paths arent children of root”你的docs_dir、INHERIT父配置或 hook 位于项目根目录之外。请调整目录结构并确保在项目根目录执行mkdocs build而非子目录。归档超 1 MB检查是否混入了site构建产物、大体积图片或未激活的虚拟环境插件已尽力自动排除上述内容剩余体积应来自复现必需的文件。归档含.dotpath插件会明确警告提交前请核对.dependencies.json等文件是否包含不应公开的信息只分享复现必需的数据。关于archive_stop_on_violation: false仅在 Bug 与文档明确支持的自定义项如文档中提到的extends base用法相关时使用并在 issue 中主动说明原因切勿用它绕过规范提交含大量自定义代码的复现包。小结info 插件把“如何写出高质量 Bug 报告”这件事自动化一条配置、一条命令即可产出包含环境元数据、依赖锁定与全部必需文件的自包含复现包。对使用者而言它降低了提交有效复现的门槛对维护者而言它保证了每次排障都有可运行、可复现的共同起点。如果你正准备向 Material for MkDocs 报告问题不妨从plugins: [info]开始让 Bug 修复的协作效率更进一步。【免费下载链接】mkdocs-materialDocumentation that simply works项目地址: https://gitcode.com/GitHub_Trending/mk/mkdocs-material创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考