mirror of
https://github.com/squidfunk/mkdocs-material.git
synced 2024-12-25 22:04:52 +01:00
122 lines
3.3 KiB
Markdown
122 lines
3.3 KiB
Markdown
---
|
||
title: Built-in group plugin
|
||
icon: material/format-list-group
|
||
---
|
||
|
||
# Built-in group plugin
|
||
|
||
The group plugin allows to group plugins into logical units to conditionally
|
||
enable or disable them for specific environments with the use of
|
||
[environment variables][mkdocs.env], e.g., to only enable a subset of
|
||
plugins when [building your project] during continuous integration (CI).
|
||
|
||
[building your project]: ../creating-your-site.md#building-your-site
|
||
|
||
## Objective
|
||
|
||
### How it works
|
||
|
||
The plugin conditionally and lazily loads all plugins that are part of a group
|
||
if and only if the group is enabled, which means that the plugin doesn't add any
|
||
overhead when the group is disabled. It also means that the grouped plugins
|
||
only need to be installed when the group is enabled.
|
||
|
||
The plugins that are part of the group are executed in the same order as if
|
||
they were defined at the top-level in the list of [`plugins`][mkdocs.plugins].
|
||
Thus, order is preserved and deterministic.
|
||
|
||
### When to use it
|
||
|
||
Whenever you're using multiple plugins that are only required in specific
|
||
environments, e.g., when building your project during continuous integration
|
||
(CI), the plugin is the perfect utility for making configuration simpler, as it
|
||
removes the need for splitting configuration into multiple files.
|
||
|
||
It can be used with any built-in or third-party plugin.
|
||
|
||
## Configuration
|
||
|
||
<!-- md:version 9.3.0 -->
|
||
<!-- md:plugin [group] – built-in -->
|
||
<!-- md:flag multiple -->
|
||
<!-- md:flag experimental -->
|
||
|
||
As with all [built-in plugins], getting started with the group plugin is
|
||
straightforward. Just add the following lines to `mkdocs.yml`, and start
|
||
splitting plugins into logical units:
|
||
|
||
``` yaml
|
||
plugins:
|
||
- group
|
||
```
|
||
|
||
The group plugin is built into Material for MkDocs and doesn't need to be
|
||
installed.
|
||
|
||
[group]: group.md
|
||
[built-in plugins]: index.md
|
||
|
||
### General
|
||
|
||
The following settings are available:
|
||
|
||
---
|
||
|
||
#### <!-- md:setting config.enabled -->
|
||
|
||
<!-- md:version 9.3.0 -->
|
||
<!-- md:default `false` -->
|
||
|
||
Use this setting to enable or disable the plugin when [building your project].
|
||
The plugin behaves differently than all other built-in plugins – __it is
|
||
disabled by default__. To enable a group, use:
|
||
|
||
``` yaml
|
||
plugins:
|
||
- group:
|
||
enabled: !ENV CI # (1)!
|
||
```
|
||
|
||
1. If you only want to use the group plugin for better organization and
|
||
always want to enable the plugins that are part of it, use:
|
||
|
||
``` yaml
|
||
plugins:
|
||
- group:
|
||
enabled: true
|
||
```
|
||
|
||
The decision to disable the plugin by default was made to simplify the usage
|
||
of environment variables, as it removes the need to provide a default value for
|
||
an environment variable.
|
||
|
||
Now, when [building your project], you can enable a group by setting the
|
||
[environment variable][mkdocs.env]:
|
||
|
||
``` sh
|
||
CI=true mkdocs build
|
||
```
|
||
|
||
[building your project]: ../creating-your-site.md#building-your-site
|
||
|
||
---
|
||
|
||
#### <!-- md:setting config.plugins -->
|
||
|
||
<!-- md:version 9.3.0 -->
|
||
<!-- md:default none -->
|
||
|
||
Use this setting to list the plugins that are part of the group. The syntax is
|
||
exactly the same as for the [`plugins`][mkdocs.plugins] setting, so you can
|
||
simply copy the list of plugins that you want to group, e.g:
|
||
|
||
``` yaml
|
||
plugins:
|
||
- group:
|
||
plugins:
|
||
- optimize
|
||
- minify
|
||
```
|
||
|
||
The plugins mentioned here are just used for illustration purposes.
|