diff --git a/CHANGELOG b/CHANGELOG
index a1df12da4..b73a683a1 100644
--- a/CHANGELOG
+++ b/CHANGELOG
@@ -1,3 +1,8 @@
+mkdocs-material-8.3.9+insiders-4.21.0 (2022-07-17)
+
+ * Added meta plugin: set front matter for all pages in a folder
+ * Fixed #4114: Tags plugin fails if only tags_extra_files is set
+
mkdocs-material-8.3.9+insiders-4.20.1 (2022-07-11)
* Fixed #4105: Tags plugin fails if tags_file is not set (4.20.0 regression)
diff --git a/docs/insiders/changelog.md b/docs/insiders/changelog.md
index d71e6875c..d200fd9c2 100644
--- a/docs/insiders/changelog.md
+++ b/docs/insiders/changelog.md
@@ -6,6 +6,11 @@ template: overrides/main.html
## Material for MkDocs Insiders
+### 4.21.0 _ July 17, 2022 { id="4.21.0" }
+
+- Added meta plugin: set front matter for all pages in a folder
+- Fixed #4114: Tags plugin fails if only `tags_extra_files` is set
+
### 4.20.1 _ July 11, 2022 { id="4.20.1" }
- Fixed #4105: Tags plugin fails if `tags_file` is not set (4.20.0 regression)
diff --git a/docs/insiders/index.md b/docs/insiders/index.md
index da18a96d2..a437314fd 100644
--- a/docs/insiders/index.md
+++ b/docs/insiders/index.md
@@ -82,14 +82,15 @@ a handful of them, [thanks to our awesome sponsors]!
## What's in for me?
The moment you [become a sponsor][how to become a sponsor], you'll get __immediate
-access to 26 additional features__ that you can start using right away, and
+access to 27 additional features__ that you can start using right away, and
which are currently exclusively available to sponsors:
+- [x] [Meta plugin] :material-alert-decagram:{ .mdx-pulse title="Added on July 17, 2022" }
- [x] [Additional tags indexes] :material-alert-decagram:{ .mdx-pulse title="Added on July 7, 2022" }
- [x] [Document contributors] :material-alert-decagram:{ .mdx-pulse title="Added on June 24, 2022" }
-- [x] [Automatic light / dark mode] :material-alert-decagram:{ .mdx-pulse title="Added on June 11, 2022" }
+- [x] [Automatic light / dark mode]
- [x] [Content tabs: anchor links]
- [x] [Navigation pruning]
- [x] [Tooltips]
@@ -304,10 +305,12 @@ are released for general availability.
#### $ 16,000 – Chipotle
+- [x] [Meta plugin]
- [x] [Additional tags indexes]
- [ ] [Instant previews]
- [ ] ... more to be announced
+ [Meta plugin]: ../reference/index.md#built-in-meta-plugin
[Additional tags indexes]: ../setup/setting-up-tags.md#tags-extra-files
[Instant previews]: https://twitter.com/squidfunk/status/1466794654213492743
diff --git a/docs/reference/index.md b/docs/reference/index.md
index 68a9cab7d..069d9e81d 100644
--- a/docs/reference/index.md
+++ b/docs/reference/index.md
@@ -27,6 +27,45 @@ See additional configuration options:
[front matter]: https://jekyllrb.com/docs/front-matter/
[Metadata]: ../setup/extensions/python-markdown.md#metadata
+### Built-in meta plugin :material-alert-decagram:{ .mdx-pulse title="Added on July 17, 2022" }
+
+[:octicons-heart-fill-24:{ .mdx-heart } Sponsors only][Insiders]{ .mdx-insiders } ·
+[:octicons-tag-24: insiders-4.21.0][Insiders] ·
+:octicons-cpu-24: Plugin ·
+:octicons-beaker-24: Experimental
+
+The built-in meta plugin allows to __set front matter per folder__, which is
+especially handy to ensure that all pages in a folder use specific templates or
+tags. Add the following lines to `mkdocs.yml`:
+
+``` yaml
+plugins:
+ - meta
+```
+
+> If you need to be able to build your documentation with and without
+> [Insiders], please refer to the [built-in plugins] section to learn how
+> shared configurations help to achieve this.
+
+The following configuration options are available:
+
+`meta_file`{ #meta-file }
+
+: :octicons-milestone-24: Default: `**/.meta.yml` – This option specifies the
+ name of the meta files that the plugin should look for. The default setting
+ assumes that meta files are called `.meta.yml`:
+
+ ``` yaml
+ plugins:
+ - meta:
+ meta_file: '**/.meta.yml' # (1)!
+ ```
+
+ 1. Note that it's strongly recommended to prefix meta files with a `.`,
+ since otherwise they would be included in the build output.
+
+ [built-in plugins]: ../insiders/getting-started.md#built-in-plugins
+
## Usage
### Setting the page title
@@ -117,7 +156,18 @@ template: custom.html
...
```
+??? question "How to set a page template for an entire folder?"
+
+ With the help of the [built-in meta plugin], you can set a custom template
+ for an entire section and all nested pages, by creating a `.meta.yml`
+ in the corresponding folder with the following content:
+
+ ``` yaml
+ template: custom.html
+ ```
+
[theme extension]: ../customization.md#extending-the-theme
+ [built-in meta plugin]: #built-in-meta-plugin
## Customization
diff --git a/docs/setup/changing-the-colors.md b/docs/setup/changing-the-colors.md
index 3fbaec7d8..bf503e530 100644
--- a/docs/setup/changing-the-colors.md
+++ b/docs/setup/changing-the-colors.md
@@ -268,7 +268,7 @@ default color palette.
[palette.media support]: https://github.com/squidfunk/mkdocs-material/releases/tag/7.1.0
-#### Automatic light / dark mode :material-alert-decagram:{ .mdx-pulse title="Added on June 11, 2022" }
+#### Automatic light / dark mode
[:octicons-heart-fill-24:{ .mdx-heart } Sponsors only][Insiders]{ .mdx-insiders } ·
[:octicons-tag-24: insiders-4.18.0][Insiders] ·
@@ -291,7 +291,7 @@ theme:
# Palette toggle for light mode
- media: "(prefers-color-scheme: light)"
- scheme: default #(1)!
+ scheme: default # (1)!
toggle:
icon: material/brightness-7
name: Switch to dark mode
diff --git a/docs/setup/setting-up-tags.md b/docs/setup/setting-up-tags.md
index 7df1c35a7..1efeb1fef 100644
--- a/docs/setup/setting-up-tags.md
+++ b/docs/setup/setting-up-tags.md
@@ -60,7 +60,7 @@ The following configuration options are available:
- tags:
tags_extra_files:
compatibility.md:
- - compat #(1)!
+ - compat # (1)!
web.md:
- html
- js
@@ -185,28 +185,30 @@ tags:
- HTML5
- JavaScript
- CSS
- - Other
---
...
```
The page will now render with those tags above the main headline and within the
-search preview, which now allows to __find pages by tags__, as shown in the
-following screenshots:
+search preview, which now allows to __find pages by tags__.
-=== "Tags"
+??? question "How to set tags for an entire folder?"
- [![Tags preview]][Tags preview]
+ With the help of the [built-in meta plugin], you can ensure that tags are
+ set for an entire section and all nested pages, by creating a `.meta.yml`
+ in the corresponding folder with the following content:
-=== "Tag search"
-
- [![Tag search preview]][Tag search preview]
+ ``` yaml
+ tags:
+ - HTML5
+ - JavaScript
+ - CSS
+ ```
[built-in tags plugin]: #built-in-tags-plugin
[Metadata]: extensions/python-markdown.md#metadata
- [Tags preview]: ../assets/screenshots/tags.png
- [Tag search preview]: ../assets/screenshots/tags-search.png
+ [built-in meta plugin]: ../reference/index.md#built-in-meta-plugin
### Adding a tags index