Updated Insiders changelog and documentation

Author: squidfunk

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)

docs/insiders/changelog.md

@@ -6,6 +6,11 @@ template: overrides/main.html
 
 ## Material for MkDocs Insiders
 
+### 4.21.0 <small>_ July 17, 2022</small> { 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 <small>_ July 11, 2022</small> { id="4.20.1" }
 
 - Fixed #4105: Tags plugin fails if `tags_file` is not set (4.20.0 regression)

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:
 
 <div class="mdx-columns" markdown>
 
+- [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
 

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
 

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

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