1
0
mirror of https://github.com/squidfunk/mkdocs-material.git synced 2024-11-12 01:50:52 +01:00

Prepare 9.3.0 release

This commit is contained in:
squidfunk 2023-09-11 17:18:58 +02:00
parent 2e85464401
commit 3a352743e5
No known key found for this signature in database
GPG Key ID: 5ED40BC4F9C436DF
8 changed files with 118 additions and 61 deletions

View File

@ -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

View File

@ -2,6 +2,13 @@
## Material for MkDocs
### 9.3.0 <small>September 11, 2023</small> { 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 <small>September 4, 2023</small> { id="9.2.8" }
- Updated Italian and Russian translations

View File

@ -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

View File

@ -25,6 +25,9 @@
{
"$ref": "plugins/blog.json"
},
{
"$ref": "plugins/group.json"
},
{
"$ref": "plugins/info.json"
},

View File

@ -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
}
]
}

View File

@ -32,7 +32,7 @@
<link rel="alternate" type="application/rss+xml" title="{{ lang.t('rss.updated') }}" href="{{ 'feed_rss_updated.xml' | url }}">
{% endif %}
<link rel="icon" href="{{ config.theme.favicon | url }}">
<meta name="generator" content="mkdocs-{{ mkdocs_version }}, mkdocs-material-9.2.8">
<meta name="generator" content="mkdocs-{{ mkdocs_version }}, mkdocs-material-9.3.0">
{% endblock %}
{% block htmltitle %}
{% if page.meta and page.meta.title %}

View File

@ -1,6 +1,6 @@
{
"name": "mkdocs-material",
"version": "9.2.8",
"version": "9.3.0",
"description": "Documentation that simply works",
"keywords": [
"mkdocs",

View File

@ -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",