创建一个复现

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

指南

环境 可选

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

使用以下命令创建一个新的虚拟环境：

python3 -m venv venv

使用以下命令激活环境：

macOS

. venv/bin/activate

Windows

. venv/Scripts/activate

Linux

. venv/bin/activate

您的终端现在应该在提示符之前打印 (venv)，这样您就知道您正在使用刚刚创建的虚拟环境。

使用以下命令退出环境：

deactivate

最小复现

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

1. 如我们的错误报告指南中所述，确保您正在运行最新版本的 Material for MkDocs，它可能已经包含了对该错误的修复：

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

1. 使用 mkdocs 可执行文件引导一个新的文档项目，这将作为复现的基础。为此，必须创建一个新的空项目：

mkdocs new .

首先，在 mkdocs.yml 中添加最小配置：

theme:
    name: material

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

2. 在打包成 .zip 文件之前的最后一步是，仔细检查所有设置和文档，确保它们对复现是必要的，也就是说，当它们被省略时，错误不会发生。删除所有非必要的行和文件。

创建一个 .zip 文件

Material for MkDocs 9.0.0 包含一个新的插件，专门用于创建用于错误报告的复现。当启用内置的 info 插件时，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