Documentation

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"

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
-    is also valid in posts, e.g.:
+    of the `posts` directory. This file then can define all front matter
+    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
-[page description]:
+front matter properties for this page, e.g. to change the [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
-    index:
+    become clickable, pointing to the corresponding section in the tags index:
 
     ``` yaml
     plugins:
@@ -51,8 +62,8 @@ 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
-    subsets of the [tags index], in order to provide scoped tags indexes for
+    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:
 
     ``` yaml
@@ -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