diff --git a/CHANGELOG b/CHANGELOG index 2797b2bd6..4e725790b 100644 --- a/CHANGELOG +++ b/CHANGELOG @@ -1,3 +1,10 @@ +mkdocs-material-9.3.0 (2023-09-11) + + * Improved configuration sharing between community and Insiders edition + * Added built-in group plugin for enabling plugins conditionally + * Added new settings in tags plugin for enabling/disabling + * Dropped support for Python 3.7 (EOL) + mkdocs-material-9.2.8+insiders-4.40.4 (2023-09-04) * Fixed privacy plugin choking on boolean HTML5 attributes diff --git a/docs/changelog/index.md b/docs/changelog/index.md index 1b70bb4af..56eec81e8 100644 --- a/docs/changelog/index.md +++ b/docs/changelog/index.md @@ -2,6 +2,13 @@ ## Material for MkDocs +### 9.3.0 September 11, 2023 { id="9.3.0" } + +- Improved configuration sharing between community and Insiders edition +- Added built-in group plugin for enabling plugins conditionally +- Added new settings in tags plugin for enabling/disabling +- Dropped support for Python 3.7 (EOL) + ### 9.2.8 September 4, 2023 { id="9.2.8" } - Updated Italian and Russian translations diff --git a/docs/insiders/getting-started.md b/docs/insiders/getting-started.md index 981ea674f..cd5341e78 100644 --- a/docs/insiders/getting-started.md +++ b/docs/insiders/getting-started.md @@ -150,65 +150,77 @@ pip install --upgrade git+https://${GH_TOKEN}@github.com/squidfunk/mkdocs-materi [upgrade guide]: ../upgrade.md -## Caveats +## Built-in plugins -This section describes some aspects to consider when using Insiders together -with Material for MkDocs to ensure that users without access to Insiders can -still build your documentation. - -### Built-in plugins - -When using built-in plugins that are solely available via Insiders, it might be -necessary to split the `mkdocs.yml` configuration into a base configuration, and -one with plugin overrides. Note that this is a limitation of MkDocs, which can -be mitigated by using [configuration inheritance]: - -=== ":octicons-file-code-16: `mkdocs.insiders.yml`" - - ``` yaml - INHERIT: mkdocs.yml - plugins: - - search - - social - - tags - ``` - -=== ":octicons-file-code-16: `mkdocs.yml`" - - ``` yaml - # Configuration with everything except Insiders plugins - ``` - -Now, when you're in an environment with access to Insiders (e.g. in your CI -pipeline), you can build your documentation project with the following lines: - -``` -mkdocs build --config-file mkdocs.insiders.yml -``` - -!!! tip "Sharing plugin and extension configuration" - - If you want to share `plugins` or `markdown_extensions` between both - configuration files `mkdocs.insiders.yml` and `mkdocs.yml`, you can use - the alternative key-value syntax in both files. The above example would - then look like: - - === ":octicons-file-code-16: `mkdocs.insiders.yml`" - - ``` yaml - INHERIT: mkdocs.yml - plugins: - social: {} - ``` - - === ":octicons-file-code-16: `mkdocs.yml`" - - ``` yaml - # Additional configuration above - plugins: - search: {} - tags: {} - ``` +When you're using built-in plugins that are solely available via Insiders, +outside contributors won't be able to build your documentation project on their +local machine. This is the reason why we developed the [built-in group plugin] +that allows to conditionally load plugins. + [^1]: + Previously we recommended to use [configuration inheritance] to work around + this limitations, but the brand new [built-in group plugin] is a much better + approach, as it allows you to use a single configuration file for building + your project with the community edition and Insiders version of Material + for MkDocs. + [built-in group plugin]: #built-in-group-plugin [configuration inheritance]: https://www.mkdocs.org/user-guide/configuration/#configuration-inheritance + +### Built-in group plugin + +[:octicons-tag-24: 9.3.0][Group plugin support] · +:octicons-cpu-24: Plugin · +:octicons-beaker-24: Experimental + +The built-in group plugin adds support for conditionally loading plugins based +on environments. This makes enabling and disabling of multiple plugins much +simpler, as you can group them into logical units and enable or disable them +with an [environment variable]: + +``` yaml +plugins: + - group: + enabled: !ENV CI + plugins: + - optimize + - minify +``` + +[`enabled`](#+group.enabled){ #+group.enabled } + +: :octicons-milestone-24: Default: `false` – This option specifies whether + the plugin is enabled when building your project. By default, the plugin is + disabled, so you can use an [environment variable]: + + ``` yaml + plugins: + - group: + enabled: !ENV CI + ``` + + Now, If you invoke MkDocs with that environment variable (or export the + environment variable before invoking MkDocs), the plugin will be enabled: + + ``` sh + CI=true mkdocs build + ``` + +[`plugins`](#+group.plugins){ #+group.plugins } + +: :octicons-milestone-24: Default: _none_ – This option specifies the plugins + that the group plugin should load when enabled. Note that the plugins must + be specified as a list, even if there's only one plugin: + + ``` yaml + plugins: + - group: + plugins: + - optimize + - minify + ``` + + The syntax is exactly the same as for all other plugins. + + [Group plugin support]: https://github.com/squidfunk/mkdocs-material/releases/tag/9.3.0 + [environment variable]: https://www.mkdocs.org/user-guide/configuration/#environment-variables diff --git a/docs/schema/plugins.json b/docs/schema/plugins.json index a99caecd3..e8e16dbeb 100644 --- a/docs/schema/plugins.json +++ b/docs/schema/plugins.json @@ -25,6 +25,9 @@ { "$ref": "plugins/blog.json" }, + { + "$ref": "plugins/group.json" + }, { "$ref": "plugins/info.json" }, diff --git a/docs/schema/plugins/group.json b/docs/schema/plugins/group.json new file mode 100644 index 000000000..99d75540d --- /dev/null +++ b/docs/schema/plugins/group.json @@ -0,0 +1,28 @@ +{ + "$schema": "https://json-schema.org/draft-07/schema", + "title": "Built-in group plugin", + "oneOf": [ + { + "type": "object", + "properties": { + "group": { + "markdownDescription": "https://squidfunk.github.io/mkdocs-material/insiders/getting-started/#built-in-group-plugin", + "type": "object", + "properties": { + "enabled": { + "title": "Enable plugin", + "markdownDescription": "https://squidfunk.github.io/mkdocs-material/insiders/getting-started/#+group.enabled", + "type": "boolean", + "default": true + }, + "plugins": { + "$ref": "../plugins.json" + } + }, + "additionalProperties": false + } + }, + "additionalProperties": false + } + ] +} diff --git a/material/base.html b/material/base.html index 2354baca1..59471addc 100644 --- a/material/base.html +++ b/material/base.html @@ -32,7 +32,7 @@ {% endif %} - + {% endblock %} {% block htmltitle %} {% if page.meta and page.meta.title %} diff --git a/package.json b/package.json index c128a206f..2102f564c 100644 --- a/package.json +++ b/package.json @@ -1,6 +1,6 @@ { "name": "mkdocs-material", - "version": "9.2.8", + "version": "9.3.0", "description": "Documentation that simply works", "keywords": [ "mkdocs", diff --git a/pyproject.toml b/pyproject.toml index dddc015f8..99a8691ee 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -37,7 +37,7 @@ dynamic = [ "keywords" ] readme = "README.md" -requires-python = ">=3.7" +requires-python = ">=3.8" classifiers = [ "Development Status :: 5 - Production/Stable", "Environment :: Web Environment",