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] :material-alert-decagram:{ .mdx-pulse title="Added on September 12, 2022" }
-- [x] [Navigation status] :material-alert-decagram:{ .mdx-pulse title="Added on August 21, 2022" }
+- [x] [Blog plugin: related links]
+- [x] [Blog plugin]
+- [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]
-- [ ] Navigation subtitles
+- [x] [Tags plugin: allow list]
+- [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`
-property. Add the following lines at the top of a Markdown file:
+Each page has a designated title, which is used in the navigation sidebar, for 
+[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]
-    for the generated page to this value. Note that the site title, which is set
-    via [`site_name`][site_name], is appended with a dash.
+1.  This line sets the [`title`][title] inside the HTML document's
+    [`head`][head] for the generated page to the given value. Note that the
+    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
-`description` property. Add the following lines at the top of a Markdown file:
+A Markdown file can include a description that is added to the `meta` tags of
+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,17 +96,21 @@ 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 } ·
 [:octicons-tag-24: insiders-4.5.0][Insiders] ·
 :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`
-property. For example, you can mark a page as `new` with the following lines at 
-the top of a Markdown file:
+The page status can now be set with the front matter `status` property. For
+example, you can mark a page as `new` with the following lines at the top of a 
+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/name:pymdownx.slugs.uslugify"
+              "default": "!!python/object/apply:pymdownx.slugs.slugify {kwds: {case: lower}}"
             },
             "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/name:pymdownx.slugs.uslugify"
+              "default": "!!python/object/apply:pymdownx.slugs.slugify {kwds: {case: lower}}"
             },
             "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
-add the code snippet generated by [Giscus]. Follow the guide on [theme extension]
+The [`comments.html`][comments] partial (empty by default) is the best place to
+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"