4.5 KiB
| title | icon |
|---|---|
| Built-in info plugin | material/information |
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:
plugins:
- info
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:
plugins:
- info:
enabled: false
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:
plugins:
- info:
enabled_on_serve: true
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:
plugins:
- info:
archive: false
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:
plugins:
- info:
archive_stop_on_violation: false
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.