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