Documentation

docs/insiders/index.md

@@ -82,15 +82,17 @@ 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 22 additional features__ that you can start using right away, and
+access to 24 additional features__ that you can start using right away, and
 which are currently exclusively available to sponsors:
 
 <div class="mdx-columns" markdown>
 
+- [x] [Navigation subtitles] :material-alert-decagram:{ .mdx-pulse title="Added on October 2, 2022" }
+- [x] [Tags plugin: allow list] :material-alert-decagram:{ .mdx-pulse title="Added on October 2, 2022" }
 - [x] [Blog plugin: custom index pages] :material-alert-decagram:{ .mdx-pulse title="Added on September 27, 2022" }
-- [x] [Blog plugin: related links] :material-alert-decagram:{ .mdx-pulse title="Added on September 12, 2022" }
+- [x] [Blog plugin: related links]
-- [x] [Blog plugin] :material-alert-decagram:{ .mdx-pulse title="Added on September 12, 2022" }
+- [x] [Blog plugin]
-- [x] [Navigation status] :material-alert-decagram:{ .mdx-pulse title="Added on August 21, 2022" }
+- [x] [Navigation status]
 - [x] [Meta plugin]
 - [x] [Tags plugin: additional indexes]
 - [x] [Document contributors]
@@ -293,14 +295,22 @@ are released for general availability.
 - [x] [Blog plugin: related links]
 - [x] [Blog plugin: custom index pages]
 - [x] [Tags plugin: additional indexes]
-- [ ] [Instant previews]
+- [x] [Tags plugin: allow list]
-- [ ] Navigation subtitles
+- [x] [Navigation subtitles]
 
   [Meta plugin]: ../reference/index.md#built-in-meta-plugin
-  [Tags plugin: additional indexes]: ../setup/setting-up-tags.md#+tags.tags_extra_files
-  [Instant previews]: https://twitter.com/squidfunk/status/1466794654213492743
   [Blog plugin: related links]: ../setup/setting-up-a-blog.md#adding-related-links
   [Blog plugin: custom index pages]: ../setup/setting-up-a-blog.md#custom-index-pages
+  [Tags plugin: additional indexes]: ../setup/setting-up-tags.md#+tags.tags_extra_files
+  [Tags plugin: allow list]: ../setup/setting-up-tags.md#+tags.tags_allowed
+  [Navigation subtitles]: ../reference/index.md#setting-the-page-subtitle
+
+#### $ 20,000 – Jalapeño
+
+- [ ] [Instant previews]
+- ... more to be announced
+
+  [Instant previews]: https://twitter.com/squidfunk/status/1466794654213492743
 
 ### Goals completed
 

docs/reference/index.md

@@ -5,7 +5,7 @@ template: overrides/main.html
 # Reference
 
 Material for MkDocs is packed with many great features that make technical
-writing a pleasure. This section of the documentation explains how to set up
+writing a joyful activity. This section of the documentation explains how to set up
 a page, and showcases all available specimen that can be used directly from
 within Markdown files.
 
@@ -55,8 +55,10 @@ The following configuration options are available:
 
 ### Setting the page title
 
-The page title can be overridden for a document with the front matter `title`
+Each page has a designated title, which is used in the navigation sidebar, for 
-property. Add the following lines at the top of a Markdown file:
+[social cards] and in other places. While MkDocs attempts to automatically 
+determine the title of a page in a [four step process], the title can also be 
+explicitly set with the front matter `title` property:
 
 ``` yaml
 ---
@@ -67,18 +69,23 @@ title: Lorem ipsum dolor sit amet # (1)!
 ...
 ```
 
-1.  This will set the [`title`][title] inside the HTML document's [`head`][head]
+1.  This line sets the [`title`][title] inside the HTML document's
-    for the generated page to this value. Note that the site title, which is set
+    [`head`][head] for the generated page to the given value. Note that the
-    via [`site_name`][site_name], is appended with a dash.
+    site title, which is set via [`site_name`][site_name], is appended with a
+    dash.
 
+  [social cards]: ../setup/setting-up-social-cards.md
+  [four step process]: https://www.mkdocs.org/user-guide/writing-your-docs/#meta-data
   [title]: https://developer.mozilla.org/en-US/docs/Web/HTML/Element/title
   [head]: https://developer.mozilla.org/en-US/docs/Web/HTML/Element/head
   [site_name]: https://www.mkdocs.org/user-guide/configuration/#site_name
 
 ### Setting the page description
 
-The page description can be overridden for a document with the front matter
+A Markdown file can include a description that is added to the `meta` tags of
-`description` property. Add the following lines at the top of a Markdown file:
+a page, and is also used for [social cards]. It's a good idea to set a 
+[`site_description`][site_description] in `mkdocs.yml` as a fallback value if
+the author does not explicitly define a description for a Markdown file:
 
 ``` yaml
 ---
@@ -89,9 +96,11 @@ description: Nullam urna elit, malesuada eget finibus ut, ac tortor. # (1)!
 ...
 ```
 
-1.  This will set the `meta` tag containing the site description inside the
+1.  This line sets the `meta` tag containing the description inside the
     document `head` for the current page to the provided value.
 
+  [site_description]: https://www.mkdocs.org/user-guide/configuration/#site_description
+
 ### Setting the page icon
 
 [:octicons-heart-fill-24:{ .mdx-heart } Sponsors only][Insiders]{ .mdx-insiders } ·
@@ -99,7 +108,9 @@ description: Nullam urna elit, malesuada eget finibus ut, ac tortor. # (1)!
 :octicons-beaker-24: Experimental
 
 An icon can be assigned to each page, which is then rendered as part of the
-navigation sidebar. Add the following lines at the top of a Markdown file:
+navigation sidebar, as well as [navigation tabs], if enabled. Use the front
+matter `icon` property to reference an icon, adding the following lines at the
+top of a Markdown file:
 
 ``` yaml
 ---
@@ -123,6 +134,7 @@ icon: material/emoticon-happy # (1)!
 
   [Insiders]: ../insiders/index.md
   [icon search]: icons-emojis.md#search
+  [navigation tabs]: ../setup/setting-up-navigation.md#navigation-tabs
 
 ### Setting the page status
 
@@ -150,9 +162,9 @@ extra:
         new: Recently added
     ```
 
-The page status can now be set for a document with the front matter `status`
+The page status can now be set with the front matter `status` property. For
-property. For example, you can mark a page as `new` with the following lines at 
+example, you can mark a page as `new` with the following lines at the top of a 
-the top of a Markdown file:
+Markdown file:
 
 ``` yaml
 ---
@@ -168,6 +180,25 @@ The following status identifiers are currently supported:
 - :material-alert-decagram: – `new`
 - :material-trash-can: – `deprecated`
 
+### Setting the page subtitle
+
+[:octicons-heart-fill-24:{ .mdx-heart } Sponsors only][Insiders]{ .mdx-insiders } ·
+[:octicons-tag-24: insiders-4.25.0][Insiders] ·
+:octicons-beaker-24: Experimental
+
+Each page can define a subtitle, which is then rendered below the title as part
+of the navigation sidebar by using the front matter `subtitle` property, and
+adding the following lines:
+
+``` yaml
+---
+subtitle: Nullam urna elit, malesuada eget finibus ut, ac tortor
+---
+
+# Document title
+...
+```
+
 ### Setting the page template
 
 If you're using [theme extension] and created a new page template in the

docs/schema/extensions/markdown.json

@@ -118,7 +118,7 @@
         },
         "slugify": {
           "markdownDescription": "https://squidfunk.github.io/mkdocs-material/setup/extensions/python-markdown/#+toc.slugify",
-          "type": "string"
+          "default": "!!python/object/apply:pymdownx.slugs.slugify {kwds: {case: lower}}"
         },
         "toc_depth": {
           "markdownDescription": "https://squidfunk.github.io/mkdocs-material/setup/extensions/python-markdown/#+toc.toc_depth",

docs/schema/extensions/pymdownx.json

@@ -159,12 +159,10 @@
           "properties": {
             "emoji_generator": {
               "markdownDescription": "https://squidfunk.github.io/mkdocs-material/setup/extensions/python-markdown-extensions/#+pymdownx.emoji.emoji_generator",
-              "type": "string",
               "default": "!!python/name:materialx.emoji.to_svg"
             },
             "emoji_index": {
               "markdownDescription": "https://squidfunk.github.io/mkdocs-material/setup/extensions/python-markdown-extensions/#+pymdownx.emoji.emoji_index",
-              "type": "string",
               "default": "!!python/name:materialx.emoji.twemoji"
             },
             "options": {

docs/schema/plugins/blog.json

@@ -85,8 +85,7 @@
             "post_slugify": {
               "title": "Post slugify function",
               "markdownDescription": "https://squidfunk.github.io/mkdocs-material/setup/setting-up-a-blog/#+blog.post_slugify",
-              "type": "string",
+              "default": "!!python/object/apply:pymdownx.slugs.slugify {kwds: {case: lower}}"
-              "default": "!!python/name:pymdownx.slugs.uslugify"
             },
             "post_slugify_separator": {
               "title": "Post slugify separator",
@@ -231,8 +230,7 @@
             "categories_slugify": {
               "title": "Categories slugify function",
               "markdownDescription": "https://squidfunk.github.io/mkdocs-material/setup/setting-up-a-blog/#+blog.categories_slugify",
-              "type": "string",
+              "default": "!!python/object/apply:pymdownx.slugs.slugify {kwds: {case: lower}}"
-              "default": "!!python/name:pymdownx.slugs.uslugify"
             },
             "categories_slugify_separator": {
               "title": "Categories slugify separator",

docs/schema/plugins/tags.json

@@ -15,6 +15,12 @@
           "markdownDescription": "https://squidfunk.github.io/mkdocs-material/setup/setting-up-tags/#built-in-tags-plugin",
           "type": "object",
           "properties": {
+            "enabled": {
+              "title": "Enable plugin",
+              "markdownDescription": "https://squidfunk.github.io/mkdocs-material/setup/setting-up-tags/#+tags.enabled",
+              "type": "boolean",
+              "default": true
+            },
             "tags_file": {
               "title": "Markdown file to render tags index",
               "markdownDescription": "https://squidfunk.github.io/mkdocs-material/setup/setting-up-tags/#+tags.tags_file",
@@ -34,6 +40,26 @@
                 }
               },
               "additionalProperties": false
+            },
+            "tags_slugify": {
+              "title": "Tags slugify function",
+              "markdownDescription": "https://squidfunk.github.io/mkdocs-material/setup/setting-up-tags/#+tags.tags_slugify",
+              "default": "!!python/object/apply:pymdownx.slugs.slugify {kwds: {case: lower}}"
+            },
+            "tags_slugify_separator": {
+              "title": "Tags slugify separator",
+              "markdownDescription": "https://squidfunk.github.io/mkdocs-material/setup/setting-up-tags/#+tags.tags_slugify_separator",
+              "type": "string",
+              "default": "\"-\""
+            },
+            "tags_allowed": {
+              "title": "Tags allowed",
+              "markdownDescription": "https://squidfunk.github.io/mkdocs-material/setup/setting-up-tags/#+tags.tags_allowed",
+              "type": "array",
+              "items": {
+                "type": "string"
+              },
+              "default": []
             }
           },
           "additionalProperties": false

docs/setup/adding-a-comment-system.md

@@ -42,14 +42,14 @@ Before you can use [Giscus], you need to complete the following steps:
     </script>
     ```
 
-The by default empty [`comments.html`][comments] partial is the best place to
+The [`comments.html`][comments] partial (empty by default) is the best place to
-add the code snippet generated by [Giscus]. Follow the guide on [theme extension]
+add the snippet generated by [Giscus]. Follow the guide on [theme extension]
 and [override the `comments.html` partial][overriding partials] with:
 
 ``` html hl_lines="3"
 {% if page.meta.comments %}
   <h2 id="__comments">{{ lang.t("meta.comments") }}</h2>
-  <!-- Insert generated code here -->
+  <!-- Insert generated snippet here -->
 
   <!-- Synchronize Giscus theme with palette -->
   <script>

docs/setup/adding-a-git-repository.md

@@ -311,7 +311,7 @@ them at your own risk.
   [environment variable]: https://www.mkdocs.org/user-guide/configuration/#environment-variables
   [rate limits]: https://docs.github.com/en/rest/overview/resources-in-the-rest-api#rate-limiting
 
-#### Document authors :material-alert-decagram:{ .mdx-pulse title="Added on June 24, 2022" }
+#### Document authors
 
 [:octicons-heart-fill-24:{ .mdx-heart } Sponsors only][Insiders]{ .mdx-insiders } ·
 [:octicons-tag-24: insiders-4.19.0][Insiders] ·

docs/setup/extensions/python-markdown.md

@@ -258,7 +258,9 @@ The following configuration options are supported:
         ``` yaml
         markdown_extensions:
           - toc:
-              slugify: !!python/object/apply:pymdownx.slugs.slugify {kwds: {case: lower}}
+              slugify: !!python/object/apply:pymdownx.slugs.slugify
+                kwds:
+                  case: lower
         ```
 
     === "Unicode, case-sensitive"

docs/setup/setting-up-a-blog.md

@@ -22,7 +22,7 @@ __Check out our [blog], which is created with the new [built-in blog plugin]!__
 
 ## Configuration
 
-### Built-in blog plugin :material-alert-decagram:{ .mdx-pulse title="Added on September 12, 2022" }
+### Built-in blog plugin
 
 [:octicons-heart-fill-24:{ .mdx-heart } Sponsors only][Insiders]{ .mdx-insiders } ·
 [:octicons-tag-24: insiders-4.23.0][Insiders] ·
@@ -248,7 +248,9 @@ The following configuration options are available for posts:
         ``` yaml
         plugins:
           - blog:
-              post_slugify: !!python/name:pymdownx.slugs.uslugify
+              post_slugify: !!python/object/apply:pymdownx.slugs.slugify
+                kwds:
+                  case: lower
         ```
 
     === "Unicode, case-sensitive"
@@ -256,7 +258,7 @@ The following configuration options are available for posts:
         ``` yaml
         plugins:
           - blog:
-              post_slugify: !!python/name:pymdownx.slugs.uslugify_cased
+              post_slugify: !!python/object/apply:pymdownx.slugs.slugify
         ```
 
 [`post_slugify_separator`](#+blog.post_slugify_separator){ #+blog.post_slugify_separator }
@@ -542,7 +544,9 @@ The following configuration options are available for category index generation:
         ``` yaml
         plugins:
           - blog:
-              categories_slugify: !!python/name:pymdownx.slugs.uslugify
+              categories_slugify: !!python/object/apply:pymdownx.slugs.slugify 
+                kwds:
+                  case: lower
         ```
 
     === "Unicode, case-sensitive"
@@ -550,7 +554,7 @@ The following configuration options are available for category index generation:
         ``` yaml
         plugins:
           - blog:
-              categories_slugify: !!python/name:pymdownx.slugs.uslugify_cased
+              categories_slugify: !!python/object/apply:pymdownx.slugs.slugify
         ```
 
 [`categories_slugify_separator`](#+blog.categories_slugify_separator){ #+blog.categories_slugify_separator }
@@ -1028,7 +1032,7 @@ authors:
 Categories are an excellent way for grouping your posts thematically on
 dedicated index pages. This way, a user interested in a specific topic can
 explore all of your posts on this topic. Make sure [categories] are enabled and
-add them to the `categories` front matter property:
+add them to the front matter `categories` property:
 
 ``` yaml
 ---
@@ -1053,7 +1057,7 @@ the list.
 #### Adding tags
 
 Besides [categories], the [built-in blog plugin] also integrates with the
-[built-in tags plugin]. If you add tags in the `tags` front matter property as
+[built-in tags plugin]. If you add tags in the front matter `tags` property as
 part of a post, the post is linked from the [tags index]:
 
 ``` yaml
@@ -1079,7 +1083,7 @@ linked with their titles.
 
 Related links offer the perfect way to prominently add a _further reading_ 
 section to your post that is included in the left sidebar, guiding the user to 
-other destinations of your documentation. Use the `links` front matter property 
+other destinations of your documentation. Use the front matter `links` property 
 to add related links to a post:
 
 ``` yaml
@@ -1153,7 +1157,7 @@ offers this capability as well.
 
 Sometimes, however, the computed reading time might not feel accurate, or
 result in odd and unpleasant numbers. For this reason, reading time can be 
-overridden and explicitly set with the `readtime` front matter property for a
+overridden and explicitly set with the front matter `readtime` property for a
 post:
 
 ``` yaml
@@ -1189,8 +1193,8 @@ authors, and add a `.meta.yml` file to set common properties:
 ```
 
 1.  As already noted, you can also place a `.meta.yml` file in nested folders
-    of the `posts` directory. This file then can contain any front matter that
+    of the `posts` directory. This file then can define all front matter
-    is also valid in posts, e.g.:
+    properties that are valid in posts, e.g.:
 
     ``` yaml
     authors:
@@ -1267,8 +1271,7 @@ the [built-in blog plugin] would create it:
     - [`categories_slugify`][categories_slugify]
 
 You can now add arbitrary content to the newly created file, or set specific
-page properties for this page via front matter, e.g. to change the
+front matter properties for this page, e.g. to change the [page description]:
-[page description]:
 
 ``` yaml
 ---
@@ -1279,7 +1282,7 @@ description: Nullam urna elit, malesuada eget finibus ut, ac tortor.
 ...
 ```
 
-All posts belonging to the category will be automatically appended.
+All post excerpts belonging to the category are automatically appended.
 
   [add the category]: #adding-categories
   [page description]: ../reference/index.md#setting-the-page-description

docs/setup/setting-up-site-analytics.md

@@ -233,7 +233,8 @@ The following properties are available for each rating:
 
 ### Hiding the feedback widget
 
-The [feedback widget] can be hidden for a document with the front matter `hide` property. Add the following lines at the top of a Markdown file:
+The [feedback widget] can be hidden for a document with the front matter `hide`
+property. Add the following lines at the top of a Markdown file:
 
 ``` yaml
 ---

docs/setup/setting-up-tags.md

@@ -30,13 +30,24 @@ plugins:
 
 The following configuration options are available:
 
+[`enabled`](#+tags.enabled){ #+tags.enabled }
+
+:   :octicons-milestone-24: Default: `true` – This option specifies whether
+    the plugin is enabled when building your project. If you want to switch
+    the plugin off, you can disable it with the following lines:
+
+    ``` yaml
+    plugins:
+      - tags:
+          enabled: false
+    ```
+
 [`tags_file`](#+tags.tags_file){ #+tags.tags_file }
 
 :   :octicons-milestone-24: Default: _none_ – This option specifies which page
     should be used to render the tags index. See the section on [adding a tags 
     index][tags index] for more information. If this option is specified, tags
-    will become clickable, pointing to the corresponding section in the tags
+    become clickable, pointing to the corresponding section in the tags index:
-    index:
 
     ``` yaml
     plugins:
@@ -51,7 +62,7 @@ The following configuration options are available:
 [`tags_extra_files`](#+tags.tags_extra_files){ #+tags.tags_extra_files }
 
 :   [:octicons-tag-24: insiders-4.20.0][Insiders] · :octicons-milestone-24: 
-    Default: _none_ – This option allows to define additional pages to render
+    Default: _none_ – This option specifies additional pages, i.e. to render
     subsets of the [tags index], in order to provide scoped tags indexes for 
     specific sections:
 
@@ -84,11 +95,67 @@ The following configuration options are available:
         at least one of the tags `HTML5`, `JavaScript` or `CSS` will be included
         in the additional tags index on `web.md`.
 
-    See #3864 for additional use cases.
+    See #3864 for more information.
+
+[`tags_slugify`](#+tags.tags_slugify){ #+tags.tags_slugify }
+
+:   [:octicons-tag-24: insiders-4.25.0][Insiders] · :octicons-milestone-24: 
+    Default: `headerid.slugify` – This option specifies which function to use for 
+    generating URL-compatible slugs from tags. [Python Markdown Extensions] 
+    includes several Unicode-aware slug functions which are a good choice for 
+    non-ASCII languages:
+
+    === "Unicode"
+
+        ``` yaml
+        plugins:
+          - tags:
+              tags_slugify: !!python/object/apply:pymdownx.slugs.slugify
+                kwds:
+                  case: lower
+        ```
+
+    === "Unicode, case-sensitive"
+
+        ``` yaml
+        plugins:
+          - tags:
+              tags_slugify: !!python/object/apply:pymdownx.slugs.slugify
+        ```
+
+[`tags_slugify_separator`](#+tags.tags_slugify_separator){ #+tags.tags_slugify_separator }
+
+:   [:octicons-tag-24: insiders-4.25.0][Insiders] · :octicons-milestone-24: 
+    Default: `-` – This option specifies the separator which is used by the slug function. By default, a hyphen is used, but it can
+    be changed to any string:
+
+    ``` yaml
+    plugins:
+      - tags:
+          tags_slugify_separator: "-"
+    ```
+
+[`tags_allowed`](#+tags.tags_allowed){ #+tags.tags_allowed } :material-alert-decagram:{ .mdx-pulse title="Added on October 2, 2022" }
+
+:   [:octicons-tag-24: insiders-4.25.0][Insiders] · :octicons-milestone-24: 
+    Default: _none_ – This option allows the author to define explicitly which
+    tags are allowed to be used on pages. If this setting is omitted, the
+    [built-in tags plugin] won't check tag names. Use this option to define a
+    list of tags in order to catch typos:
+
+    ``` yaml
+    plugins:
+      - tags:
+          tags_allowed:
+            - HTML5
+            - JavaScript
+            - CSS
+    ```
 
   [Tags support]: https://github.com/squidfunk/mkdocs-material/releases/tag/8.2.0
   [Insiders]: ../insiders/index.md
   [tag identifiers]: #tag-icons
+  [Python Markdown Extensions]: https://facelessuser.github.io/pymdown-extensions/extras/slugs/
 
 ### Tag icons