Built-in info plugin
The info plugin is a utility that is solely intended to create self-contained minimal reproductions as .zip files when reporting bugs or proposing change requests, making communication between us maintainers and you much easier, as we have a common ground to work on.
Objective
How it works
The plugin helps you to prepare a minimal reproduction by collecting the necessary information about the environment and configuration of your project. This makes it easier for us to fix bugs, as it requires that you upgrade to the latest version and remove your customizations.
When following these principles, you can be confident that you don't report a bug that has already been fixed in a subsequent release, or which is caused by one of your customizations. Even more importantly, you actively help us to fix the bug as quickly as possible.
The output of the plugin is a .zip file that you can share with us maintainers.
When to use it
Whenever you're reporting a bug or have something to discuss, like a question or change request, you should attach a small, self-contained minimal reproduction. Runnable examples help to make communication much more efficient, giving us maintainers more time to benefit more users by pushing the project forward. Minimal reproductions are mandatory for bug reports.
Configuration
In order to get started with the built-in info plugin, just add the following lines to mkdocs.yml, and quickly create a minimal reproduction to share with us maintainers:
The info plugin is built into Material for MkDocs and doesn't need to be installed.
General
The following settings are available:
Use this setting to enable or disable the plugin when building your project. It's normally not necessary to specify this setting, but if you want to disable the plugin, use:
Use this setting to control whether the plugin should be enabled when previewing your site. It's normally not necessary to specify this setting, but if you want to change this behavior, use:
This setting streamlines the process of creating and inspecting minimal reproductions, as it allows to quickly iterate on the reproduction without having to disable the plugin first.
Archive
Use this setting to control whether the plugin should create a .zip file from the project or exit after the version check. This setting is solely intended for debugging the plugin itself:
Use this setting to control whether the plugin should stop creating the .zip file when one of the requirements is not satisfied. This setting must only be used when reporting a bug that is related to a customization explicitly mentioned in our documentation. You can change it with:
If you're using this setting when reporting a bug, please explain why you think it is necessary to include customizations. If you're unsure, please ask us first by creating a discussion.