Creating a reproduction¶
A reproduction is a simplified version of a bug that demonstrates the specific scenario in which the bug occurred. It includes all necessary minimal settings and instructions and should be as simple as possible while still demonstrating the issue.
We recommend using a virtual environment, which is an isolated Python runtime. If you are in a virtual environment, any packages that you install or upgrade will be local to the environment. If you run into problems, you can just delete and recreate the environment. It's trivial to set up:
Create a new virtual environment with:
Activate the environment with:
Your terminal should now print
(venv)before the prompt, which is how you know that you are inside the virtual environment that you just created.
Exit the environment with:
Following the instructions below, you will set up a skeleton project to create a reproduction. As mentioned above, we recommend using a virtual environment, so create a new folder in your working directory and a a new virtual environment inside it. Next:
As mentioned in our bug reporting guide, ensure that you're running the latest version of Material for MkDocs, which might already include a fix for the bug:
Bootstrap a new documentation project using the
mkdocsexecutable, which you use as a basis for the reproduction. It's essential to create a new, empty project for this:
Start by adding the minimal configuration in
Now, only add the necessary settings to
mkdocs.ymlto keep the reproduction minimal. If you are creating a reproduction for a rendering bug, create only the necessary amount of Markdown documents. Repeat this step until the bug you want to report can be observed.
As a last step, before packing everything into a .zip file, double-check all settings and documents if they are essential to the reproduction, which means that the bug does not occur when they are omitted. Remove all non-essential lines and files.
Creating a .zip file¶
Material for MkDocs 9.0.0 includes a new plugin solely intended to create reproductions for bug reports. When the built-in info plugin is enabled, MkDocs will add all relevant files to a .zip, print a summary to the terminal and exit. Add the following lines to
Now, when running
mkdocs build, a file called
example.zip is automatically created, containing the minimal reproduction you can directly attach to your bug report.