创建复现¶

复现是一个简化版本的错误示例，展示了错误发生的特定场景。它包括所有必要的最小设置和说明，并且应该尽可能简单，同时仍能展示问题。

指南¶

环境 可选¶

我们推荐使用 virtual environment，这是一个隔离的 Python 运行环境。如果您在虚拟环境中，您安装或升级的任何包都将仅限于该环境。如果遇到问题，您可以简单地删除并重新创建该环境。设置非常简单：

• 创建一个新的虚拟环境：

  python3 -m venv venv
  

• 激活环境：

  macOS Windows Linux

  . venv/bin/activate
  

  . venv/Scripts/activate
  

  . venv/bin/activate
  

  现在您的终端应该在提示符前显示 (venv)，这表示您已进入刚刚创建的虚拟环境。

• 退出环境：

  deactivate
  

最小复现¶

按照以下说明，您将设置一个骨架项目以创建复现。如上所述，我们推荐使用 virtual environment，因此请在您的工作目录中创建一个新文件夹，并在其中创建一个新的虚拟环境。接下来：

1. 如我们在 bug reporting guide 中提到的，确保您正在运行最新版本的 Material for MkDocs，该版本可能已经包含了错误的修复：

   pip install --upgrade --force-reinstall mkdocs-material
   

2. 使用 mkdocs 可执行文件引导一个新的文档项目，作为复现的基础。为此创建一个新的空项目是至关重要的：

   mkdocs new .
   

   首先在 mkdocs.yml 中添加 minimal configuration：

   theme:
     name: material
   

3. 现在，仅在 mkdocs.yml 中添加必要的设置，以保持复现的最小化。如果您正在为渲染错误创建复现，请仅创建必要数量的 Markdown 文档。重复此步骤，直到可以观察到您想要报告的错误。

4. 最后一步，在将所有内容打包到 .zip 文件之前，请仔细检查所有设置和文档是否对复现至关重要，这意味着在省略它们时不会出现错误。删除所有非必要的行和文件。

创建 .zip 文件¶

Material for MkDocs 9.0.0 包含一个新插件，专门用于为错误报告创建复现。当启用内置信息插件时，MkDocs 将把所有相关文件添加到 .zip 中，打印摘要到终端并退出。将以下行添加到 mkdocs.yml 中：

plugins:
  - info

现在，当运行 mkdocs build 时，将自动创建一个名为 example.zip 的文件，包含您可以直接附加到错误报告中的最小复现。

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