Ana içeriğe geç

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

9.0.0 info – built-in

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:

enabled

9.0.0 true

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

enabled_on_serve

9.0.6 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

archive

9.0.0 true

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

archive_stop_on_violation

9.0.0 true

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.