Restructured documentation (#5692)

.editorconfig

@@ -30,10 +30,6 @@ end_of_line = lf
 insert_final_newline = true
 trim_trailing_whitespace = true
 
-# Markdown
-[*.md]
-trim_trailing_whitespace = false
-
 # Python
 [*.py]
 indent_style = space

Dockerfile

@@ -60,11 +60,8 @@ RUN \
   pip install --no-cache-dir . \
 && \
   if [ "${WITH_PLUGINS}" = "true" ]; then \
-    pip install --no-cache-dir \
+    pip install --no-cache-dir mkdocs-material[recommended] \
-      "mkdocs-minify-plugin~=0.7" \
+    pip install --no-cache-dir mkdocs-material[imaging]; \
-      "mkdocs-redirects~=1.2" \
-      "pillow~=9.4" \
-      "cairosvg~=2.6"; \
   fi \
 && \
   if [ -e user-requirements.txt ]; then \

docs/blog/posts/blog-support-just-landed.md

@@ -168,9 +168,9 @@ In velit purus, dictum quis neque nec, molestie viverra risus. Nam pellentesque
 tellus id elit ultricies, vel finibus erat cursus.
 ```
 
-1.  If you mark a post as a [draft], a red marker appears next to the post date 
+1.  If you mark a post as a [draft], a red marker appears next to the post date
-    on index pages. When the site is built, drafts are not included in the 
+    on index pages. When the site is built, drafts are not included in the
-    output. [This behavior can be changed], e.g. for rendering drafts when 
+    output. [This behavior can be changed], e.g. for rendering drafts when
     building deploy previews.
 
 When you spin up the [live preview server], you should be greeted by your first
@@ -233,7 +233,7 @@ Some ideas already proposed by users:
   part of a series, a list with links to all other posts should be included in
   the post's content.
 
-- __Author indexes__: Besides [archive] and [category] indexes, authors should 
+- __Author indexes__: Besides [archive] and [category] indexes, authors should
   be able to create per-author indexes, which list all posts linked to an
   author. Additionally, a profile should be created for each author and linked
   from posts.

docs/blog/posts/chinese-search-support.md

@@ -3,25 +3,25 @@ date: 2022-05-05
 authors: [squidfunk]
 title: Chinese search support
 description: >
-  Insiders adds Chinese language support for the built-in search plugin – a 
+  Insiders adds Chinese language support for the built-in search plugin – a
   feature that has been requested many times
 categories:
   - Search
 links:
   - blog/posts/search-better-faster-smaller.md
-  - setup/setting-up-site-search.md#chinese-language-support
+  - plugins/search.md#segmentation
   - insiders/index.md#how-to-become-a-sponsor
 ---
 
 # Chinese search support – 中文搜索​支持
 
-__Insiders adds experimental Chinese language support for the [built-in search 
+__Insiders adds experimental Chinese language support for the [built-in search
 plugin] – a feature that has been requested for a long time given the large
 number of Chinese users.__
 
 After the United States and Germany, the third-largest country of origin of
 Material for MkDocs users is China. For a long time, the [built-in search plugin]
-didn't allow for proper segmentation of Chinese characters, mainly due to 
+didn't allow for proper segmentation of Chinese characters, mainly due to
 missing support in [lunr-languages] which is used for search tokenization and
 stemming. The latest Insiders release adds long-awaited Chinese language support
 for the built-in search plugin, something that has been requested by many users.
@@ -49,8 +49,8 @@ through the segmenter. You can install [jieba] with:
 pip install jieba
 ```
 
-The next step is only required if you specified the [`separator`][separator] 
+The next step is only required if you specified the [`separator`][separator]
-configuration in `mkdocs.yml`. Text is segmented with [zero-width whitespace] 
+configuration in `mkdocs.yml`. Text is segmented with [zero-width whitespace]
 characters, so it renders exactly the same in the search modal. Adjust
 `mkdocs.yml` so that the [`separator`][separator] includes the `\u200b`
 character:
@@ -65,14 +65,14 @@ That's all that is necessary.
 
 ## Usage
 
-If you followed the instructions in the configuration guide, Chinese words will 
+If you followed the instructions in the configuration guide, Chinese words will
 now be tokenized using [jieba]. Try searching for
-[:octicons-search-24: 支持][q=支持] to see how it integrates with the 
+[:octicons-search-24: 支持][q=支持] to see how it integrates with the
 built-in search plugin.
 
 ---
 
-Note that this is an experimental feature, and I, @squidfunk, am not 
+Note that this is an experimental feature, and I, @squidfunk, am not
 proficient in Chinese (yet?). If you find a bug or think something can be
 improved, please [open an issue].
 

docs/blog/posts/excluding-content-from-search.md

@@ -119,7 +119,7 @@ search:
   exclude: true
 ---
 
-# Document title
+# Page title
 ...
 ```
 
@@ -133,7 +133,7 @@ filtered by the search plugin before the page is rendered:
 === ":octicons-file-code-16: `docs/page.md`"
 
     ``` markdown
-    # Document title
+    # Page title
 
     ## Section 1
 
@@ -173,7 +173,7 @@ supported by the [Attribute Lists] extension:
 === ":octicons-file-code-16: `docs/page.md`"
 
     ``` markdown
-    # Document title
+    # Page title
 
     The content of this block is included
 

docs/blog/posts/search-better-faster-smaller.md

@@ -176,10 +176,10 @@ which creates and manages the [lunr] search index. When search is initialized,
 the following steps are taken:
 
   [^1]:
-    Prior to :octicons-tag-24: 5.0.0, search was carried out in the main thread 
+    Prior to <!-- md:version 5.0.0 -->, search was carried out in the main
-    which locked up the browser, rendering it unusable. This problem was first
+    thread  which locked up the browser, rendering it unusable. This problem was
-    reported in #904 and, after some back and forth, fixed and released in
+    first reported in #904 and, after some back and forth, fixed and released in
-    :octicons-tag-24: 5.0.0.
+    <!-- md:version 5.0.0 -->.
 
 1.  __Linking sections with pages__: The search index is parsed, and each
     section is linked to its parent page. The parent page itself is _not
@@ -196,7 +196,7 @@ the following steps are taken:
     > can achieve with a tokenizer that is capable of separating strings with
     > lookahead.
 
-1.  __Indexing__: As a final step, each section is indexed. When querying the
+3.  __Indexing__: As a final step, each section is indexed. When querying the
     index, if a search query includes one of the tokens as returned by step 2.,
     the section is considered to be part of the search result and passed to the
     main thread.

docs/browser-support.md

@@ -64,6 +64,4 @@ the following older browser versions might work with some additional effort:
 - :fontawesome-brands-internet-explorer: __Internet Explorer__ - no support,
   mainly due to missing support for [custom properties]. The last version of
   Material for MkDocs to support Internet Explorer is
-  [:octicons-tag-24: 4.6.3][IE support].
+  <!-- md:version 4.6.3 -->.
-
-  [IE support]: https://github.com/squidfunk/mkdocs-material/releases/tag/4.6.3

docs/contributing/reporting-a-bug.md

@@ -148,7 +148,7 @@ summary of the issue, so the impact and severity of the bug you want to report
 can be inferred from the title.
 
 | <!-- --> | Example  |
-| -------- | -------- | 
+| -------- | -------- |
 | :material-check:{ style="color: #4DB6AC" } __Clear__ | Built-in `typeset` plugin changes precedence of nav title over `h1`
 | :material-close:{ style="color: #EF5350" } __Wordy__ | The built-in `typeset` plugin changes the precedence of the nav title over the document headline
 | :material-close:{ style="color: #EF5350" } __Unclear__ | Title does not work
@@ -235,17 +235,17 @@ make it easier for us maintainers to improve the documentation.
 ### Reproduction
 
 A minimal reproduction is at the heart of every well-written bug report, as
-it allows us maintainers to quickly recreate the necessary conditions to inspect
+it allows us maintainers to instantly recreate the necessary conditions to
-the bug and quickly find its root cause. It's a proven fact that issues with
+inspect the bug to quickly find its root cause. It's a proven fact that issues
-concise and small reproductions can be fixed much faster.
+with concise and small reproductions can be fixed much faster.
 
 [:material-bug:&nbsp; Create a reproduction][Create reproduction]{ .md-button .md-button--primary }
 
 ---
 
-After you have created the reproduction, you should have a .zip file, ideally not
+After you have created the reproduction, you should have a `.zip` file, ideally
-larger than 1 MB. Just drag and drop the .zip file into this field, which will
+not larger than 1 MB. Just drag and drop the `.zip` file into this field, which
-automatically upload it to GitHub.
+will automatically upload it to GitHub.
 
 > __Why we need this__: if an issue contains no minimal reproduction or just
 > a link to a repository with thousands of files, the maintainers would need to
@@ -259,7 +259,7 @@ automatically upload it to GitHub.
     process. The reason is that the reproduction which is automatically
     produced by the [built-in info plugin] contains all of the necessary
     environment information that is often forgotten to be included.
-    
+
     Additionally, there are many non-technical users of Material for MkDocs that
     have trouble creating repositories.
 
@@ -301,7 +301,7 @@ only relevant when the bug you are reporting does not involve a crash when
 
 Thanks for following the guide and creating a high-quality and complete bug
 report – you are almost done. This section ensures that you have read this guide
-and have worked to the best of your knowledge to provide us with everything we 
+and have worked to the best of your knowledge to provide us with everything we
 need to know to help you.
 
 __We'll take it from here.__

docs/conventions.md

@@ -0,0 +1,67 @@
+# Conventions
+
+This section explains several conventions used in this documentation.
+
+## Symbols
+
+This documentation use some symbols for illustration purposes. Before you read
+on, please make sure you've made yourself familiar with the following list of
+conventions:
+
+### <!-- md:sponsors --> – Sponsors only { data-toc-label="Sponsors only" }
+
+The pumping heart symbol denotes that a specific feature or behavior is only
+available to sponsors via [Insiders]. Make sure that you have access to
+[Insiders] if you want to use the feature.
+
+### <!-- md:version --> – Version { data-toc-label="Version" }
+
+The tag symbol in conjunction with a version number denotes when a specific
+feature or behavior was added. Make sure you're at least on this version
+if you want to use it.
+
+### <!-- md:version insiders- --> – Version (Insiders)  { data-toc-label="Version (Insiders)" }
+
+The tag symbol with a heart in conjunction with a version number denotes that a
+specific feature or behavior was added to the [Insiders] version of Material for
+MkDocs.
+
+### <!-- md:default --> – Default value { #default data-toc-label="Default value" }
+
+Some properties in `mkdocs.yml` have default values for when the author does not
+explicitly define them. The default value of the property is always included.
+
+#### <!-- md:default computed --> – Default value is computed { #default data-toc-label="is computed" }
+
+Some default values are not set to static values but computed form other values,
+like the site language, repository provider, or other settings.
+
+#### <!-- md:default none --> – Default value is empty { #default data-toc-label="is empty" }
+
+Some properties do not contain default values. This means that the functionality
+that is associated with them is not available unless explicitly enabled.
+
+### <!-- md:feature --> – Optional feature { #feature data-toc-label="Optional feature" }
+
+Most of the features are hidden behind feature flags, which means they must
+be explicitly enabled via `mkdocs.yml`. This allows for the existence of
+potentially orthogonal features.
+
+### <!-- md:flag experimental --> – Experimental { data-toc-label="Experimental" }
+
+Some newer features are still considered experimental, which means the ymight
+(although rarely) change at any time, including their complete removal (which
+hasn't happened yet).
+
+### <!-- md:plugin --> – Plugin { data-toc-label="Plugin" }
+
+Several features are implemented through MkDocs excellent plugin architecture,
+some of which are built-in and distributed with Material for MkDocs, so no
+installation is required.
+
+### <!-- md:utility --> – Utility { data-toc-label="Utility" }
+
+Besides plugins, there are some utilities that build on top of MkDocs in order
+to provide extended functionality, like for example support for versioning.
+
+  [Insiders]: insiders/index.md

docs/creating-your-site.md

@@ -1,6 +1,6 @@
 # Creating your site
 
-After you've [installed] Material for MkDocs, you can bootstrap your project 
+After you've [installed] Material for MkDocs, you can bootstrap your project
 documentation using the `mkdocs` executable. Go to the directory where you want
 your project to be located and enter:
 
@@ -48,7 +48,7 @@ theme:
 
 ???+ tip "Recommended: [configuration validation and auto-complete]"
 
-    In order to minimize friction and maximize productivity, Material for MkDocs 
+    In order to minimize friction and maximize productivity, Material for MkDocs
     provides its own [schema.json][^1] for `mkdocs.yml`. If your editor supports
     YAML schema validation, it's definitely recommended to set it up:
 

docs/customization.md

@@ -225,7 +225,7 @@ to make more fundamental changes, it may be necessary to make the adjustments
 directly in the source of the theme and recompile it.
 
   [^1]:
-    Prior to :octicons-tag-24: 7.0.0 the build was based on Webpack, resulting
+    Prior to <!-- md:version 7.0.0 --> the build was based on Webpack, resulting
     in occasional broken builds due to incompatibilities with loaders and
     plugins. Therefore, we decided to swap Webpack for a leaner solution which
     is now based on [RxJS] as the application itself. This allowed for the

docs/guides/creating-a-reproduction.md

@@ -1,8 +1,8 @@
 # Creating a reproduction
 
-A reproduction is a simplified version of a bug that demonstrates the specific 
+A reproduction is a simplified version of a bug that demonstrates the specific
-scenario in which the bug occurred. It includes all necessary minimal settings 
+scenario in which the bug occurred. It includes all necessary minimal settings
-and instructions and should be as simple as possible while still demonstrating 
+and instructions and should be as simple as possible while still demonstrating
 the issue.
 
 ## Guide
@@ -87,7 +87,7 @@ inside it. Next:
     bug, create only the necessary amount of Markdown documents. __Repeat this
     step until the bug you want to report can be observed.__
 
-4.  As a last step, before packing everything into a .zip file, double-check
+4.  As a last step, before packing everything into a `.zip` file, double-check
     all settings and documents if they are essential to the reproduction, which
     means that the bug does not occur when they are omitted. Remove all
     non-essential lines and files.
@@ -95,11 +95,11 @@ inside it. Next:
   [bug reporting guide]: ../contributing/reporting-a-bug.md#upgrade-to-latest-version
   [minimal configuration]: ../creating-your-site.md#minimal-configuration
 
-### Creating a .zip file
+### Creating a `.zip` file
 
 Material for MkDocs 9.0.0 includes a new plugin solely intended to create
 reproductions for bug reports. When the built-in info plugin is enabled, MkDocs
-will add all relevant files to a .zip, print a summary to the terminal and
+will add all relevant files to a `.zip`, print a summary to the terminal and
 exit. Add the following lines to `mkdocs.yml`:
 
 ``` yaml

docs/insiders/getting-started.md

@@ -6,7 +6,7 @@ title: Getting started with Insiders
 
 Material for MkDocs Insiders is a compatible drop-in replacement for Material
 for MkDocs, and can be installed similarly using [`pip`][pip],
-[`docker`][docker] or [`git`][git]. Note that in order to access the Insiders 
+[`docker`][docker] or [`git`][git]. Note that in order to access the Insiders
 repository, you need to [become an eligible sponsor] of @squidfunk on GitHub.
 
   [pip]: #with-pip
@@ -18,7 +18,7 @@ repository, you need to [become an eligible sponsor] of @squidfunk on GitHub.
 
 After you've been added to the list of collaborators and accepted the
 repository invitation, the next step is to create a [personal access token] for
-your GitHub account in order to access the Insiders repository programmatically 
+your GitHub account in order to access the Insiders repository programmatically
 (from the command line or GitHub Actions workflows):
 
 1.  Go to https://github.com/settings/tokens
@@ -66,7 +66,7 @@ comfortable self-hosting:
 6.  Install [Pull App] on your fork to stay in-sync with upstream
 
 The [`publish`][publish] workflow[^5] is automatically run when a new tag
-(release) is created. When a new Insiders version is released on the upstream 
+(release) is created. When a new Insiders version is released on the upstream
 repository, the [Pull App] will create a pull request with the changes and
 pull in the new tag, which is picked up by the [`publish`][publish] workflow
 that builds and publishes the Docker image automatically to your private
@@ -155,7 +155,33 @@ pip install --upgrade git+https://${GH_TOKEN}@github.com/squidfunk/mkdocs-materi
 When you're using built-in plugins that are solely available via Insiders,
 outside contributors won't be able to build your documentation project on their
 local machine. This is the reason why we developed the [built-in group plugin]
-that allows to conditionally load plugins.
+that allows to conditionally load plugins:
+
+``` yaml
+plugins:
+  - search
+  - social
+
+  # CI=1 mkdocs build
+  - group:
+      enabled: !ENV CI
+      plugins:
+        - git-revision-date-localized
+        - git-committers
+
+  # INSIDERS=1 mkdocs build
+  - group:
+      enabled: !ENV INSIDERS
+      plugins:
+        - optimize
+        - privacy
+```
+
+Of course, you can also enable both groups with:
+
+```
+CI=1 INSIDERS=1 mkdocs build
+```
 
   [^1]:
     Previously we recommended to use [configuration inheritance] to work around
@@ -164,63 +190,5 @@ that allows to conditionally load plugins.
     your project with the community edition and Insiders version of Material
     for MkDocs.
 
-  [built-in group plugin]: #built-in-group-plugin
+  [built-in group plugin]: ../plugins/group.md
   [configuration inheritance]: https://www.mkdocs.org/user-guide/configuration/#configuration-inheritance
-
-### Built-in group plugin
-
-[:octicons-tag-24: 9.3.0][Group plugin support] ·
-:octicons-cpu-24: Plugin ·
-:octicons-beaker-24: Experimental
-
-The built-in group plugin adds support for conditionally loading plugins based
-on environments. This makes enabling and disabling of multiple plugins much
-simpler, as you can group them into logical units and enable or disable them
-with an [environment variable]:
-
-``` yaml
-plugins:
-  - group:
-      enabled: !ENV CI
-      plugins:
-        - optimize
-        - minify
-```
-
-[`enabled`](#+group.enabled){ #+group.enabled }
-
-:   :octicons-milestone-24: Default: `false` – This option specifies whether
-    the plugin is enabled when building your project. By default, the plugin is
-    disabled, so you can use an [environment variable]:
-
-    ``` yaml
-    plugins:
-      - group:
-          enabled: !ENV CI
-    ```
-
-    Now, If you invoke MkDocs with that environment variable (or export the
-    environment variable before invoking MkDocs), the plugin will be enabled:
-
-    ``` sh
-    CI=true mkdocs build
-    ```
-
-[`plugins`](#+group.plugins){ #+group.plugins }
-
-:   :octicons-milestone-24: Default: _none_ – This option specifies the plugins
-    that the group plugin should load when enabled. Note that the plugins must
-    be specified as a list, even if there's only one plugin:
-
-    ``` yaml
-    plugins:
-      - group:
-          plugins:
-            - optimize
-            - minify
-    ```
-
-    The syntax is exactly the same as for all other plugins.
-
-  [Group plugin support]: https://github.com/squidfunk/mkdocs-material/releases/tag/9.3.0
-  [environment variable]: https://www.mkdocs.org/user-guide/configuration/#environment-variables

docs/philosophy.md

@@ -13,12 +13,12 @@ discusses the [conventions] used in this documentation.
   a professional static site in minutes. No need to know HTML,CSS or JavaScript
   – let Material for MkDocs do the heavy lifting for you.
 
-- __Works on all devices__: Serve your documentation with confidence – the 
+- __Works on all devices__: Serve your documentation with confidence – the
-  underlying layout automatically adapts to perfectly fit the available screen 
+  underlying layout automatically adapts to perfectly fit the available screen
   estate, no matter the type or size of the viewing device.
 
 - __Made to measure__: Change the colors, fonts, language, icons, logo and much
-  more with a few lines of configuration. Material for MkDocs can be easily 
+  more with a few lines of configuration. Material for MkDocs can be easily
   extended and provides tons of options to alter appearance and behavior.
 
 - __Fast and lightweight__: Don't let your users wait – get incredible value
@@ -33,62 +33,3 @@ discusses the [conventions] used in this documentation.
 - __Open Source__: Trust 20,000+ users – choose a mature and well-funded
   solution built with state-of-the-art Open Source technologies. Keep ownership
   of your content without fear of vendor lock-in. Licensed under MIT.
-
-## Conventions
-
-### Symbols
-
-This documentation use some symbols for illustration purposes. Before you read
-on, please make sure you've made yourself familiar with the following list of
-conventions:
-
-[:octicons-heart-fill-24:{ .mdx-heart }   Insiders][Insiders]{ .mdx-insiders }
-
-:   Some features are not yet available in the community edition, but only as
-    part of the Insiders build of Material for MkDocs. Please consult the 
-    [Insiders] guide to learn how to get access.
-
-:octicons-tag-24:   __{x.x.x}__
-
-:   The tag icon in conjunction with a version number denotes when a specific 
-    feature or behavior was added. Make sure you're at least on this version
-    if you want to use it.
-
-:octicons-file-code-24:   __{file.ext}__
-
-:   The source file icon together with a file name is sometimes used in code
-    examples which span multiple files. The file name (or path) always starts
-    from the location of `mkdocs.yml`.
-
-:octicons-milestone-24:   __Default__: _value_
-
-:   Some properties in `mkdocs.yml` have default values for when the author
-    does not explicitly define them. The default value of the property is always
-    included.
-
-:octicons-unlock-24:   __Feature flag__
-
-:   Most of the features are hidden behind feature flags, which means they must
-    be explicitly enabled via `mkdocs.yml`. This allows for the existence of
-    potentially orthogonal features.
-
-:octicons-beaker-24:   __Experimental__
-
-:   Some newer features are still considered experimental, which means they
-    might (although rarely) change at any time, including their complete removal 
-    (which hasn't happened yet).
-
-
-:octicons-cpu-24:   __Plugin__
-
-:   Several features are implemented through MkDocs excellent plugin
-    architecture, some of which are built-in and distributed with Material for
-    MkDocs, so no installation is required.
-
-:octicons-package-24:   __Utility__
-
-:   Besides plugins, there are some utilities that build on top of MkDocs in
-    order to provide extended functionality, like for example support for
-    versioning.
-
-  [Insiders]: insiders/index.md

docs/plugins/group.md

@@ -0,0 +1,121 @@
+---
+title: Built-in group plugin
+icon: material/format-list-group
+---
+
+# Built-in group plugin
+
+The group plugin allows to group plugins into logical units to conditionally
+enable or disable them for specific environments with the use of
+[environment variables][mkdocs.env], e.g., to only enable a subset of
+plugins when [building your project] during continuous integration (CI).
+
+  [building your project]: ../creating-your-site.md#building-your-site
+
+## Objective
+
+### How it works
+
+The plugin conditionally and lazily loads all plugins that are part of a group
+if and only if the group is enabled, which means that the plugin doesn't add any
+overhead when the group is disabled. It also means that the grouped plugins
+only need to be installed when the group is enabled.
+
+The plugins that are part of the group are executed in the same order as if
+they were defined at the top-level in the list of [`plugins`][mkdocs.plugins].
+Thus, order is preserved and deterministic.
+
+### When to use it
+
+Whenever you're using multiple plugins that are only required in specific
+environments, e.g., when building your project during continuous integration
+(CI), the plugin is the perfect utility for making configuration simpler, as it
+removes the need for splitting configuration into multiple files.
+
+It can be used with any built-in or third-party plugin.
+
+## Configuration
+
+<!-- md:version 9.3.0 -->
+<!-- md:plugin [group] – built-in -->
+<!-- md:flag multiple -->
+<!-- md:flag experimental -->
+
+As with all [built-in plugins], getting started with the group plugin is
+straightforward. Just add the following lines to `mkdocs.yml`, and start
+splitting plugins into logical units:
+
+``` yaml
+plugins:
+  - group
+```
+
+The group plugin is built into Material for MkDocs and doesn't need to be
+installed.
+
+  [group]: group.md
+  [built-in plugins]: index.md
+
+### General
+
+The following settings are available:
+
+---
+
+#### <!-- md:setting config.enabled -->
+
+<!-- md:version 9.2.0 -->
+<!-- md:default `false` -->
+
+Use this setting to enable or disable the plugin when [building your project].
+The plugin behaves differently than all other built-in plugins – __it is
+disabled by default__. To enable a group, use:
+
+``` yaml
+plugins:
+  - group:
+      enabled: !ENV CI # (1)!
+```
+
+1.  If you only want to use the group plugin for better organization and
+    always want to enable the plugins that are part of it, use:
+
+    ``` yaml
+    plugins:
+      - group:
+          enabled: true
+    ```
+
+The decision to disable the plugin by default was made to simplify the usage
+of environment variables, as it removes the need to provide a default value for
+an environment variable.
+
+Now, when [building your project], you can enable a group by setting the
+[environment variable][mkdocs.env]:
+
+``` sh
+CI=true mkdocs build
+```
+
+  [building your project]: ../creating-your-site.md#building-your-site
+
+---
+
+#### <!-- md:setting config.plugins -->
+
+<!-- md:version 9.2.0 -->
+<!-- md:default none -->
+
+Use this setting to list the plugins that are part of the group. The syntax is
+exactly the same as for the [`plugins`][mkdocs.plugins] setting, so you can
+simply copy the list of plugins that you want to group, e.g:
+
+``` yaml
+plugins:
+  - group:
+      plugins:
+        - optimize
+        - minify
+```
+
+The plugins mentioned here are just used for illustration purposes.

docs/plugins/index.md

@@ -0,0 +1,246 @@
+# Built-in plugins
+
+Material for MkDocs started out as a theme for [MkDocs][mkdocs], but has since
+evolved into a full-fledged framework for building and maintaining documentation.
+The theme is still the core of the project, but it's now accompanied by a
+growing number of complementary built-in plugins.
+
+We strive to make those plugins as modular and generic as possible, so that they
+can be used in a wide variety of projects and use cases. By providing useful
+default settings, we also try to make them as easy to use as possible, so that
+you can get started quickly, tweaking their settings later on. When
+developing built-in plugins, we always adhere to the following design principles:
+
+- **Modularity:** Built-in plugins are designed to be modular, so that they can
+  be easily combined to implement sophisticated pipelines. For example, the
+  [offline], [optimize] and [privacy] plugins can be used together to build
+  truly [offline-capable documentation].
+
+- **Interoperability:** Built-in plugins are designed to be as compatible as
+  possible, so they can be used in combination with other plugins, including
+  third-party plugins. We strive to make it simple to integrate with the vast
+  ecosystem that has evolved around [MkDocs][mkdocs].
+
+- **Performance:** Built-in plugins are designed to be as fast and
+  memory-efficient as possible, so that they don't unnecessarily slow down
+  builds. This is particularly important for large documentation projects with
+  thousands of pages.
+
+  [mkdocs]: https://www.mkdocs.org/
+  [design principles]: ../design-principles.md
+  [offline-capable documentation]: ../setup/building-for-offline-usage.md
+
+## Categories
+
+### Management
+
+The following plugins greatly improve the authoring experience when working on
+documentation projects by providing better management capabilities, from the
+management of plugins, multiple projects, and metadata, to the creation of
+minimal reproductions for bug reports:
+
+<div class="grid cards" markdown>
+
+-   :material-format-list-group: &nbsp; __[Built-in group plugin][group]__
+
+    ---
+
+    The group plugin allows to group plugins into logical units to conditionally
+    enable or disable them for specific environments with the use of
+    [environment variables][mkdocs.env].
+
+    ---
+
+    __Optimal management of plugins when building in different environments__
+
+-   :material-file-tree: &nbsp; __[Built-in meta plugin][meta]__
+
+    ---
+
+    The meta plugin makes it easy to manage metadata (front matter) for all
+    pages in a folder, so a certain subset of pages uses specific tags or a
+    custom template.
+
+    ---
+
+    __Simpler organization, categorization and management of metadata__
+
+-   :material-folder-open: &nbsp; __[Built-in projects plugin][projects]__
+
+    ---
+
+    The projects plugin allows to split your main project into multiple distinct
+    projects, build them concurrently and preview them together as one.
+
+    ---
+
+    __Connect multiple projects together, and build them separately or as one__
+
+-   :material-information: &nbsp; __[Built-in info plugin][info]__
+
+    ---
+
+    The info plugin is a small and useful utility that helps to create
+    self-contained minimal reproductions, so we maintainers can fix reported
+    bugs more quickly.
+
+    ---
+
+    __Your bug reports are of the highest quality, so we can fix them as fast as
+    possible__
+
+
+</div>
+
+  [group]: group.md
+  [info]: info.md
+  [meta]: meta.md
+  [projects]: meta.md
+
+### Optimization
+
+The following plugins are designed to help you build optimized documentation,
+making it more accessible to your users through faster loading times, better
+search engine rankings, beautiful preview images on social media, and GDPR
+compliance with a few lines of configuration:
+
+<div class="grid cards" markdown>
+
+-   :material-share-circle: &nbsp; __[Built-in social plugin][social]__
+
+    ---
+
+    The social plugin automatically generates beautiful and customizable
+    social cards for each page of your documentation, showing as previews on
+    social media.
+
+    ---
+
+    __Links to your site render beautiful social cards when shared on social
+    media__
+
+-   :material-rabbit: &nbsp; __[Built-in optimize plugin][optimize]__
+
+    ---
+
+    The optimize plugin automatically identifies and optimizes all media files
+    that you reference in your project by using compression and conversion
+    techniques.
+
+    ---
+
+    __Your site loads faster as smaller images are served to your users__
+
+-   :material-shield-account: &nbsp; __[Built-in privacy plugin][privacy]__
+
+    ---
+
+    The privacy plugin downloads external assets automatically for easy
+    self-hosting, allowing for GDPR compliance with a single line of
+    configuration.
+
+    ---
+
+    __Your documentation can be made GDPR compliant with minimal effort__
+
+-   :material-connection: &nbsp; __[Built-in offline plugin][offline]__
+
+    ---
+
+    The offline plugin adds support for building [offline-capable documentation],
+    so you can distribute the [`site` directory][mkdocs.site_dir] as a `.zip`
+    file that can be downloaded.
+
+    ---
+
+    __Your documentation can work without connectivity to the internet__
+
+</div>
+
+  [offline]: offline.md
+  [optimize]: optimize.md
+  [privacy]: privacy.md
+  [social]: social.md
+
+### Content
+
+The following plugins are designed to help you set up a blog, provide search
+functionality to your users, add tags to pages and posts, and use the same
+typesetting capabilities in specific parts of the documentation exactly as in
+the main content:
+
+<div class="grid cards" markdown>
+
+-   :material-newspaper-variant-outline: &nbsp; __[Built-in blog plugin][blog]__
+
+    ---
+
+    The blog plugin adds first-class support for blogging to Material for
+    MkDocs, either as a sidecar to your documentation or as a standalone
+    installation.
+
+    ---
+
+    __Your blog is built with the same powerful engine as your documentation__
+
+-   :material-magnify: &nbsp; __[Built-in search plugin][search]__
+
+    ---
+
+    The search plugin adds a search bar to the header, allowing users to search
+    the entire documentation, so it's easier for them to find what they're
+    looking for.
+
+    ---
+
+    __Your documentation is searchable without any external services, even
+    offline__
+
+-   :material-tag-text: &nbsp; __[Built-in tags plugin][tags]__
+
+    ---
+
+    The tags plugin adds first-class support for categorizing pages with tags,
+    adding the ability to group related pages to improve the discovery of
+    related content.
+
+    ---
+
+    __Your pages are categorized with tags, yielding additional context__
+
+-   :material-format-title: &nbsp; __[Built-in typeset plugin][typeset]__
+
+    ---
+
+    The typeset plugin allows to preserve the enriched presentation of titles
+    and headlines within the navigation and table of contents.
+
+    ---
+
+    __Sidebars preserve the same formatting as section titles in pages__
+
+</div>
+
+  [blog]: blog.md
+  [search]: search.md
+  [tags]: tags.md
+  [typeset]: typeset.md
+
+## Architecture
+
+### Multiple instances
+
+Several built-in plugins have support for multiple instances, which means that
+they can be used multiple times in the same configuration file, allowing to
+fine-tune behavior for separate sections of your project. Currently, the
+following plugins have support for multiple instances:
+
+<div class="mdx-columns" markdown>
+
+- [Built-in blog plugin][blog]
+- [Built-in group plugin][group]
+- [Built-in optimize plugin][optimize]
+- [Built-in privacy plugin][privacy]
+- [Built-in social plugin][social]
+
+</div>

docs/plugins/info.md

@@ -0,0 +1,155 @@
+---
+title: Built-in info plugin
+icon: material/information
+---
+
+# Built-in info plugin
+
+The info plugin is a utility that is solely intended to create self-contained
+[minimal reproductions] as `.zip` files when [reporting bugs] or proposing
+[change requests], making communication between us maintainers and you much
+easier, as we have a common ground to work on.
+
+  [minimal reproductions]: ../guides/creating-a-reproduction.md
+  [reporting bugs]: ../contributing/reporting-a-bug.md
+  [change requests]: ../contributing/requesting-a-change.md
+
+## Objective
+
+### How it works
+
+The plugin helps you to prepare a minimal reproduction by collecting the
+necessary information about the environment and configuration of your project.
+This makes it easier for us to fix bugs, as it requires that you
+[upgrade to the latest version] and [remove your customizations].
+
+When following these principles, you can be confident that you don't report a
+bug that has already been fixed in a subsequent release, or which is caused by
+one of your customizations. Even more importantly, you actively help
+us to fix the bug as quickly as possible.
+
+The output of the plugin is a `.zip` file that you can share with us maintainers.
+
+  [Upgrade to the latest version]: ../contributing/reporting-a-bug.md#upgrade-to-latest-version
+  [Remove your customizations]: ../contributing/reporting-a-bug.md#remove-customizations
+
+
+### When to use it
+
+Whenever you're [reporting a bug][reporting bugs] or have something to discuss,
+like a question or [change request][change requests], you should attach
+a small, self-contained minimal reproduction. Runnable examples help to make
+communication much more efficient, giving us maintainers more time to benefit
+more users by pushing the project forward. Minimal reproductions are mandatory
+for bug reports.
+
+## Configuration
+
+<!-- md:version 9.0.0 -->
+<!-- md:plugin [info] – built-in -->
+
+In order to get started with the built-in info plugin, just add the following
+lines to `mkdocs.yml`, and quickly [create a minimal reproduction] to share
+with us maintainers:
+
+``` yaml
+plugins:
+  - info
+```
+
+The info plugin is built into Material for MkDocs and doesn't need to be
+installed.
+
+  [info]: info.md
+  [create a minimal reproduction]: ../guides/creating-a-reproduction.md
+
+### General
+
+The following settings are available:
+
+---
+
+#### <!-- md:setting config.enabled -->
+
+<!-- md:version 9.0.0 -->
+<!-- md:default `true` -->
+
+Use this setting to enable or disable the plugin when [building your project].
+It's normally not necessary to specify this setting, but if you want to disable
+the plugin, use:
+
+``` yaml
+plugins:
+  - info:
+      enabled: false
+```
+
+  [building your project]: ../creating-your-site.md#building-your-site
+
+---
+
+#### <!-- md:setting config.enabled_on_serve -->
+
+<!-- md:version 9.0.6 -->
+<!-- md:default `false` -->
+
+Use this setting to control whether the plugin should be enabled when
+[previewing your site]. It's normally not necessary to specify this setting,
+but if you want to change this behavior, use:
+
+``` yaml
+plugins:
+  - info:
+      enabled_on_serve: true
+```
+
+This setting streamlines the process of creating and inspecting minimal
+reproductions, as it allows to quickly iterate on the reproduction without
+having to disable the plugin first.
+
+  [previewing your site]: ../creating-your-site.md#previewing-as-you-write
+
+### Archive
+
+---
+
+#### <!-- md:setting config.archive -->
+
+<!-- md:version 9.0.0 -->
+<!-- md:default `true` -->
+
+Use this setting to control whether the plugin should create a `.zip` file
+from the project or exit after the version check. This setting is solely
+intended for debugging the plugin itself:
+
+``` yaml
+plugins:
+  - info:
+      archive: false
+```
+
+---
+
+#### <!-- md:setting config.archive_stop_on_violation -->
+
+<!-- md:version 9.0.0 -->
+<!-- md:default `true` -->
+
+Use this setting to control whether the plugin should stop creating the `.zip`
+file when one of the [requirements] is not satisfied. This setting must only be
+used when [reporting a bug][reporting bugs] that is related to a customization
+[explicitly mentioned in our documentation]. You can change it with:
+
+``` yaml
+plugins:
+  - info:
+      archive_stop_on_violation: false
+```
+
+If you're using this setting when [reporting a bug][reporting bugs], please
+explain why you think it is necessary to include customizations. If you're
+unsure, please ask us first by [creating a discussion].
+
+  [requirements]: #how-it-works
+  [explicitly mentioned in our documentation]: ?q=%22extends+base%22
+  [creating a discussion]: https://github.com/squidfunk/mkdocs-material/discussions

docs/plugins/meta.md

@@ -0,0 +1,195 @@
+---
+title: Built-in meta plugin
+icon: material/file-tree
+---
+
+# Built-in meta plugin
+
+The meta plugin solves the problem of setting metadata (front matter) for all
+pages in a folder, i.e., a subsection of your project, which is particularly
+useful to ensure that a certain subset of pages features specific tags, uses a
+custom template, or is attributed to an author.
+
+## Objective
+
+### How it works
+
+The plugin scans the [`docs` directory][mkdocs.docs_dir] for `.meta.yml` files,
+and recursively merges the contents of those files with the metadata (front
+matter) of all pages that are contained in the same folder and all subfolders.
+For example, if you want to add the tag <span class="md-tag">Example</span> to
+multiple pages, use:
+
+``` yaml title=".meta.yml"
+tags:
+  - Example
+```
+
+Now, given the following directory layout, if you store the file in the folder
+named `example`, all pages in that folder receive the tag, while all pages
+outside of the folder remain unaffected:
+
+``` { .sh .no-copy hl_lines="4-8" }
+.
+├─ docs/
+│  ├─ ...
+│  ├─ example/
+│  │  ├─ .meta.yml
+│  │  ├─ a.md
+│  │  ├─ ...
+│  │  └─ z.md
+│  └─ ...
+└─ mkdocs.yml
+```
+
+When combining metadata, lists and dictionaries are recursively merged, which
+means you can append values to a list and add or set specific properties in a
+dictionary on arbitrary levels.
+
+### When to use it
+
+While the plugin itself doesn't offer much functionality beyond adding and
+merging metadata, it is a perfect companion for many of the other built-in
+plugins that Material for MkDocs offers. Some of the most powerful combinations
+of the meta plugin and other built-in plugins are:
+
+<div class="grid cards" markdown>
+
+-   :material-share-circle: &nbsp; __[Built-in social plugin][social]__
+
+    ---
+
+    The meta plugin can be used to [change the layout] for social cards or
+    [change specific layout options] like [background] or [color]
+    for a subset of pages.
+
+    ``` yaml title=".meta.yml"
+    social:
+      cards_layout: default/variant
+    ```
+
+-   :material-newspaper-variant-outline: &nbsp; __[Built-in blog plugin][blog]__
+
+    ---
+
+    The meta plugin allows to automatically associate blog posts with specific
+    [authors] and [categories], ensuring that blog posts are always correctly
+    annotated.
+
+    ``` yaml title=".meta.yml"
+    authors:
+      - squidfunk
+    ```
+
+-   :material-tag-text: &nbsp; __[Built-in tags plugin][tags]__
+
+    ---
+
+    The meta plugin makes it possible to ensure that subsections of your
+    project are annotated with [specific tags], so they can't be forgotten when
+    adding pages.
+
+    ``` yaml title=".meta.yml"
+    tags:
+      - Example
+    ```
+
+-   :material-magnify: &nbsp; __[Built-in search plugin][search]__
+
+    ---
+
+    The meta plugin makes it easy to [boost] specific sections in search results
+    or to [exclude] them entirely from being indexed, giving more granular
+    control over search.
+
+    ``` yaml title=".meta.yml"
+    search:
+      exclude: true
+    ```
+
+</div>
+
+  [social]: social.md
+  [change the layout]: social.md#meta.social.cards_layout
+  [change specific layout options]: social.md#meta.social.cards_layout_options
+  [background]: social.md#option.background_color
+  [color]: social.md#option.color
+  [blog]: blog.md
+  [authors]: blog.md#meta.authors
+  [categories]: blog.md#meta.categories
+  [tags]: tags.md
+  [specific tags]: tags.md#meta.tags
+  [search]: search.md
+  [exclude]: search.md#meta.search.exclude
+  [boost]: search.md#meta.search.boost
+
+## Configuration
+
+<!-- md:sponsors -->
+<!-- md:version insiders-4.21.0 -->
+<!-- md:plugin [meta] – built-in -->
+<!-- md:flag experimental -->
+
+As with all [built-in plugins], getting started with the meta plugin is
+straightforward. Just add the following lines to `mkdocs.yml`, and start
+applying metadata for multiple pages at once:
+
+``` yaml
+plugins:
+  - meta
+```
+
+The meta plugin is included with Material for MkDocs and doesn't need to be
+installed.
+
+  [meta]: meta.md
+  [built-in plugins]: index.md
+
+### General
+
+The following settings are available:
+
+---
+
+#### <!-- md:setting config.enabled -->
+
+<!-- md:sponsors -->
+<!-- md:version insiders-4.38.0 -->
+<!-- md:default `true` -->
+
+Use this setting to enable or disable the plugin when [building your project].
+It's normally not necessary to specify this setting, but if you want to disable
+the plugin, use:
+
+``` yaml
+plugins:
+  - meta:
+      enabled: false
+```
+
+  [building your project]: ../creating-your-site.md#building-your-site
+
+### Meta file
+
+The following settings are available for meta files:
+
+---
+
+#### <!-- md:setting config.meta_file -->
+
+<!-- md:sponsors -->
+<!-- md:version insiders-4.21.0 -->
+<!-- md:default `.meta.yml` -->
+
+Use this setting to change the file  the plugin will look for when scanning
+the [`docs` directory][mkdocs.docs_dir]. It's normally not necessary to change
+this setting, but if you want to change it, use:
+
+``` yaml
+plugins:
+  - meta:
+      meta_file: .meta.yml
+```
+
+The provided path is resolved from the [`docs` directory][mkdocs.docs_dir]
+recursively.

docs/plugins/offline.md

@@ -0,0 +1,153 @@
+---
+title: Built-in offline plugin
+icon: material/connection
+---
+
+
+# Built-in offline plugin
+
+[MkDocs][mkdocs] is one of the few frameworks that allow to build offline-capable
+documentation that can be directly viewed by the user – no server needed. With
+the offline plugin, you can distribute the [`site` directory][mkdocs.site_dir]
+as a downloadable `.zip` file while retaining most interactive functionality.
+
+## Objective
+
+### How it works
+
+After [building your project], switch to the [`site` directory][mkdocs.site_dir]
+and open `index.html` in your browser – you're now viewing your documentation
+from your local file system! Most browsers will denote this by showing `file://`
+in the address bar. However, you'll realize that the site search is gone.
+
+Material for MkDocs offers many interactive features, some of which will not
+work from the local file system due to the restrictions of modern browsers. More
+specifically and technically, all calls to the [Fetch API] will error with a
+message like:
+
+```
+Cross origin requests are only supported for protocol schemes: http, [...]
+```
+
+While browsers impose those restriction for security reasons, it reduces the
+interactivity of your project. The offline plugin makes sure that site search
+keeps working by moving the search index to a JavaScript file, and leveraging
+@squidfunk's [iframe-worker] shim.
+
+Additionally, the plugin automatically disables the
+[`use_directory_urls`][mkdocs.use_directory_urls] setting, ensuring that users
+can open your documentation directly from the local file system.
+
+There are some [limitations].
+
+  [building your project]: ../creating-your-site.md#building-your-site
+  [Fetch API]: https://developer.mozilla.org/en-US/docs/Web/API/Fetch_API
+  [iframe-worker]: https://github.com/squidfunk/iframe-worker
+  [limitations]: #limitations
+
+### When to use it
+
+As the name already indicates, the plugin should only be used when you're
+[building your project] for offline distribution. It's also good to know, that
+the offline plugin plays nicely with the following other plugins, helping to
+create even better offline-capable documentation:
+
+<div class="grid cards" markdown>
+
+-   :material-shield-account: &nbsp; __[Built-in privacy plugin][privacy]__
+
+    ---
+
+    The privacy plugin makes it easy to use external assets when building for
+    offline usage, as it automatically downloads them for distribution with
+    your documentation.
+
+    ---
+
+    __Your documentation can work without connectivity to the internet[^1]__
+
+-   :material-rabbit: &nbsp; __[Built-in optimize plugin][optimize]__
+
+    ---
+
+    The optimize plugin automatically identifies and optimizes all media files
+    that you reference in your project by using compression and conversion
+    techniques.
+
+    ---
+
+    __Your documentation can be distributed as a smaller `.zip` download__
+
+</div>
+
+  [^1]:
+    You might wonder why the [privacy plugin][privacy] is necessary to build
+    truly offline-capable documentation with the offline plugin. While it's
+    certainly possible to also add support for downloading external assets to
+    the offline plugin, this functionality is already fully implemented in the
+    privacy plugin and is its very raison d'être.
+
+    Material for MkDocs follows a modular approach for its plugin system – many
+    of the plugins work perfectly together and enhance each others
+    functionalities, allowing to solve complex problems with a few lines
+    of configuration.
+
+  [privacy]: privacy.md
+  [optimize]: optimize.md
+
+## Configuration
+
+<!-- md:version 9.0.0 -->
+<!-- md:plugin [offline] – built-in -->
+
+As with all [built-in plugins], getting started with the offline plugin is
+straightforward. Just add the following lines to `mkdocs.yml`, and start
+building offline-capable documentation:
+
+``` yaml
+plugins:
+  - offline
+```
+
+The offline plugin is built into Material for MkDocs and doesn't need to be
+installed.
+
+  [offline]: offline.md
+  [built-in plugins]: index.md
+
+### General
+
+The following settings are available:
+
+---
+
+#### <!-- md:setting config.enabled -->
+
+<!-- md:version 9.0.0 -->
+<!-- md:default `true` -->
+
+Use this setting to enable or disable the plugin when [building your project].
+If you want to build online- as well as offline-capable documentation, it's a
+good idea to use an [environment variable][mkdocs.env]:
+
+``` yaml
+plugins:
+  - offline:
+      enabled: !ENV [OFFLINE, false]
+```
+
+## Limitations
+
+When enabling the offline plugin, make sure to disable the following settings,
+as they make use of the [Fetch API] which will error when invoked from the local
+file system:
+
+- [Instant loading]
+- [Site analytics]
+- [Versioning]
+- [Comment systems]
+
+  [Instant loading]: ../setup/setting-up-navigation.md#instant-loading
+  [Site analytics]: ../setup/setting-up-site-analytics.md
+  [Versioning]: ../setup/setting-up-versioning.md
+  [Comment systems]: ../setup/adding-a-comment-system.md

docs/plugins/optimize.md

@@ -0,0 +1,443 @@
+---
+title: Built-in optimize plugin
+icon: material/rabbit
+---
+
+# Built-in optimize plugin
+
+The optimize plugin automatically identifies and optimizes all media files when
+[building your project] by using common compression and conversion techniques.
+As a result, your site loads significantly faster and yields better rankings in
+search engines.
+
+  [building your project]: ../creating-your-site.md#building-your-site
+
+## Objective
+
+### How it works
+
+The plugin scans the [`docs` directory][mkdocs.docs_dir] for media files and
+assets, optimizing them automatically in order to reduce the final size of the
+[`site` directory][mkdocs.site_dir]. This leads to faster loading times as you
+ship less bytes to your users, as well as a smaller download for
+[offline-capable documentation].
+
+Optimized images are [intelligently cached][intelligent caching], which is why
+the plugin will only optimize media files that changed since the last build.
+This makes it possible to swap out or update images, without having to worry
+about optimizing them, or even worse, forgetting to do so.
+
+In order to optimize media files, a few [dependencies] need to be available on
+your system.
+
+  [offline-capable documentation]: ../setup/building-for-offline-usage.md
+  [dependencies]: #configuration
+
+### When to use it
+
+It's generally recommended to use the plugin, as media files are optimized
+automatically without the need for intervention, ensuring that your site loads
+as fast as possible. Optimized media files are one of the key components for a
+high and consistent ranking in search engines.
+
+Additionally, the plugin can be combined with other built-in plugins
+that Material for MkDocs offers, in order to create sophisticated
+build pipelines tailored to your project:
+
+<div class="grid cards" markdown>
+
+-   :material-shield-account: &nbsp; __[Built-in privacy plugin][privacy]__
+
+    ---
+
+    The privacy plugin makes it easy to use unoptimized external assets, passing
+    them to the optimize plugin before copying them to the [`site` directory]
+    [mkdocs.site_dir].
+
+    ---
+
+    __External media files can be automatically downloaded and optimized__
+
+-   :material-connection: &nbsp; __[Built-in offline plugin][offline]__
+
+    ---
+
+    The offline plugin adds support for building offline-capable documentation,
+    so you can distribute the [`site` directory][mkdocs.site_dir] as a `.zip`
+    file that can be downloaded.
+
+    ---
+
+    __Your documentation can be distributed as a smaller `.zip` download__
+
+</div>
+
+  [privacy]: privacy.md
+  [offline]: offline.md
+
+## Configuration
+
+<!-- md:sponsors -->
+<!-- md:version insiders-4.29.0 -->
+<!-- md:plugin [optimize] – built-in -->
+<!-- md:flag multiple -->
+<!-- md:flag experimental -->
+
+As with all [built-in plugins], getting started with the optimize plugin is
+straightforward. Just add the following lines to `mkdocs.yml`, and observe how
+media files are optimized automatically:
+
+``` yaml
+plugins:
+  - optimize
+```
+
+The optimize plugin is built into Material for MkDocs and doesn't need to be
+installed.
+
+However, in order to optimize all media files, it's necessary to install the
+dependencies for [image processing], if they're not already available on your
+system. The linked guide includes instructions for several operating systems
+and mentions some alternative environments.
+
+  [optimize]: optimize.md
+  [built-in plugins]: index.md
+  [image processing]: requirements/image-processing.md
+
+### General
+
+The following settings are available:
+
+---
+
+#### <!-- md:setting config.enabled -->
+
+<!-- md:sponsors -->
+<!-- md:version insiders-4.29.0 -->
+<!-- md:default `true` -->
+
+Use this setting to enable or disable the plugin when [building your project].
+If you want to disable the plugin, e.g., for local builds, you can use an
+[environment variable][mkdocs.env] in `mkdocs.yml`:
+
+``` yaml
+plugins:
+  - optimize:
+      enabled: !ENV [CI, false]
+```
+
+This configuration enables the plugin only during continuous integration (CI).
+
+---
+
+#### <!-- md:setting config.concurrency -->
+
+<!-- md:sponsors -->
+<!-- md:version insiders-4.29.0 -->
+<!-- md:default available CPUs - 1 -->
+
+With more CPUs available, the plugin can do more work in parallel, and thus
+complete media file optimization faster. If you want to disable concurrent
+processing completely, use:
+
+``` yaml
+plugins:
+  - optimize:
+      concurrency: 1
+```
+
+By default, the plugin uses all available CPUs - 1 with a minimum of 1.
+
+### Caching
+
+The plugin implements an [intelligent caching] mechanism, ensuring that a media
+file or asset is only passed through the optimization pipeline when its contents
+change. If you swap out or update an image, the plugin detects it and updates
+the optimized version of the media file.
+
+The following settings are available for caching:
+
+  [intelligent caching]: requirements/caching.md
+
+---
+
+#### <!-- md:setting config.cache -->
+
+<!-- md:sponsors -->
+<!-- md:version insiders-4.29.0 -->
+<!-- md:default `true` -->
+
+Use this setting to instruct the plugin to bypass the cache, in order to
+re-optimize all media files, even though the cache may not be stale. It's
+normally not necessary to specify this setting, except for when debugging
+the plugin itself. Caching can be disabled with:
+
+``` yaml
+plugins:
+  - optimize:
+      cache: false
+```
+
+---
+
+#### <!-- md:setting config.cache_dir -->
+
+<!-- md:sponsors -->
+<!-- md:version insiders-4.29.0 -->
+<!-- md:default `.cache/plugin/optimize` -->
+
+It is normally not necessary to specify this setting, except for when you want
+to change the path within your root directory where media files are cached.
+If you want to change it, use:
+
+``` yaml
+plugins:
+  - optimize:
+      cache_dir: my/custom/dir
+```
+
+If you're using [multiple instances] of the plugin, it can be a good idea to
+set different cache directories for both instances, so that they don't interfere
+with each other.
+
+  [multiple instances]: index.md#multiple-instances
+
+### Optimization
+
+Documentation often makes use of screenshots or diagrams for better
+visualization of things, both of which are prime candidates for optimization.
+The plugin automatically optimizes images using [pngquant] for `.png` files,
+and [Pillow] for `.jpg` files.
+
+The following settings are available for optimization:
+
+  [pngquant]: https://pngquant.org/
+  [Pillow]: https://pillow.readthedocs.io/
+
+---
+
+#### <!-- md:setting config.optimize -->
+
+<!-- md:sponsors -->
+<!-- md:version insiders-4.41.0 -->
+<!-- md:default `true` -->
+
+Use this setting to enable or disable media file optimization. Currently,
+the plugin's sole purpose is to optimize media files, so it's equivalent to the
+[`enabled`][config.enabled] setting, but in the near future, other features
+might be added. If you want to disable optimization, use:
+
+``` yaml
+plugins:
+  - optimize:
+      optimize: false
+```
+
+---
+
+#### <!-- md:setting config.optimize_png -->
+
+<!-- md:sponsors -->
+<!-- md:version insiders-4.29.0 -->
+<!-- md:default `true` -->
+
+Use this setting to enable or disable the optimization of `.png` files. It's
+normally not necessary to specify this setting, but if you want to disable
+the optimization of `.png` files, use:
+
+``` yaml
+plugins:
+  - optimize:
+      optimize_png: false
+```
+
+---
+
+#### <!-- md:setting config.optimize_png_speed -->
+
+<!-- md:sponsors -->
+<!-- md:version insiders-4.29.0 -->
+<!-- md:default `3` of `1-10` -->
+
+Use this setting to specify the speed/quality tradeoff that [pngquant] applies
+when optimizing `.png` files. The lower the number, the more aggressively
+[pngquant] will try to optimize:
+
+=== "Slower <small>smaller</small>"
+
+    ``` yaml
+    plugins:
+      - optimize:
+          optimize_png_speed: 1
+    ```
+
+=== "Faster <small>larger</small>"
+
+    ``` yaml
+    plugins:
+      - optimize:
+          optimize_png_speed: 10
+    ```
+
+A factor of `10` has 5% lower quality, but is 8x faster than the default `3`.
+
+---
+
+#### <!-- md:setting config.optimize_png_strip -->
+
+<!-- md:sponsors -->
+<!-- md:version insiders-4.29.0 -->
+<!-- md:default `true` -->
+
+Use this setting to specify whether [pngquant] should strip optional metadata
+from `.png` files that are not required to display the image, e.g., [EXIF].
+If you want to preserve metadata, use:
+
+``` yaml
+plugins:
+  - optimize:
+      optimize_png_strip: false
+```
+
+  [EXIF]: https://en.wikipedia.org/wiki/Exif
+
+---
+
+#### <!-- md:setting config.optimize_jpg -->
+
+<!-- md:sponsors -->
+<!-- md:version insiders-4.29.0 -->
+<!-- md:default `true` -->
+
+Use this setting to enable or disable the optimization of `.jpg` files. It's
+normally not necessary to specify this setting, but if you want to disable
+the optimization of `.jpg` files, use:
+
+``` yaml
+plugins:
+  - optimize:
+      optimize_jpg: false
+```
+
+---
+
+#### <!-- md:setting config.optimize_jpg_quality -->
+
+<!-- md:sponsors -->
+<!-- md:version insiders-4.29.0 -->
+<!-- md:default `60` of `0-100` -->
+
+Use this setting to specify the image quality that [Pillow] applies when
+optimizing `.jpg` files. If the images look blurry, it's a good idea to
+fine-tune and change this setting:
+
+``` yaml
+plugins:
+  - optimize:
+      optimize_jpg_quality: 75
+```
+
+---
+
+#### <!-- md:setting config.optimize_jpg_progressive -->
+
+<!-- md:sponsors -->
+<!-- md:version insiders-4.29.0 -->
+<!-- md:default `true` -->
+
+Use this setting to specify whether [Pillow] should use progressive encoding
+when optimizing `.jpg` files, rendering faster on slow connections. If you want
+to disable progressive encoding, use:
+
+``` yaml
+plugins:
+  - optimize:
+      optimize_jpg_progressive: false
+```
+
+  [progressive encoding]: https://medium.com/hd-pro/jpeg-formats-progressive-vs-baseline-73b3938c2339
+
+---
+
+#### <!-- md:setting config.optimize_include -->
+
+<!-- md:sponsors -->
+<!-- md:version insiders-4.41.0 -->
+<!-- md:default none -->
+
+Use this setting to enable media file optimization for specific directories
+of your project, e.g., when using [multiple instances] of the plugin to optimize
+media files differently:
+
+``` yaml
+plugins:
+  - optimize:
+      optimize_include:
+        - screenshots/*
+```
+
+This configuration enables optimization for all media files that are contained
+in the `screenshots` folder and its subfolders inside the [`docs` directory]
+[mkdocs.docs_dir].
+
+---
+
+#### <!-- md:setting config.optimize_exclude -->
+
+<!-- md:sponsors -->
+<!-- md:version insiders-4.41.0 -->
+<!-- md:default none -->
+
+Use this setting to disable media file optimization for specific directories
+of your project, e.g., when using [multiple instances] of the plugin to optimize
+media files differently:
+
+``` yaml
+plugins:
+  - social:
+      optimize_exclude:
+        - vendor/*
+```
+
+This configuration disables optimization for all media files that are contained
+in the `vendor` folder and its subfolders inside the [`docs` directory]
+[mkdocs.docs_dir].
+
+### Reporting
+
+The following settings are available for reporting:
+
+---
+
+#### <!-- md:setting config.print_gain -->
+
+<!-- md:sponsors -->
+<!-- md:version insiders-4.29.0 -->
+<!-- md:default `true` -->
+
+Use this setting to control whether the plugin should print the number of bytes
+gained after optimizing each file. If you want to disable this behavior, use:
+
+``` yaml
+plugins:
+  - optimize:
+      print_gain: false
+```
+
+---
+
+#### <!-- md:setting config.print_gain_summary -->
+
+<!-- md:sponsors -->
+<!-- md:version insiders-4.29.0 -->
+<!-- md:default `true` -->
+
+Use this setting to control whether the plugin should print the total number of
+bytes gained after optimizing all files. If you want to disable this behavior,
+use:
+
+``` yaml
+plugins:
+  - optimize:
+      print_gain_summary: false
+```

docs/plugins/privacy.md

@@ -0,0 +1,416 @@
+---
+title: Built-in privacy plugin
+icon: material/shield-account
+---
+
+
+# Built-in privacy plugin
+
+The privacy plugin offers a streamlined solution for automatically self-hosting
+external assets. With just a single line of configuration, the plugin can
+automatically identify and download external assets, making GDPR compliance
+as effortless as it can possibly be.
+
+## Objective
+
+### How it works
+
+The plugin scans the generated HTML for external assets, i.e., scripts, style
+sheets, images, and web fonts, downloads them, stores them in the
+[`site` directory][mkdocs.site_dir] and replaces all references with links to
+the downloaded copies for effortless self-hosting. For example:
+
+``` html
+<script src="https://example.com/script.js"></script>
+```
+
+This external script is downloaded, and the link is replaced with:
+
+``` html
+<script src="assets/external/example.com/script.js"></script>
+```
+
+Of course, scripts and style sheets can reference further external assets,
+which is why this process is repeated recursively until no further external
+assets are detected:
+
+- Scripts are scanned for further scripts, style sheets and JSON files
+- Style sheets are scanned for images and web fonts
+
+Additionally, hints like [`preconnect`][preconnect], used to reduce latency when
+requesting external assets, are removed from the output, as they're not
+necessary when self-hosting. After the plugin has done it's work, your project
+will be free of requests to external services.
+
+There are some [limitations].
+
+  [preconnect]: https://developer.mozilla.org/en-US/docs/Web/HTML/Attributes/rel/preconnect
+  [limitations]: #limitations
+
+### When to use it
+
+The plugin was developed to make compliance with the 2018 European
+__General Data Protection Regulation__ (GDPR) as simple as possible, while
+retaining the flexibility and power that Material for MkDocs offers, like for
+example its tight integration with [Google Fonts].
+
+But, that's only the start. For example, if your project includes a lot of
+images, enabling the plugin allows to move them outside of your repository, as
+the plugin will automatically download and store them in the [`site` directory]
+[mkdocs.site_dir] when [building your project].
+
+Even more interestingly, the plugin can be combined with other built-in plugins
+that Material for MkDocs offers, in order to create sophisticated build
+pipelines tailored to your project:
+
+<div class="grid cards" markdown>
+
+-   :material-rabbit: &nbsp; __[Built-in optimize plugin][optimize]__
+
+    ---
+
+    The optimize plugin allows to optimize all downloaded external assets
+    detected by the privacy plugin by using compression and conversion
+    techniques.
+
+    ---
+
+    __External media files are automatically downloaded and optimized__
+
+-   :material-connection: &nbsp; __[Built-in offline plugin][offline]__
+
+    ---
+
+    The offline plugin adds support for building [offline-capable documentation],
+    so you can distribute the [`site` directory][mkdocs.site_dir] as a `.zip`
+    file that can be downloaded.
+
+    ---
+
+    __Your documentation can work without connectivity to the internet__
+
+</div>
+
+  [Google Fonts]: ../setup/changing-the-fonts.md
+  [building your project]: ../creating-your-site.md#building-your-site
+  [optimize]: optimize.md
+  [offline]: offline.md
+  [offline-capable documentation]: ../setup/building-for-offline-usage.md
+
+## Configuration
+
+<!-- md:sponsors -->
+<!-- md:version insiders-4.9.0 -->
+<!-- md:plugin [privacy] – built-in -->
+<!-- md:flag multiple -->
+<!-- md:flag experimental -->
+
+As with all [built-in plugins], getting started with the privacy plugin is
+straightforward. Just add the following lines to `mkdocs.yml`, and start
+effortlessly self-hosting external assets:
+
+``` yaml
+plugins:
+  - privacy
+```
+
+The privacy plugin is built into Material for MkDocs and doesn't need to be
+installed.
+
+  [privacy]: privacy.md
+  [built-in plugins]: index.md
+
+### General
+
+The following settings are available:
+
+---
+
+#### <!-- md:setting config.enabled -->
+
+<!-- md:sponsors -->
+<!-- md:version insiders-4.10.0 -->
+<!-- md:default `true` -->
+
+Use this setting to enable or disable the plugin when [building your project].
+If you want to disable the plugin, e.g., for local builds, you can use an
+[environment variable][mkdocs.env] in `mkdocs.yml`:
+
+``` yaml
+plugins:
+  - privacy:
+      enabled: !ENV [CI, false]
+```
+
+This configuration enables the plugin only during continuous integration (CI).
+
+---
+
+#### <!-- md:setting config.concurrency -->
+
+<!-- md:sponsors -->
+<!-- md:version insiders-4.30.0 -->
+<!-- md:default available CPUs - 1 -->
+
+With more CPUs available, the plugin can do more work in parallel, and thus
+complete handling of external assets faster. If you want to disable concurrent
+processing completely, use:
+
+``` yaml
+plugins:
+  - privacy:
+      concurrency: 1
+```
+
+By default, the plugin uses all available CPUs - 1 with a minimum of 1.
+
+### Caching
+
+The plugin implements an [intelligent caching] mechanism, ensuring that external
+assets are only downloaded when they're not already contained in the cache.
+While the initial build might take some time, it's a good idea to use caching,
+as it will speed up consecutive builds.
+
+The following settings are available for caching:
+
+  [intelligent caching]: requirements/caching.md
+
+---
+
+#### <!-- md:setting config.cache -->
+
+<!-- md:sponsors -->
+<!-- md:version insiders-4.30.0 -->
+<!-- md:default `true` -->
+
+Use this setting to instruct the plugin to bypass the cache, in order to
+re-schedule downloads for all external assets, even though the cache may not be
+stale. It's normally not necessary to specify this setting, except for when
+debugging the plugin itself. Caching can be disabled with:
+
+``` yaml
+plugins:
+  - privacy:
+      cache: false
+```
+
+---
+
+#### <!-- md:setting config.cache_dir -->
+
+<!-- md:sponsors -->
+<!-- md:version insiders-4.30.0 -->
+<!-- md:default `.cache/plugin/privacy` -->
+
+It is normally not necessary to specify this setting, except for when you want
+to change the path within your root directory where downloaded copies are
+cached. If you want to change it, use:
+
+``` yaml
+plugins:
+  - privacy:
+      cache_dir: my/custom/dir
+```
+
+If you're using [multiple instances] of the plugin, it can be a good idea to
+set different cache directories for both instances, so that they don't interfere
+with each other.
+
+  [multiple instances]: index.md#multiple-instances
+
+### External assets
+
+The following settings are available for external assets:
+
+---
+
+#### <!-- md:setting config.assets -->
+
+<!-- md:sponsors -->
+<!-- md:version insiders-4.37.0 -->
+<!-- md:default `true` -->
+
+Use this setting to control whether the plugin should download external
+assets. If you only want the plugin to process [external links], you can disable
+handling of external assets with:
+
+``` yaml
+plugins:
+  - privacy:
+      assets: false
+```
+
+  [external links]: #external-links
+
+---
+
+#### <!-- md:setting config.assets_fetch -->
+
+<!-- md:sponsors -->
+<!-- md:version insiders-4.37.0 -->
+<!-- md:default `true` -->
+
+Use this setting to control whether the plugin should downloads or only report
+external assets when they're encountered. If you already self-host all external
+assets, this setting can be used as a safety net to detect links to external
+assets placed by the author in pages:
+
+``` yaml
+plugins:
+  - privacy:
+      assets_fetch: true
+```
+
+---
+
+#### <!-- md:setting config.assets_fetch_dir -->
+
+<!-- md:sponsors -->
+<!-- md:version insiders-4.37.0 -->
+<!-- md:default `assets/external` -->
+
+It is normally not necessary to specify this setting, except for when you want
+to change the path within the [`site` directory][mkdocs.site_dir] where
+external assets are stored. If you want to change it, use:
+
+``` yaml
+plugins:
+  - privacy:
+      assets_fetch_dir: my/custom/dir
+```
+
+This configuration stores the downloaded copies at `my/custom/dir` in the
+[`site` directory][mkdocs.site_dir].
+
+---
+
+#### <!-- md:setting config.assets_include -->
+
+<!-- md:sponsors -->
+<!-- md:version insiders-4.37.0 -->
+<!-- md:default none -->
+
+Use this setting to enable downloading of external assets for specific origins,
+e.g., when using [multiple instances] of the plugin to fine-tune processing of
+external assets for different origins:
+
+``` yaml
+plugins:
+  - privacy:
+      assets_include:
+        - unsplash.com/*
+```
+
+---
+
+#### <!-- md:setting config.assets_exclude -->
+
+<!-- md:sponsors -->
+<!-- md:version insiders-4.37.0 -->
+<!-- md:default none -->
+
+Use this setting to disable downloading of external assets for specific origins,
+e.g., when using [multiple instances] of the plugin to fine-tune processing of
+external assets for different origins:
+
+``` yaml
+plugins:
+  - privacy:
+      assets_exclude: # (1)!
+        - cdn.jsdelivr.net/npm/mathjax@3/*
+        - giscus.app/*
+```
+
+1.  [MathJax] loads web fonts for typesetting of mathematical content
+    through relative URLs, and thus cannot be automatically bundled by the
+    privacy plugin. [MathJax can be self-hosted].
+
+    [Giscus], which we recommend to use as a [comment system], uses a technique
+    called code-splitting to load only the code that is necessary, which
+    is implemented via relative URLs. [Giscus can be self-hosted] as well.
+
+  [MathJax]: ../reference/math.md
+  [MathJax can be self-hosted]: https://docs.mathjax.org/en/latest/web/hosting.html
+  [Giscus]: https://giscus.app/
+  [comment system]: ../setup/adding-a-comment-system.md
+  [Giscus can be self-hosted]: https://github.com/giscus/giscus/blob/main/SELF-HOSTING.md
+
+---
+
+### External links
+
+The following settings are available for external links:
+
+---
+
+#### <!-- md:setting config.links -->
+
+<!-- md:sponsors -->
+<!-- md:version insiders-4.37.0 -->
+<!-- md:default `true` -->
+
+Use this setting to instruct the plugin to parse and process external links to
+annotate them for [improved security], or to automatically add additional
+attributes to external links. If you want to disable processing of external
+links, use:
+
+``` yaml
+plugins:
+  - privacy:
+      links: false
+```
+
+  [improved security]: https://developer.chrome.com/en/docs/lighthouse/best-practices/external-anchors-use-rel-noopener/
+
+---
+
+#### <!-- md:setting config.links_attr_map -->
+
+<!-- md:sponsors -->
+<!-- md:version insiders-4.37.0 -->
+<!-- md:default none -->
+
+Use this setting to specify additional attributes that should be added to
+external links, for example, to add `target="_blank"` to all external links
+so they open in a new tab:
+
+``` yaml
+plugins:
+  - privacy:
+      links_attr_map:
+        target: _blank
+```
+
+---
+
+#### <!-- md:setting config.links_noopener -->
+
+<!-- md:sponsors -->
+<!-- md:version insiders-4.37.0 -->
+<!-- md:default `true` -->
+
+It is normally not recommended to change this setting, as it will automatically
+annotate external links that open in a new window with `rel="noopener"` for
+[improved security]:
+
+``` yaml
+plugins:
+  - privacy:
+      links_noopener: true
+```
+
+## Limitations
+
+Dynamically created URLs as part of scripts are not detected, and thus cannot be
+downloaded automatically, as the plugin does not execute scripts – it only detects fully qualified URLs for downloading and replacement. In short, don't do this:
+
+``` js
+const cdn = "https://polyfill.io"
+const url = `${cdn}/v3/polyfill.min.js`
+```
+
+Instead, always use fully qualified URLs:
+
+``` js
+const url ="https://polyfill.io/v3/polyfill.min.js"
+```

docs/plugins/projects.md

@@ -0,0 +1,264 @@
+---
+title: Built-in projects plugin
+icon: material/folder-open
+---
+
+# Built-in projects plugin
+
+The projects plugin adds the ability to split your main project into multiple
+distinct projects, build them concurrently and preview them together as one.
+This is particularly useful when creating a multi-language project, but can also
+be used to split very large projects into smaller parts.
+
+## Objective
+
+### How it works
+
+The plugin scans the configured [`projects` directory][config.projects_dir] for
+`mkdocs.yml` files, identifies all nested projects and builds them concurrently.
+If not configured otherwise, the plugin expects that your project has
+the following directory layout, e.g. for a multi-language project:
+
+``` { .sh .no-copy }
+.
+├─ docs/
+├─ projects/
+│  ├─ en/
+│  │  ├─ docs/
+│  │  └─ mkdocs.yml
+│  └─ de/
+│     ├─ docs/
+│     └─ mkdocs.yml
+└─ mkdocs.yml
+```
+
+One of the most useful and interesting features of the plugin is that it allows
+[previewing your site] from the main project, while still being able to preview
+and build each project individually. This is especially useful for
+multi-language projects.
+
+If, when [previewing your site], you change a file in one of the projects, the
+plugin only rebuilds this project and makes sure that MkDocs will also reload
+the associated files. This also creates the opportunity for splitting your
+main project into several projects for a better editing experience.
+
+There are some [limitations], but we're working hard to remove them.
+
+  [previewing your site]: ../creating-your-site.md#previewing-as-you-write
+  [limitations]: #limitations
+
+### When to use it
+
+The plugin came into existence because we needed a convenient and scalable
+method to build our [examples] repository, which features many self-contained
+and runnable projects that users can download and use as a basis when
+boostrapping a new project or [creating a reproduction].
+
+When you want to create a multi-language project, or have a very large existing
+project, you might consider using the plugin, as it makes managing, editing
+and building more comfortable.
+
+  [examples]: https://github.com/mkdocs-material/examples
+  [creating a reproduction]: ../guides/creating-a-reproduction.md
+
+## Configuration
+
+<!-- md:sponsors -->
+<!-- md:version insiders-4.38.0 -->
+<!-- md:plugin [projects] – built-in -->
+<!-- md:flag experimental -->
+
+In order to get started with the projects plugin, just add the following lines
+to `mkdocs.yml`, and split your main project into several distinct projects that
+can be built concurrently:
+
+``` yaml
+plugins:
+  - projects
+```
+
+The projects plugin is built into Material for MkDocs and doesn't need to be
+installed.
+
+  [projects]: projects.md
+
+### General
+
+The following settings are available:
+
+---
+
+#### <!-- md:setting config.enabled -->
+
+<!-- md:sponsors -->
+<!-- md:version insiders-4.38.0 -->
+<!-- md:default `true` -->
+
+Use this setting to enable or disable the plugin when [building your project].
+If you want to disable the plugin, e.g., for local builds, you can use an
+[environment variable][mkdocs.env] in `mkdocs.yml`:
+
+``` yaml
+plugins:
+  - projects:
+      enabled: !ENV [CI, false]
+```
+
+This configuration enables the plugin only during continuous integration (CI).
+
+  [building your project]: ../creating-your-site.md#building-your-site
+
+---
+
+#### <!-- md:setting config.concurrency -->
+
+<!-- md:sponsors -->
+<!-- md:version insiders-4.38.0 -->
+<!-- md:default available CPUs - 1 -->
+
+With more CPUs available, the plugin can do more work in parallel, and thus
+build projects faster. If you want to disable concurrent processing completely,
+use:
+
+``` yaml
+plugins:
+  - projects:
+      concurrency: 1
+```
+
+By default, the plugin uses all available CPUs - 1 with a minimum of 1.
+
+### Caching
+
+The plugin implements an [intelligent caching] mechanism, ensuring that a
+project is only rebuilt when its contents change. While the initial build might
+take some time, it's a good idea to use caching, as it will speed up consecutive
+builds.
+
+The following settings are available for caching:
+
+  [intelligent caching]: requirements/caching.md
+
+---
+
+#### <!-- md:setting config.cache -->
+
+<!-- md:sponsors -->
+<!-- md:version insiders-4.38.0 -->
+<!-- md:default `true` -->
+
+Use this setting to instruct the plugin to bypass the cache, in order to
+rebuild all projects, even though the cache may not be stale. It's normally not
+necessary to specify this setting, except for when debugging the plugin itself.
+Caching can be disabled with:
+
+``` yaml
+plugins:
+  - projects:
+      cache: false
+```
+
+---
+
+#### <!-- md:setting config.cache_dir -->
+
+<!-- md:sponsors -->
+<!-- md:version insiders-4.38.0 -->
+<!-- md:default `.cache/plugin/projects` -->
+
+It is normally not necessary to specify this setting, except for when you want
+to change the path within your root directory where the metadata is cached.
+If you want to change it, use:
+
+``` yaml
+plugins:
+  - projects:
+      cache_dir: my/custom/dir
+```
+
+### Projects
+
+The following settings are available for projects:
+
+---
+
+#### <!-- md:setting config.projects -->
+
+<!-- md:sponsors -->
+<!-- md:version insiders-4.38.0 -->
+<!-- md:default `true` -->
+
+Use this setting to enable or disable building of projects. Currently, the
+plugin's sole purpose is to build projects, so it's equivalent to the
+[`enabled`][config.enabled] setting, but in the future, other features might be
+added. If you want to disable building of projects, use:
+
+``` yaml
+plugins:
+  - projects:
+      projects: false
+```
+
+---
+
+#### <!-- md:setting config.projects_dir -->
+
+<!-- md:sponsors -->
+<!-- md:version insiders-4.38.0 -->
+<!-- md:default `projects` -->
+
+Use this setting to change the folder where your projects are located. It's
+normally not necessary to change this setting, but if you want to rename the
+folder or change its file system location, use:
+
+``` yaml
+plugins:
+  - projects:
+      projects_dir: projects
+```
+
+Note that the [`projects` directory][config.projects_dir] is solely used for
+project organization – it is not included in project URLs, since projects are
+automatically hoisted by the plugin.
+
+The provided path is resolved from the root directory.
+
+### Hoisting
+
+The following settings are available for hoisting:
+
+---
+
+#### <!-- md:setting config.hoisting -->
+
+<!-- md:sponsors -->
+<!-- md:version insiders-4.39.0 -->
+<!-- md:default `true` -->
+
+Use this setting to enable or disable hoisting of themes files to the main
+project. If you disable this setting, each project receives a copy of the
+theme's files, which can be considered redundant:
+
+``` yaml
+plugins:
+  - projects:
+      hoisting: false
+```
+
+It's generally advisable to enable hoisting, as it yields faster deployments
+and faster loading of your project's sites, because the files are the same for
+all projects and can be deduplicated.
+
+### Limitations
+
+The plugin is one of the latest additions to Material for MkDocs, which means it
+is rather young and has some limitations. We're working hard to remove them, and
+we're happy to receive feedback and learn about your requirements in ?5800.
+Current limitations are:
+
+- __Basic multi-language support only__: we'll be investigating how to provide
+  better support for multi-language projects, allowing to easier interlink
+  projects and switch between them.
+
+- __Separate search indexes and sitemaps__: currently, the projects are entirely
+  separate, which means they will have separate search indexes and sitemaps.

docs/plugins/requirements/caching.md

@@ -0,0 +1,35 @@
+---
+icon: material/database-outline
+---
+
+# Caching
+
+Some of the [built-in plugins] implement intelligent caching mechanisms, which
+massively speed up consecutive builds by reducing the amount of work that needs
+to be done. This guide explains how to configure caching in different
+environments.
+
+## Prerequisites
+
+Caching is entirely optional but enabled by default. It can be disabled per
+plugin. If not configured otherwise, plugins will cache their data in the
+`.cache` folder in the root of your project. For this reason it's recommended
+to create a `.gitignore` file in the root of your project:
+
+``` title=".gitignore"
+.cache
+```
+
+This ensures that cached files are not added to your git repository – something
+that is generally not recommended to do unless absolutely necessary. In some
+cases, you might need to check in cached files, e.g. when you need to
+pre-generate [social cards] locally, e.g., when you're not be able to install
+the image processing dependencies in your continuous integration (CI)
+environment.
+
+In this case, we recommend changing the `cache_dir` setting – something that all
+plugins that implement caching share – to a folder which you add to your git
+repository.
+
+  [built-in plugins]: ../index.md
+  [social cards]: ../../setup/setting-up-social-cards.md

docs/plugins/requirements/image-processing.md

@@ -1,21 +1,38 @@
+---
+icon: material/image-sync-outline
+---
+
 # Image processing
 
-Material for MkDocs depends on several libraries to allow for image processing
+Some of the [built-in plugins] depend on external libraries for efficient image
-as part of the build pipeline, including [social cards] and [image optimization].
+processing, most notably the [social] plugin to generate [social cards], and the
-For this reason, a few external libraries must be installed on the host system.
+[optimize] plugin for applying [image optimization]. This guide explains how to
-This section explains how to install them.
+install those libraries in different environments.
 
-  [social cards]: ../setting-up-social-cards.md
+  [built-in plugins]: ../index.md
-  [image optimization]: ../building-an-optimized-site.md
+  [social]: ../social.md
+  [social cards]: ../../setup/setting-up-social-cards.md
+  [optimize]: ../optimize.md
+  [image optimization]: ../../setup/building-an-optimized-site.md
 
 ## Dependencies
 
-Install the Python dependencies for image processing with:
+The libraries for image processing are entirely optional, and only need to be
+installed if you want to use the [social] plugin or the [optimize] plugin. The
+libraries are listed under the `imaging` extra:
 
 ```
-pip install pillow cairosvg
+pip install "mkdocs-material[imaging]"
 ```
 
+This will install compatible versions of the following packages:
+
+- [Pillow]
+- [CairoSVG]
+
+  [Pillow]: https://pillow.readthedocs.io/
+  [CairoSVG]: https://cairosvg.org/
+
 ### Cairo Graphics
 
 [Cairo Graphics] is a graphics library and dependency of [Pillow], which
@@ -36,9 +53,8 @@ Material for MkDocs makes use of for generating [social cards] and performing
 === ":fontawesome-brands-windows: Windows"
 
     As stated in the [installation guide], the easiest way to get up and running
-    with the [Cairo Graphics] library on Windows is by installing [GTK+], since
+    with the [Cairo Graphics] library on Windows is by installing [GTK+]. You
-    it has Cairo as a dependency. You can also download and install a
+    can also download a precompiled [GTK runtime].
-    precompiled [GTK runtime].
 
 === ":material-linux: Linux"
 
@@ -70,8 +86,6 @@ The following environments come with a preinstalled version of [Cairo Graphics]:
 - [x] No installation needed in [GitHub Actions] (Ubuntu)
 
   [Cairo Graphics]: https://www.cairographics.org/
-  [Pillow]: https://pillow.readthedocs.io/
-  [CairoSVG]: https://cairosvg.org/
   [Homebrew]: https://brew.sh/
   [installation guide]: https://www.cairographics.org/download/
   [GTK+]: https://www.gtk.org/docs/installations/windows/
@@ -82,7 +96,7 @@ The following environments come with a preinstalled version of [Cairo Graphics]:
 ### pngquant
 
 [pngquant] is an excellent library for lossy PNG compression, and a direct
-dependency of the [built-in optimize plugin]. See the following section which 
+dependency of the [built-in optimize plugin]. See the following section which
 explains how to install [pngquant] system:
 
 === ":material-apple: macOS"
@@ -97,8 +111,8 @@ explains how to install [pngquant] system:
 
 === ":fontawesome-brands-windows: Windows"
 
-    Installing [pngquant] on Windows is a little more involved. The 
+    Installing [pngquant] on Windows is a little more involved. The
-    [pngquant-winbuild] repository contains a guide on how to set up an 
+    [pngquant-winbuild] repository contains a guide on how to set up an
     environment for building [pngquant] on Windows.
 
 === ":material-linux: Linux"
@@ -113,6 +127,10 @@ explains how to install [pngquant] system:
 
     The same is true for `yum` and `zypper`.
 
+The following environments come with a preinstalled version of [pngquant]:
+
+- [x] No installation needed in [Docker image]
+
   [pngquant]: https://pngquant.org/
-  [built-in optimize plugin]: ../building-an-optimized-site.md#built-in-optimize-plugin
+  [built-in optimize plugin]: ../../setup/building-an-optimized-site.md#built-in-optimize-plugin
   [pngquant-winbuild]: https://github.com/jibsen/pngquant-winbuild

docs/plugins/search.md

@@ -0,0 +1,427 @@
+---
+title: Built-in search plugin
+icon: material/magnify
+---
+
+# Built-in search plugin
+
+The search plugin adds a search bar to the header, allowing users to search your
+documentation. It's powered by [lunr.js], a lightweight full-text search engine
+for the browser, elimininating the need for external services, and even works
+when building [offline-capable documentation].
+
+  [lunr.js]: https://lunrjs.com/
+  [offline-capable documentation]: ../setup/building-for-offline-usage.md
+
+## Objective
+
+### How it works
+
+The plugin scans the generated HTML and builds a search index from all pages and
+sections by extracting the section titles and contents. It preserves some inline
+formatting like code blocks and lists, but removes all other formatting, so the
+search index is as small as possible.
+
+When a user visits your site, the search index is shipped to the browser,
+indexed with [lunr.js] and made available for fast and simple querying – no
+server needed. This ensures that the search index is always up to date with
+your documentation, yielding accurate results.
+
+### When to use it
+
+It's generally recommended to use the plugin, as interactive search functionality
+is a vital part of every good documentation. Additionally, the plugin integrates
+perfectly with several of the other [built-in plugins] that Material for MkDocs
+offers:
+
+<div class="grid cards" markdown>
+
+-   :material-connection: &nbsp; __[Built-in offline plugin][offline]__
+
+    ---
+
+    The offline plugin adds support for building offline-capable documentation,
+    so you can distribute the [`site` directory][mkdocs.site_dir] as a `.zip`
+    file that can be downloaded.
+
+    ---
+
+    __Your documentation can work without connectivity to the internet__
+
+-   :material-file-tree: &nbsp; __[Built-in meta plugin][meta]__
+
+    ---
+
+    The meta plugin makes it easy to [boost][meta.search.boost] specific
+    sections in search results or to [exclude][meta.search.exclude] them
+    entirely from being indexed, giving more granular control over search.
+
+    ---
+
+    __Simpler organization and management of search in different subsections__
+
+</div>
+
+  [offline]: offline.md
+  [meta]: meta.md
+  [built-in plugins]: index.md
+
+## Configuration
+
+<!-- md:version 9.0.0 -->
+<!-- md:plugin [search] – built-in -->
+
+As with all [built-in plugins], getting started with the search plugin is
+straightforward. Just add the following lines to `mkdocs.yml`, and your users
+will be able to search your documentation:
+
+``` yaml
+plugins:
+  - search
+```
+
+The search plugin is built into Material for MkDocs and doesn't need to be
+installed.
+
+  [search]: search.md
+  [built-in plugins]: index.md
+
+### General
+
+The following settings are available:
+
+---
+
+#### <!-- md:setting config.enabled -->
+
+<!-- md:version 9.2.9 -->
+<!-- md:default `true` -->
+
+Use this setting to enable or disable the plugin when [building your project].
+It's normally not necessary to specify this setting, but if you want to disable
+the plugin, use:
+
+``` yaml
+plugins:
+  - search:
+      enabled: false
+```
+
+  [building your project]: ../creating-your-site.md#building-your-site
+
+### Search
+
+The following settings are available for search:
+
+---
+
+#### <!-- md:setting config.lang -->
+
+<!-- md:version 9.0.0 -->
+<!-- md:default computed -->
+
+Use this setting to specify the language of the search index, enabling [stemming]
+support for other languages than English. The default value is automatically
+computed from the [site language], but can be explicitly set to another language
+or even multiple languages with:
+
+=== "Set language"
+
+    ``` yaml
+    plugins:
+      - search:
+          lang: en
+    ```
+
+=== "Add further languages"
+
+    ``` yaml
+    plugins:
+      - search:
+          lang: # (1)!
+            - en
+            - de
+    ```
+
+    1.  Be aware that including support for further languages increases the
+        base JavaScript payload by around 20kb and by another 15-30kb per
+        language, all before `gzip`.
+
+  [stemming]: https://en.wikipedia.org/wiki/Stemming
+  [site language]: ../setup/changing-the-language.md#site-language
+  [lunr languages]: https://github.com/MihaiValentin/lunr-languages
+
+Language support is provided by [lunr languages], a collection of
+language-specific stemmers and stop words for [lunr.js] maintained by the
+Open Source community.
+
+---
+
+The following languages are currently supported by [lunr languages]:
+
+<div class="mdx-columns" markdown>
+
+- `ar` – Arabic
+- `da` – Danish
+- `de` – German
+- `du` – Dutch
+- `en` – English
+- `es` – Spanish
+- `fi` – Finnish
+- `fr` – French
+- `hi` – Hindi
+- `hu` – Hungarian
+- `hy` – Armenian
+- `it` – Italian
+- `ja` – Japanese
+- `kn` - Kannada
+- `ko` – Korean
+- `no` – Norwegian
+- `pt` – Portuguese
+- `ro` – Romanian
+- `ru` – Russian
+- `sa` – Sanskrit
+- `sv` – Swedish
+- `ta` – Tamil
+- `te` – Telugu
+- `th` – Thai
+- `tr` – Turkish
+- `vi` – Vietnamese
+- `zh` – Chinese
+
+</div>
+
+If [lunr languages] doesn't provide support for the selected [site language],
+the plugin falls back to another language that yields the best stemming results.
+If you discover that the search results are not satisfactory, you can contribute
+to [lunr languages] by adding support for your language.
+
+---
+
+#### <!-- md:setting config.separator -->
+
+<!-- md:version 9.0.0 -->
+<!-- md:default computed -->
+
+Use this setting to specify the separator used to split words when building the
+search index on the client side. The default value is automatically computed
+from the [site language], but can also be explicitly set to another value with:
+
+``` yaml
+plugins:
+  - search:
+      separator: '[\s\-,:!=\[\]()"/]+|(?!\b)(?=[A-Z][a-z])|\.(?!\d)|&[lg]t;'
+```
+
+Separators support [positive and negative lookahead assertions], which allows
+for rather complex expressions that yield precise control over how words are
+split when building the search index.
+
+Broken into its parts, this separator induces the following behavior:
+
+=== "Special characters"
+
+    ```
+    [\s\-,:!=\[\]()"/]+
+    ```
+
+    The first part of the expression inserts token boundaries for each
+    document before and after whitespace, hyphens, commas, brackets and
+    other special characters. If several of those special characters are
+    adjacent, they are treated as one.
+
+=== "Case changes"
+
+    ```
+    (?!\b)(?=[A-Z][a-z])
+    ```
+
+    Many programming languages have naming conventions like `PascalCase` or
+    `camelCase`. By adding this subexpression to the separator,
+    [words are split at case changes], tokenizing the word `PascalCase`
+    into `Pascal` and `Case`.
+
+=== "Version strings"
+
+    ```
+    \.(?!\d)
+    ```
+
+    When adding `.` to the separator, version strings like `1.2.3` are split
+    into `1`, `2` and `3`, which makes them undiscoverable via search. When
+    using this subexpression, a small lookahead is introduced which will
+    [preserve version strings] and keep them discoverable.
+
+=== "HTML/XML tags"
+
+    ```
+    &[lg]t;
+    ```
+
+    If your documentation includes HTML/XML code examples, you may want to allow
+    users to find [specific tag names]. Unfortunately, the `<` and `>` control
+    characters are encoded in code blocks as `&lt;` and `&gt;`. Adding this
+    subexpression to the separator allows for just that.
+
+  [positive and negative lookahead assertions]: https://www.regular-expressions.info/lookaround.html
+  [words are split at case changes]: ?q=searchHighlight
+  [preserve version strings]: ?q=9.0.0
+  [specific tag names]: ?q=script
+
+---
+
+#### <!-- md:setting config.pipeline -->
+
+<!-- md:version 9.0.0 -->
+<!-- md:default computed -->
+<!-- md:flag experimental -->
+
+Use this setting to specify the [pipeline functions] that are used to filter and
+expand tokens after tokenizing them with the [`separator`][config.separator] and
+before adding them to the search index. The default value is automatically
+computed from the [site language], but can also be explicitly set with:
+
+``` yaml
+plugins:
+  - search:
+      pipeline:
+        - stemmer
+        - stopWordFilter
+        - trimmer
+```
+
+The following pipeline functions can be used:
+
+- `stemmer` – Stem tokens to their root form, e.g. `running` to `run`
+- `stopWordFilter` – Filter common words according, e.g. `a`, `the`, etc.
+- `trimmer` – Trim whitespace from tokens
+
+  [pipeline functions]: https://lunrjs.com/guides/customising.html#pipeline-functions
+
+### Segmentation
+
+The plugin supports text segmentation of Chinese via [jieba], a popular
+Chinese text segmentation library. Other languages like Japanese and Korean are
+currently segmented on the client side, but we're considering to move this
+functionality into the plugin in the future.
+
+The following settings are available for segmentation:
+
+  [jieba]: https://pypi.org/project/jieba/
+
+---
+
+#### <!-- md:setting config.jieba_dict -->
+
+<!-- md:version 9.2.0 -->
+<!-- md:default none -->
+<!-- md:flag experimental -->
+
+Use this setting to specify a [custom dictionary] to be used by [jieba] for
+segmenting text, replacing the default dictionary. [jieba] comes with
+several dictionaries, which can be used with:
+
+``` yaml
+plugins:
+  - search:
+      jieba_dict: dict.txt
+```
+
+The following dictionaries are provided by [jieba]:
+
+- [dict.txt.small] – 占用内存较小的词典文件
+- [dict.txt.big] – 支持繁体分词更好的词典文件
+
+The provided path is resolved from the root directory.
+
+  [custom dictionary]: https://github.com/fxsjy/jieba#%E5%85%B6%E4%BB%96%E8%AF%8D%E5%85%B8
+  [dict.txt.small]: https://github.com/fxsjy/jieba/raw/master/extra_dict/dict.txt.small
+  [dict.txt.big]: https://github.com/fxsjy/jieba/raw/master/extra_dict/dict.txt.big
+
+---
+
+#### <!-- md:setting config.jieba_dict_user -->
+
+<!-- md:version 9.2.0 -->
+<!-- md:default none -->
+<!-- md:flag experimental -->
+
+Use this setting to specify an additional [user dictionary] to be used by
+[jieba] for segmenting text, augmenting the default dictionary. User
+dictionaries are ideal for tuning the segmenter:
+
+``` yaml
+plugins:
+  - search:
+      jieba_dict_user: user_dict.txt
+```
+
+The provided path is resolved from the root directory.
+
+  [user dictionary]: https://github.com/fxsjy/jieba#%E8%BD%BD%E5%85%A5%E8%AF%8D%E5%85%B8
+
+## Usage
+
+### Metadata
+
+The following properties are available:
+
+---
+
+#### <!-- md:setting meta.search.boost -->
+
+<!-- md:version 8.3.0 -->
+<!-- md:flag metadata -->
+<!-- md:default none -->
+
+Use this property to increase or decrease the relevance of a page in the search
+results, giving more weight to them. Use values above `1` to rank up and values
+below `1` to rank down:
+
+=== ":material-arrow-up-circle: Rank up"
+
+    ``` yaml
+    ---
+    search:
+      boost: 2 # (1)!
+    ---
+
+    # Page title
+    ...
+    ```
+
+    1.  When boosting pages, always start with low values.
+
+=== ":material-arrow-down-circle: Rank down"
+
+    ``` yaml
+    ---
+    search:
+      boost: 0.5
+    ---
+
+    # Page title
+    ...
+    ```
+
+---
+
+#### <!-- md:setting meta.search.exclude -->
+
+<!-- md:version 9.0.0 -->
+<!-- md:flag metadata -->
+<!-- md:default none -->
+
+Use this property to exclude a page from the search results. Note that this will
+not only remove the page, but also all subsections of the page from the search
+results:
+
+``` yaml
+---
+search:
+  exclude: true
+---
+
+# Page title
+...
+```

docs/plugins/tags.md

@@ -0,0 +1,376 @@
+---
+title: Built-in tags plugin
+icon: material/tag-text
+---
+
+# Built-in tags plugin
+
+The tags plugin adds first-class support for categorizing pages with the use
+of tags, adding the possibility to group related pages and make them
+discoverable via search and dedicated tags indexes. If your documentation is
+large, tags can help to discover relevant information faster.
+
+## Objective
+
+### How it works
+
+The plugin scans all pages for the [`tags`][meta.tags] metadata property and
+generates a tags index, which is an inverted list of tags and the pages they
+appear on. The tags index can be located anywhere in the [`nav`][mkdocs.nav],
+allowing for maximum flexibility when adding tags to your project.
+
+### When to use it
+
+If you want to add one or multiple tags indexes to your project, the tags
+plugin is a perfect choice as it makes this process ridiculously simple.
+Additionally, it integrates perfectly with several of the other
+[built-in plugins] that Material for MkDocs offers:
+
+<div class="grid cards" markdown>
+
+-   :material-file-tree: &nbsp; __[Built-in meta plugin][meta]__
+
+    ---
+
+    The meta plugin makes it possible to ensure that subsections of your
+    project are annotated with [specific tags][meta.tags], so they can't be
+    forgotten when adding pages.
+
+    ---
+
+    __Simpler organization and management of tags in different subsections__
+
+-   :material-newspaper-variant-outline: &nbsp; __[Built-in blog plugin][blog]__
+
+    ---
+
+    The tags plugin allows to categorize posts alongside with pages in your
+    project, to improve their discoverability and connect posts to your
+    documentation.
+
+    ---
+
+    __Your documentation's tag system integrates with your blog__
+
+</div>
+
+  [meta]: meta.md
+  [blog]: blog.md
+  [built-in plugins]: index.md
+
+## Configuration
+
+<!-- md:version 8.2.0 -->
+<!-- md:plugin [tags] – built-in -->
+<!-- md:flag multiple -->
+
+As with all [built-in plugins], getting started with the tags plugin is
+straightforward. Just add the following lines to `mkdocs.yml`, and start using
+[tags][meta.tags] to categorize your pages:
+
+``` yaml
+plugins:
+  - tags
+```
+
+The tags plugin is built into Material for MkDocs and doesn't need to be
+installed.
+
+  [tags]: tags.md
+
+### General
+
+The following settings are available:
+
+---
+
+#### <!-- md:setting config.enabled -->
+
+<!-- md:version 9.1.7 -->
+<!-- md:default `true` -->
+
+Use this setting to enable or disable the plugin when [building your project].
+It's normally not necessary to specify this setting, but if you want to disable
+the plugin, use:
+
+``` yaml
+plugins:
+  - tags:
+      enabled: false
+```
+
+  [building your project]: ../creating-your-site.md#building-your-site
+
+### Tags
+
+The following settings are available for tags:
+
+---
+
+#### <!-- md:setting config.tags -->
+
+<!-- md:version 9.2.9 -->
+<!-- md:default `true` -->
+
+Use this setting to enable or disable handling of tags. Currently, the plugin's
+sole purpose is to process tags, so it's equivalent to the [`enabled`]
+[config.enabled] setting, but in the future, other features might be added.
+If you want to disable handling of tags, use:
+
+``` yaml
+plugins:
+  - tags:
+      tags: false
+```
+
+---
+
+#### <!-- md:setting config.tags_file -->
+
+<!-- md:version 8.2.0 -->
+<!-- md:default none -->
+
+Use this setting to specify the location of the tags index, which is the page
+used to render a list of all tags and their associated pages. If this setting is
+specified, tags become clickable, pointing to the corresponding section in the
+tags index:
+
+``` yaml
+plugins:
+  - tags:
+      tags_file: tags.md
+```
+
+The page holding the tags index can be linked anywhere in the [`nav`][mkdocs.nav]
+section of `mkdocs.yml`. This setting is not required – you should only use it
+if you want to have a tags index.
+
+The provided path is resolved from the [`docs` directory][mkdocs.docs_dir].
+
+---
+
+#### <!-- md:setting config.tags_extra_files -->
+
+<!-- md:sponsors -->
+<!-- md:version insiders-4.20.0 -->
+<!-- md:default none -->
+
+Use this setting to specify the locations of additional tags indexes, which are
+pages that render a subset of the tags index, in order to provide scoped tags
+indexes for specific sections:
+
+``` yaml
+plugins:
+  - tags:
+      tags_extra_files:
+        extra-1.md: [tag-id-1, tag-id-2, ...]
+        extra-2.md: [tag-id-3, tag-id-4, ...]
+        ...
+```
+
+The provided path is resolved from the [`docs` directory][mkdocs.docs_dir].
+
+---
+
+#### <!-- md:setting config.tags_slugify -->
+
+<!-- md:sponsors -->
+<!-- md:version insiders-4.25.0 -->
+<!-- md:default [`toc.slugify`][toc.slugify] -->
+
+Use this setting to change the function to use for generating URL-compatible
+slugs from tags. [Python Markdown Extensions] comes with a Unicode-aware
+[`slugify`][pymdownx.slugs.slugify] function:
+
+=== "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
+    ```
+
+When your project features non-European languages, it's advisable to use this
+configuration. Of course, you can also provide a custom slugification function
+for more granular control.
+
+  [toc.slugify]: https://github.com/Python-Markdown/markdown/blob/1337d0891757e192165668d2606db36cf08e65a9/markdown/extensions/toc.py#L26-L33
+  [pymdownx.slugs.slugify]: https://github.com/facelessuser/pymdown-extensions/blob/01c91ce79c91304c22b4e3d7a9261accc931d707/pymdownx/slugs.py#L59-L65
+  [Python Markdown Extensions]: https://facelessuser.github.io/pymdown-extensions/extras/slugs/
+
+---
+
+#### <!-- md:setting config.tags_slugify_separator -->
+
+<!-- md:sponsors -->
+<!-- md:version insiders-4.25.0 -->
+<!-- md:default `-` -->
+
+Use this setting to change the separator that is passed to the slugification
+function set as part of [`tags_slugify`][config.tags_slugify]. While the default
+is a hyphen, it can be set to any string, e.g., `_`:
+
+``` yaml
+plugins:
+  - tags:
+      tags_slugify_separator: _
+```
+
+---
+
+#### <!-- md:setting config.tags_compare -->
+
+<!-- md:sponsors -->
+<!-- md:version insiders-4.26.2 -->
+<!-- md:default none -->
+
+Use this setting to specify a custom function for comparing tags. By default,
+tag comparison is case-sensitive, but you can use the `casefold` function
+for case-insensitive comparison:
+
+``` yaml
+plugins:
+  - tags:
+      tags_compare: !!python/name:material.plugins.tags.casefold
+```
+
+You can also define your own comparison function, which must return a string
+representing the tag, that is used for sorting, and reference it in
+[`tags_compare`][config.tags_compare].
+
+---
+
+#### <!-- md:setting config.tags_compare_reverse -->
+
+<!-- md:sponsors -->
+<!-- md:version insiders-4.26.2 -->
+<!-- md:default `false` -->
+
+Use this setting to reverse the order in which tags are sorted when comparing
+them. By default, tags are sorted in ascending order, but you can reverse
+ordering as follows:
+
+``` yaml
+plugins:
+  - tags:
+      tags_compare_reverse: true
+```
+
+---
+
+#### <!-- md:setting config.tags_pages_compare -->
+
+<!-- md:sponsors -->
+<!-- md:version insiders-4.39.0 -->
+<!-- md:default none -->
+
+Use this setting to specify a custom function for comparing pages. By default,
+pages occur in order of appearance, but you can sort them by using the following
+configuration:
+
+=== "Sort by page title"
+
+    ``` yaml
+    plugins:
+      - tags:
+          tags_pages_compare: !!python/name:material.plugins.tags.page_title
+    ```
+
+=== "Sort by page URL"
+
+    ``` yaml
+    plugins:
+      - tags:
+          tags_pages_compare: !!python/name:material.plugins.tags.page_url
+    ```
+
+You can also define your own comparison function, which must return a string
+representing the page, that is used for sorting, and reference it in
+[`tags_pages_compare`][config.tags_pages_compare].
+
+---
+
+#### <!-- md:setting config.tags_pages_compare_reverse -->
+
+<!-- md:sponsors -->
+<!-- md:version insiders-4.39.0 -->
+<!-- md:default `false` -->
+
+Use this setting to reverse the order in which pages are sorted when comparing
+them. By default, pages are sorted in ascending order, but you can reverse
+ordering as follows:
+
+``` yaml
+plugins:
+  - tags:
+      tags_pages_compare_reverse: true
+```
+
+---
+
+#### <!-- md:setting config.tags_allowed -->
+
+<!-- md:sponsors -->
+<!-- md:version insiders-4.25.0 -->
+<!-- md:default none -->
+
+The plugin allows to check tags against a predefined list, in order to catch
+typos or make sure that tags are not arbitrarily added. Specify the tags you
+want to allow with:
+
+``` yaml
+plugins:
+  - tags:
+      tags_allowed:
+        - HTML5
+        - JavaScript
+        - CSS
+```
+
+The plugin stops the build if a page references a tag that is not part of
+this list. Pages can be assigned to tags by using the [`tags`][meta.tags]
+metadata property.
+
+## Usage
+
+### Metadata
+
+The following properties are available:
+
+---
+
+#### <!-- md:setting meta.tags -->
+
+<!-- md:version 8.2.0 -->
+<!-- md:flag metadata -->
+<!-- md:default none -->
+
+Use this property to associate a page with one or more tags, making the page
+appear in the generated tags index. Tags are defined as a list of strings
+(whitespaces are allowed):
+
+``` yaml
+---
+tags:
+  - HTML5
+  - JavaScript
+  - CSS
+---
+
+# Page title
+...
+```
+
+If you want to prevent accidental typos when assigning tags to pages, you can
+set a predefined list of allowed tags in `mkdocs.yml` by using the
+[`tags_allowed`][config.tags_allowed] setting.

docs/plugins/typeset.md

@@ -0,0 +1,82 @@
+---
+title: Built-in typeset plugin
+icon: material/format-title
+---
+
+# Built-in typeset plugin
+
+The typeset plugin allows to preserve the enriched presentation of titles and
+headlines within the navigation and table of contents. This means that code
+blocks, icons, emojis and any other inline formatting can be rendered exactly
+as defined in the page's content.
+
+## Objective
+
+### How it works
+
+When [building your project], MkDocs extracts the plain text from headlines and
+drops the original formatting. This is generally useful and a good idea, since
+this information is made available to other plugins that might have problems
+when being passed HTML instead of plain text.
+
+However, it also means that the entire formatting is lost.
+
+The plugin hooks into the rendering process, extracts the original headlines,
+and makes them available to be used in templates and plugins. The templates of
+Material for MkDocs use this information to render an enriched version of the
+navigation and table of contents.
+
+  [building your project]: ../creating-your-site.md#building-your-site
+
+### When to use it
+
+It's generally recommended to use the plugin, because it is a drop-in solution
+that doesn't require any configuration and is designed to work out of the box.
+Since it doesn't overwrite but only adds information, it's not expected to
+interfere with other plugins.
+
+## Configuration
+
+<!-- md:sponsors -->
+<!-- md:version insiders-4.27.0 -->
+<!-- md:plugin [typeset] – built-in -->
+<!-- md:flag experimental -->
+
+As with all [built-in plugins], getting started with the typeset plugin is
+straightforward. Just add the following lines to `mkdocs.yml`, and observe the
+enriched navigation and table of contents:
+
+``` yaml
+plugins:
+  - typeset
+```
+
+The typeset plugin is built into Material for MkDocs and doesn't need to be
+installed.
+
+  [typeset]: typeset.md
+  [built-in plugins]: index.md
+
+### General
+
+The following settings are available:
+
+---
+
+#### <!-- md:setting config.enabled -->
+
+<!-- md:sponsors -->
+<!-- md:version insiders-4.27.0 -->
+<!-- md:default `true` -->
+
+Use this setting to enable or disable the plugin when [building your project].
+It's normally not necessary to specify this setting, but if you want to disable
+the plugin, use:
+
+``` yaml
+plugins:
+  - typeset:
+      enabled: false
+```
+
+  [building your project]: ../creating-your-site.md#building-your-site

docs/reference/admonitions.md

@@ -34,7 +34,7 @@ See additional configuration options:
 
 ### Admonition icons
 
-[:octicons-tag-24: 8.3.0][Admonition icons support]
+<!-- md:version 8.3.0 -->
 
 Each of the supported admonition types has a distinct icon, which can be changed
 to any icon bundled with the theme, or even a [custom icon]. Add the following
@@ -101,7 +101,6 @@ theme:
               quote: fontawesome/solid/quote-left
         ```
 
-  [Admonition icons support]: https://github.com/squidfunk/mkdocs-material/releases/tag/8.3.0
   [custom icon]: ../setup/changing-the-logo-and-icons.md#additional-icons
   [supported types]: #supported-types
   [icon search]: icons-emojis.md#search
@@ -291,7 +290,7 @@ the default type, and thus fallback for unknown type qualifiers, is `note`[^1]:
     type qualifiers are now all deprecated and will be removed in the next major
     version. This will also be mentioned in the upgrade guide.
 
-[`note`](#type:note){ #type:note }
+<!-- md:option type:note -->
 
 :   !!! note
 
@@ -299,7 +298,7 @@ the default type, and thus fallback for unknown type qualifiers, is `note`[^1]:
         euismod nulla. Curabitur feugiat, tortor non consequat finibus, justo
         purus auctor massa, nec semper lorem quam in massa.
 
-[`abstract`](#type:abstract){ #type:abstract }
+<!-- md:option type:abstract -->
 
 :   !!! abstract
 
@@ -307,7 +306,7 @@ the default type, and thus fallback for unknown type qualifiers, is `note`[^1]:
         euismod nulla. Curabitur feugiat, tortor non consequat finibus, justo
         purus auctor massa, nec semper lorem quam in massa.
 
-[`info`](#type:info){ #type:info }
+<!-- md:option type:info -->
 
 :   !!! info
 
@@ -315,7 +314,7 @@ the default type, and thus fallback for unknown type qualifiers, is `note`[^1]:
         euismod nulla. Curabitur feugiat, tortor non consequat finibus, justo
         purus auctor massa, nec semper lorem quam in massa.
 
-[`tip`](#type:tip){ #type:tip }
+<!-- md:option type:tip -->
 
 :   !!! tip
 
@@ -323,7 +322,7 @@ the default type, and thus fallback for unknown type qualifiers, is `note`[^1]:
         euismod nulla. Curabitur feugiat, tortor non consequat finibus, justo
         purus auctor massa, nec semper lorem quam in massa.
 
-[`success`](#type:success){ #type:success }
+<!-- md:option type:success -->
 
 :   !!! success
 
@@ -331,7 +330,7 @@ the default type, and thus fallback for unknown type qualifiers, is `note`[^1]:
         euismod nulla. Curabitur feugiat, tortor non consequat finibus, justo
         purus auctor massa, nec semper lorem quam in massa.
 
-[`question`](#type:question){ #type:question }
+<!-- md:option type:question -->
 
 :   !!! question
 
@@ -339,7 +338,7 @@ the default type, and thus fallback for unknown type qualifiers, is `note`[^1]:
         euismod nulla. Curabitur feugiat, tortor non consequat finibus, justo
         purus auctor massa, nec semper lorem quam in massa.
 
-[`warning`](#type:warning){ #type:warning }
+<!-- md:option type:warning -->
 
 :   !!! warning
 
@@ -347,7 +346,7 @@ the default type, and thus fallback for unknown type qualifiers, is `note`[^1]:
         euismod nulla. Curabitur feugiat, tortor non consequat finibus, justo
         purus auctor massa, nec semper lorem quam in massa.
 
-[`failure`](#type:failure){ #type:failure }
+<!-- md:option type:failure -->
 
 :   !!! failure
 
@@ -355,7 +354,7 @@ the default type, and thus fallback for unknown type qualifiers, is `note`[^1]:
         euismod nulla. Curabitur feugiat, tortor non consequat finibus, justo
         purus auctor massa, nec semper lorem quam in massa.
 
-[`danger`](#type:danger){ #type:danger }
+<!-- md:option type:danger -->
 
 :   !!! danger
 
@@ -363,7 +362,7 @@ the default type, and thus fallback for unknown type qualifiers, is `note`[^1]:
         euismod nulla. Curabitur feugiat, tortor non consequat finibus, justo
         purus auctor massa, nec semper lorem quam in massa.
 
-[`bug`](#type:bug){ #type:bug }
+<!-- md:option type:bug -->
 
 :   !!! bug
 
@@ -371,7 +370,7 @@ the default type, and thus fallback for unknown type qualifiers, is `note`[^1]:
         euismod nulla. Curabitur feugiat, tortor non consequat finibus, justo
         purus auctor massa, nec semper lorem quam in massa.
 
-[`example`](#type:example){ #type:example }
+<!-- md:option type:example -->
 
 :   !!! example
 
@@ -379,7 +378,7 @@ the default type, and thus fallback for unknown type qualifiers, is `note`[^1]:
         euismod nulla. Curabitur feugiat, tortor non consequat finibus, justo
         purus auctor massa, nec semper lorem quam in massa.
 
-[`quote`](#type:quote){ #type:quote }
+<!-- md:option type:quote -->
 
 :   !!! quote
 
@@ -391,8 +390,8 @@ the default type, and thus fallback for unknown type qualifiers, is `note`[^1]:
 
 ### Classic admonitions
 
-Prior to version [:octicons-tag-24: 8.5.6][Admonition modern], admonitions had
+Prior to version <!-- md:version 8.5.6 -->, admonitions had a slightly
-a slightly different appearance:
+different appearance:
 
 !!! classic "Note"
 
@@ -427,8 +426,6 @@ If you want to restore this appearance, add the following CSS to an
       - stylesheets/extra.css
     ```
 
-[Admonition modern]: https://github.com/squidfunk/mkdocs-material/releases/tag/8.5.6
-
 ### Custom admonitions
 
 If you want to add a custom admonition type, all you need is a color and an

docs/reference/annotations.md

@@ -33,7 +33,7 @@ See additional configuration options:
 
 ### Annotation icons
 
-[:octicons-tag-24: 9.2.0][Annotation icons support]
+<!-- md:version 9.2.0 -->
 
 The annotation icon can be changed to any icon bundled with the theme, or even
 a [custom icon], e.g. to material/arrow-right-circle:. Simply add the following
@@ -67,7 +67,6 @@ Some popular choices:
 - :material-star-four-points-circle: - `material/star-four-points-circle`
 - :material-plus-circle-outline: - `material/plus-circle-outline`
 
-  [Annotation icons support]: https://github.com/squidfunk/mkdocs-material/releases/tag/9.2.0
   [custom icon]: ../setup/changing-the-logo-and-icons.md#additional-icons
   [icon search]: icons-emojis.md#search
 
@@ -75,8 +74,8 @@ Some popular choices:
 
 ### Using annotations
 
-[:octicons-tag-24: 9.2.0][Annotation support] ·
+<!-- md:version 9.2.0 -->
-:octicons-beaker-24: Experimental
+<!-- md:flag experimental -->
 
 Annotations consist of two parts: a marker, which can be placed anywhere in
 a block marked with the `annotate` class, and content located in a list below
@@ -104,8 +103,6 @@ Note that the `annotate` class must only be added to the outermost block. All
 nested elements can use the same list to define annotations, except when
 annotations are nested themselves.
 
-  [Annotation support]: https://github.com/squidfunk/mkdocs-material/releases/tag/9.2.0
-
 #### in annotations
 
 When [SuperFences] is enabled, annotations can be nested inside annotations by
@@ -208,7 +205,7 @@ of a dedicated content tab (and not to the container, which is not supported):
 
 #### in everything else
 
-The [Attribute Lists] extension is the key ingredient for adding annotations to 
+The [Attribute Lists] extension is the key ingredient for adding annotations to
 most elements, but it has some [limitations]. However, it's always possible to
 leverage the [Markdown in HTML] extension to wrap arbitrary elements with a
 `div` with the `annotate` class:

docs/reference/code-blocks.md

@@ -13,8 +13,8 @@ during runtime using a JavaScript syntax highlighter.
 
 ## Configuration
 
-This configuration enables syntax highlighting on code blocks and inline code 
+This configuration enables syntax highlighting on code blocks and inline code
-blocks, and allows to include source code directly from other files. Add the 
+blocks, and allows to include source code directly from other files. Add the
 following lines to `mkdocs.yml`:
 
 ``` yaml
@@ -46,8 +46,8 @@ See additional configuration options:
 
 ### Code copy button
 
-[:octicons-tag-24: 9.0.0][Code copy button support] ·
+<!-- md:version 9.0.0 -->
-:octicons-unlock-24: Feature flag
+<!-- md:feature -->
 
 Code blocks can automatically render a button on the right side to allow the
 user to copy a code block's contents to the clipboard. Add the following to
@@ -59,8 +59,6 @@ theme:
     - content.code.copy
 ```
 
-  [Code copy button support]: https://github.com/squidfunk/mkdocs-material/releases/tag/9.0.0
-
 ??? info "Enabling or disabling code copy buttons for a specific code block"
 
     If you don't want to enable code copy buttons globally, you can enable them
@@ -73,7 +71,7 @@ theme:
     ```
     ````
 
-    Note that the language shortcode which has to come first must now also be 
+    Note that the language shortcode which has to come first must now also be
     prefixed by a `.`. Similarly, the copy button can also be disabled for a
     specific code block:
 
@@ -85,9 +83,9 @@ theme:
 
 ### Code selection button
 
-[:octicons-heart-fill-24:{ .mdx-heart } Sponsors only][Insiders]{ .mdx-insiders } ·
+<!-- md:sponsors -->
-[:octicons-tag-24: insiders-4.32.0][Insiders] ·
+<!-- md:version insiders-4.32.0 -->
-:octicons-beaker-24: Experimental
+<!-- md:flag experimental -->
 
 Code blocks can include a button to allow for the selection of line ranges by
 the user, which is perfect for linking to a specific subsection of a code block. This allows the user to apply [line highlighting] dynamically. Add the following
@@ -101,8 +99,8 @@ theme:
 
 ??? info "Enabling or disabling code selection buttons for a specific code block"
 
-    If you don't want to enable code selection buttons globally, you can enable 
+    If you don't want to enable code selection buttons globally, you can enable
-    them for a specific code block by using a slightly different syntax based on 
+    them for a specific code block by using a slightly different syntax based on
     the [Attribute Lists] extension:
 
     ```` yaml
@@ -111,7 +109,7 @@ theme:
     ```
     ````
 
-    Note that the language shortcode which has to come first must now also be 
+    Note that the language shortcode which has to come first must now also be
     prefixed by a `.`. Similarly, the selection button can also be disabled for
     a specific code block:
 
@@ -121,13 +119,12 @@ theme:
     ```
     ````
 
-  [Insiders]: ../insiders/index.md
   [line highlighting]: #highlighting-specific-lines
 
 ### Code annotations
 
-[:octicons-tag-24: 8.0.0][Code annotations support] ·
+<!-- md:version 8.0.0 -->
-:octicons-unlock-24: Feature flag
+<!-- md:feature -->
 
 Code annotations offer a comfortable and friendly way to attach arbitrary
 content to specific sections of code blocks by adding numeric markers in block
@@ -156,21 +153,20 @@ theme:
     ```
     ````
 
-    Note that the language shortcode which has to come first must now also be 
+    Note that the language shortcode which has to come first must now also be
     prefixed by a `.`.
 
-  [Code annotations support]: https://github.com/squidfunk/mkdocs-material/releases/tag/8.0.0
   [Attribute Lists]: ../setup/extensions/python-markdown.md#attribute-lists
 
 #### Custom selectors
 
-[:octicons-heart-fill-24:{ .mdx-heart } Sponsors only][Insiders]{ .mdx-insiders } ·
+<!-- md:sponsors -->
-[:octicons-tag-24: insiders-4.32.0][Insiders] ·
+<!-- md:version insiders-4.32.0 -->
-:octicons-beaker-24: Experimental
+<!-- md:flag experimental -->
 
 Normally, code annotations can only be [placed in comments], as comments can be
 considered safe for placement. However, sometimes it might be necessary to place
-annotations in parts of the code block where comments are not allowed, e.g. in 
+annotations in parts of the code block where comments are not allowed, e.g. in
 strings.
 
 Additional selectors can be set per-language:
@@ -292,8 +288,8 @@ theme:
 
 #### Stripping comments
 
-[:octicons-tag-24: 8.5.0][Stripping comments support] ·
+<!-- md:version 8.5.0 -->
-:octicons-beaker-24: Experimental
+<!-- md:flag experimental -->
 
 If you wish to strip the comment characters surrounding a code annotation,
 simply add an `!` after the closing parenthesis of the code annotation:
@@ -320,8 +316,6 @@ Note that this only allows for a single code annotation to be rendered per
 comment. If you want to add multiple code annotations, comments cannot be
 stripped for technical reasons.
 
-  [Stripping comments support]: https://github.com/squidfunk/mkdocs-material/releases/tag/8.5.0
-
 ### Adding line numbers
 
 Line numbers can be added to a code block by using the `linenums="<start>"`
@@ -552,12 +546,11 @@ This will render annotations with a larger width:
 
 ### Annotations with numbers
 
-Prior to [:octicons-tag-24: 8.1.0][code annotation markers], code annotations
+Prior to <!-- md:version 8.1.0 -->, code annotations were rendered with markers
-were rendered with markers showing the original number as used by the author.
+showing the original number as used by the author. However, for technical
-However, for technical reasons code annotation numbers restart each code block,
+reasons code annotation numbers restart each code block, which might lead to
-which might lead to confusion. For this reason, code annotations now render as
+confusion. For this reason, code annotations now render as `+` signs which are
-`+` signs which are rotated if they're open to denote that clicking them again
+rotated if they're open to denote that clicking them again will close them.
-will close them.
 
 If you wish to revert to the prior behavior and display code annotation numbers,
 you can add an [additional style sheet] and copy and paste the following CSS:
@@ -579,5 +572,3 @@ you can add an [additional style sheet] and copy and paste the following CSS:
     extra_css:
       - stylesheets/extra.css
     ```
-
-  [code annotation markers]: https://github.com/squidfunk/mkdocs-material/releases/tag/8.1.0

docs/reference/content-tabs.md

@@ -12,14 +12,14 @@ grouping code blocks and other content.
 ## Configuration
 
 This configuration enables content tabs, and allows to nest arbitrary content
-inside content tabs, including code blocks and ... more content tabs! Add the 
+inside content tabs, including code blocks and ... more content tabs! Add the
 following lines to `mkdocs.yml`:
 
 ``` yaml
 markdown_extensions:
   - pymdownx.superfences
   - pymdownx.tabbed:
-      alternate_style: true 
+      alternate_style: true
 ```
 
 See additional configuration options:
@@ -32,9 +32,9 @@ See additional configuration options:
 
 ### Anchor links
 
-[:octicons-heart-fill-24:{ .mdx-heart } Sponsors only][Insiders]{ .mdx-insiders } ·
+<!-- md:sponsors -->
-[:octicons-tag-24: insiders-4.17.0][Insiders] ·
+<!-- md:version insiders-4.17.0 -->
-:octicons-beaker-24: Experimental
+<!-- md:flag experimental -->
 
 In order to link to content tabs and share them more easily, [Insiders] adds
 an anchor link to each content tab automatically, which you can copy via right
@@ -66,7 +66,6 @@ or to the [publishing guide for Insiders][tab_2].
 
     Fore more information, please [see the extension guide][slugification].
 
-  [Insiders]: ../insiders/index.md
   [tab_1]: #-or-even-me
   [tab_2]: ../publishing-your-site.md#insiders
   [Python Markdown Extensions]: https://facelessuser.github.io/pymdown-extensions/
@@ -74,11 +73,11 @@ or to the [publishing guide for Insiders][tab_2].
 
 ### Linked content tabs
 
-[:octicons-tag-24: 8.3.0][Linked content tabs support] ·
+<!-- md:version 8.3.0 -->
-:octicons-unlock-24: Feature flag
+<!-- md:feature -->
 
 When enabled, all content tabs across the whole documentation site will be
-linked and switch to the same label when the user clicks on a tab. Add the 
+linked and switch to the same label when the user clicks on a tab. Add the
 following lines to `mkdocs.yml`:
 
 ``` yaml
@@ -100,7 +99,6 @@ integrated with [instant loading] and persisted across page loads.
 
     [![Linked content tabs disabled]][Linked content tabs disabled]
 
-  [Linked content tabs support]: https://github.com/squidfunk/mkdocs-material/releases/tag/8.3.0
   [instant loading]: ../setup/setting-up-navigation.md#instant-loading
   [Linked content tabs enabled]: ../assets/screenshots/content-tabs-link.png
   [Linked content tabs disabled]: ../assets/screenshots/content-tabs.png

docs/reference/data-tables.md

@@ -10,7 +10,7 @@ like [sortable tables] can be achieved with a third-party library and some
 [additional JavaScript].
 
   [sortable tables]: #sortable-tables
-  [additional JavaScript]: ../customization.md#additional-javascript 
+  [additional JavaScript]: ../customization.md#additional-javascript
 
 ## Configuration
 
@@ -185,147 +185,7 @@ numbers, filesizes, dates and month names. See the [tablesort documentation]
 
 ### Import table from file
 
-[:octicons-cpu-24: Plugin][table-reader-docs]
+The plugin [mkdocs-table-reader-plugin][table-reader-docs] allows you to
+import data from a CSV or Excel file.
 
-You can also import data from a CSV or Excel file using the plugin [`mkdocs-table-reader-plugin`][table-reader-docs].
+  [table-reader-docs]: https://timvink.github.io/mkdocs-table-reader-plugin/
-
-First, you will need to install it with `pip`:
-
-```sh
-pip install mkdocs-table-reader-plugin
-```
-
-Then extend the `mkdocs.yml` file like this:
-
-```yaml
-plugins:
-  - table-reader
-```
-
-Then, it is a simple process to import the data in to the Markdown files.
-
-=== "Import data from :fontawesome-solid-file-csv: CSV file"
-    
-    Let's use a :fontawesome-solid-file-csv: CSV in the local directory. The file may look like this:
-
-    ```csv title="./data.csv"
-    col1,col2,col3
-    r1c1,r1c2,r1c3
-    r2c1,r2c2,r2c3
-    r3c1,r3c2,r3c3
-    ```
-
-    You can then add it to your :fontawesome-solid-file-arrow-down: Markdown page like this:
-
-    ```md title="./markdown.md"
-    ...
-
-    {{ read_csv('./data.csv') }}
-
-    ...
-    ```
-
-    <div class="result" markdown>
-
-    ...
-
-    col1|col2|col3
-    ----|----|----
-    r1c1|r1c2|r1c3
-    r2c1|r2c2|r2c3
-    r3c1|r3c2|r3c3
-
-    ...
-
-    </div>
-
-=== "Import data from :fontawesome-solid-file-excel: Excel file"
-      
-    Let's use an :fontawesome-solid-file-excel: Excel file in the local directory. The file may look like this:
-
-    ![][excel-file]{width="300px"}
-
-    [excel-file]: https://i.stack.imgur.com/f32ks.png
-
-    And you can add it to your :fontawesome-solid-file-arrow-down: Markdown page like this:
-
-    ```md title="./markdown.md"
-    ...
-
-    {{ read_excel('./Book1.xlsx', engine='openpyxl') }}
-
-    ...
-    ```
-
-    <div class="result" markdown>
-
-    It will then return a result like this:
-
-    col1|col2|col3
-    ----|----|----
-    r1c1|r1c2|r1c3
-    r2c1|r2c2|r2c3
-    r3c1|r3c2|r3c3
-
-    </div>
-
-    !!! warning "Warning"
-        
-        You may receive an error if you use `engine='openpyxl'`.
-
-        If this happens, you can resolve it by installing it using `pip`:
-
-        ```sh
-        pip install openpyxl
-        ```
-
-        Read more here: [pandas.read_excel][pandas-read_excel-engine]
-        
-        [pandas-read_excel-engine]: https://pandas.pydata.org/pandas-docs/stable/reference/api/pandas.read_excel.html#:~:text=enginestr%2C%20default%20None
-
-    !!! tip "Pro Tip: Multiple Sheets"
-
-        If your Excel file contains multiple sheets, you may want to extend the function by adding the `sheet_name` parameter.
-
-        It would look like this:
-
-        ```md title="./markdown.md"
-        ...
-
-        {{ read_excel('./Book1.xlsx', engine='openpyxl', sheet_name="Sheet1") }}
-
-        ...
-        ```
-
-        By default, Pandas will grab the first sheet in the workbook.
-
-        Read more here: [pandas.read_excel][pandas-read_excel-sheet_name]
-        
-        [pandas-read_excel-sheet_name]: https://pandas.pydata.org/pandas-docs/stable/reference/api/pandas.read_excel.html#:~:text=sheet_namestr%2C%20int%2C%20list%2C%20or%20None%2C%20default%200
-
-=== "Import data from other file types"
-
-    The plugin [`mkdocs-table-reader-plugin`][table-reader-docs] also provides readers for other formats:
-
-    <div class="mdx-columns" markdown>
-
-    - [`read_csv`][table-reader-read_csv]
-    - [`read_fwf`][table-reader-read_fwf]
-    - [`read_yaml`][table-reader-read_yaml]
-    - [`read_table`][table-reader-read_table]
-    - [`read_json`][table-reader-read_json]
-    - [`read_excel`][table-reader-read_excel]
-    - [`read_raw`][table-reader-read_raw]
-
-    </div>
-
-    You can read more on their Docs website: [mkdocs-table-reader-plugin][table-reader-docs]
-
-[table-reader-docs]: https://timvink.github.io/mkdocs-table-reader-plugin/
-[table-reader-read_csv]: https://timvink.github.io/mkdocs-table-reader-plugin/readers/#read_csv
-[table-reader-read_fwf]: https://timvink.github.io/mkdocs-table-reader-plugin/readers/#read_fwf
-[table-reader-read_yaml]: https://timvink.github.io/mkdocs-table-reader-plugin/readers/#read_yaml
-[table-reader-read_table]: https://timvink.github.io/mkdocs-table-reader-plugin/readers/#read_table
-[table-reader-read_json]: https://timvink.github.io/mkdocs-table-reader-plugin/readers/#read_json
-[table-reader-read_excel]: https://timvink.github.io/mkdocs-table-reader-plugin/readers/#read_excel
-[table-reader-read_raw]: https://timvink.github.io/mkdocs-table-reader-plugin/readers/#read_raw

docs/reference/diagrams.md

@@ -13,7 +13,7 @@ popular and flexible solution for drawing diagrams.
 
 ## Configuration
 
-[:octicons-tag-24: 8.2.0][Diagrams support]
+<!-- md:version 8.2.0 -->
 
 This configuration enables native support for [Mermaid.js] diagrams. Material
 for MkDocs will automatically initialize the JavaScript runtime when a page 
@@ -42,7 +42,6 @@ No further configuration is necessary. Advantages over a custom integration:
     diagrams. See the section on [other diagrams] for more information why this
     is currently not implemented for all diagrams.
 
-  [Diagrams support]: https://github.com/squidfunk/mkdocs-material/releases/tag/8.2.0
   [instant loading]: ../setup/setting-up-navigation.md#instant-loading
   [additional style sheets]: ../customization.md#additional-css
   [other diagrams]: #other-diagram-types

docs/reference/grids.md

@@ -45,15 +45,14 @@ elements in a rectangular shape.
 
 ### Using card grids
 
-[:octicons-heart-fill-24:{ .mdx-heart } Sponsors only][Insiders]{ .mdx-insiders } ·
+<!-- md:sponsors -->
-[:octicons-tag-24: insiders-4.12.0][Insiders] ·
+<!-- md:version insiders-4.12.0 -->
-:octicons-beaker-24: Experimental
+<!-- md:flag experimental -->
 
 Card grids wrap each grid item with a beautiful hover card that levitates on
 hover. They come in two slightly different syntaxes: [list] and [block syntax],
 adding support for distinct use cases.
 
-  [Insiders]: ../insiders/index.md
   [list]: #list-syntax
   [block syntax]: #block-syntax
 
@@ -98,7 +97,7 @@ includes icons and links:
 
     Install [`mkdocs-material`](#) with [`pip`](#) and get up
     and running in minutes
-    
+
     [:octicons-arrow-right-24: Getting started](#)
 
 -   :fontawesome-brands-markdown:{ .lg .middle } __It's just Markdown__
@@ -106,7 +105,7 @@ includes icons and links:
     ---
 
     Focus on your content and generate a responsive and searchable static site
-    
+
     [:octicons-arrow-right-24: Reference](#)
 
 -   :material-format-font:{ .lg .middle } __Made to measure__
@@ -114,7 +113,7 @@ includes icons and links:
     ---
 
     Change the colors, fonts, language, icons, logo and more with a few lines
-    
+
     [:octicons-arrow-right-24: Customization](#)
 
 -   :material-scale-balance:{ .lg .middle } __Open Source, MIT__
@@ -137,7 +136,7 @@ includes icons and links:
 
     Install [`mkdocs-material`][mkdocs-material] with [`pip`][pip] and get up
     and running in minutes
-    
+
     [:octicons-arrow-right-24: Getting started][getting started]
 
 -   :fontawesome-brands-markdown:{ .lg .middle } __It's just Markdown__
@@ -145,7 +144,7 @@ includes icons and links:
     ---
 
     Focus on your content and generate a responsive and searchable static site
-    
+
     [:octicons-arrow-right-24: Reference][reference]
 
 -   :material-format-font:{ .lg .middle } __Made to measure__
@@ -153,7 +152,7 @@ includes icons and links:
     ---
 
     Change the colors, fonts, language, icons, logo and more with a few lines
-    
+
     [:octicons-arrow-right-24: Customization][customization]
 
 -   :material-scale-balance:{ .lg .middle } __Open Source, MIT__
@@ -227,9 +226,9 @@ to the grid.
 
 ### Using generic grids
 
-[:octicons-heart-fill-24:{ .mdx-heart } Sponsors only][Insiders]{ .mdx-insiders } ·
+<!-- md:sponsors -->
-[:octicons-tag-24: insiders-4.12.0][Insiders] ·
+<!-- md:version insiders-4.12.0 -->
-:octicons-beaker-24: Experimental
+<!-- md:flag experimental -->
 
 Generic grids allow for arranging arbitrary block elements in a grid, including
 [admonitions], [code blocks], [content tabs] and more. Just wrap a set of blocks

docs/reference/images.md

@@ -4,8 +4,8 @@ icon: material/image-frame
 
 # Images
 
-While images are first-class citizens of Markdown and part of the core syntax, 
+While images are first-class citizens of Markdown and part of the core syntax,
-it can be difficult to work with them. Material for MkDocs makes working with 
+it can be difficult to work with them. Material for MkDocs makes working with
 images more comfortable, providing styles for image alignment and image
 captions.
 
@@ -31,10 +31,10 @@ See additional configuration options:
 
 ### Lightbox
 
-[:octicons-tag-24: 0.1.0][Lightbox support] ·
+<!-- md:version 0.1.0 -->
-[:octicons-cpu-24: Plugin][glightbox]
+<!-- md:plugin [glightbox] -->
 
-If you want to add image zoom functionality to your documentation, the 
+If you want to add image zoom functionality to your documentation, the
 [glightbox] plugin is an excellent choice, as it integrates perfectly
 with Material for MkDocs. Install it with `pip`:
 
@@ -52,7 +52,6 @@ plugins:
 We recommend checking out the available
 [configuration options][glightbox options].
 
-  [Lightbox support]: https://github.com/squidfunk/mkdocs-material/releases/tag/0.1.0
   [glightbox]: https://github.com/blueswen/mkdocs-glightbox
   [glightbox options]: https://github.com/blueswen/mkdocs-glightbox#usage
 
@@ -154,7 +153,7 @@ browsers without support:
 
 ### Light and dark mode
 
-[:octicons-tag-24: 8.1.1][Light and dark mode support]
+<!-- md:version 8.1.1 -->
 
 If you added a [color palette toggle] and want to show different images for
 light and dark color schemes, you can append a `#only-light` or `#only-dark`
@@ -200,7 +199,6 @@ hash fragment to the image URL:
     Remember to change `#!css "custom-light"` and `#!css "custom-dark"` to the
     name of your scheme.
 
-  [Light and dark mode support]: https://github.com/squidfunk/mkdocs-material/releases/tag/8.1.1
   [color palette toggle]: ../setup/changing-the-colors.md#color-palette-toggle
   [Zelda light world]: ../assets/images/zelda-light-world.png#only-light
   [Zelda dark world]: ../assets/images/zelda-dark-world.png#only-dark

docs/reference/index.md

@@ -9,10 +9,10 @@ within Markdown files.
 
 ### Built-in <u>typeset</u> plugin
 
-[:octicons-heart-fill-24:{ .mdx-heart } Sponsors only][Insiders]{ .mdx-insiders } ·
+<!-- md:sponsors -->
-[:octicons-tag-24: insiders-4.27.0][Insiders] ·
+<!-- md:version insiders-4.27.0 -->
-:octicons-cpu-24: Plugin ·
+<!-- md:plugin -->
-:octicons-beaker-24: Experimental
+<!-- md:flag experimental -->
 
 The built-in typeset plugin __preserves HTML formatting__ in the navigation and
 table of contents. This means that now, code blocks, icons, emojis and other
@@ -31,13 +31,13 @@ section headlines; even [highlighting inline code blocks] is supported :tada:
 
 ### Built-in meta plugin
 
-[:octicons-heart-fill-24:{ .mdx-heart } Sponsors only][Insiders]{ .mdx-insiders } ·
+<!-- md:sponsors -->
-[:octicons-tag-24: insiders-4.21.0][Insiders] ·
+<!-- md:version insiders-4.21.0 -->
-:octicons-cpu-24: Plugin ·
+<!-- md:plugin -->
-:octicons-beaker-24: Experimental
+<!-- md:flag 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 
+especially handy to ensure that all pages in a folder use specific templates or
 tags. Add the following lines to `mkdocs.yml`:
 
 ``` yaml
@@ -51,9 +51,9 @@ plugins:
 
 The following configuration options are available:
 
-[`meta_file`](#+meta.meta_file){ #+meta.meta_file }
+<!-- md:option meta.meta_file -->
 
-:   :octicons-milestone-24: Default: `.meta.yml` – This option specifies the
+:   <!-- md: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`:
 
@@ -73,9 +73,9 @@ The following configuration options are available:
 
 ### Setting the page `title`
 
-Each page has a designated title, which is used in the navigation sidebar, for 
+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 
+[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 
+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
@@ -83,7 +83,7 @@ explicitly set with the front matter `title` property:
 title: Lorem ipsum dolor sit amet # (1)!
 ---
 
-# Document title
+# Page title
 ...
 ```
 
@@ -101,7 +101,7 @@ title: Lorem ipsum dolor sit amet # (1)!
 ### Setting the page `description`
 
 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 
+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:
 
@@ -110,7 +110,7 @@ the author does not explicitly define a description for a Markdown file:
 description: Nullam urna elit, malesuada eget finibus ut, ac tortor. # (1)!
 ---
 
-# Document title
+# Page title
 ...
 ```
 
@@ -121,8 +121,8 @@ description: Nullam urna elit, malesuada eget finibus ut, ac tortor. # (1)!
 
 ### Setting the page `icon`
 
-[:octicons-tag-24: 9.2.0][Page icon support] ·
+<!-- md:version 9.2.0 -->
-:octicons-beaker-24: Experimental
+<!-- md:flag experimental -->
 
 An icon can be assigned to each page, which is then rendered as part of the
 navigation sidebar, as well as [navigation tabs], if enabled. Use the front
@@ -134,7 +134,7 @@ top of a Markdown file:
 icon: material/emoticon-happy # (1)!
 ---
 
-# Document title
+# Page title
 ...
 ```
 
@@ -149,18 +149,17 @@ icon: material/emoticon-happy # (1)!
       </div>
     </div>
 
-  [Page icon support]: https://github.com/squidfunk/mkdocs-material/releases/tag/9.2.0
   [Insiders]: ../insiders/index.md
   [icon search]: icons-emojis.md#search
   [navigation tabs]: ../setup/setting-up-navigation.md#navigation-tabs
 
 ### Setting the page `status`
 
-[:octicons-tag-24: 9.2.0][Page status support] ·
+<!-- md:version 9.2.0 -->
-:octicons-beaker-24: Experimental
+<!-- md:flag experimental -->
 
 A status can be assigned to each page, which is then displayed as part of the
-navigation sidebar. First, associate a status identifier with a description by 
+navigation sidebar. First, associate a status identifier with a description by
 adding the following to `mkdocs.yml`:
 
 ``` yaml
@@ -180,7 +179,7 @@ extra:
     ```
 
 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 
+example, you can mark a page as `new` with the following lines at the top of a
 Markdown file:
 
 ``` yaml
@@ -188,7 +187,7 @@ Markdown file:
 status: new
 ---
 
-# Document title
+# Page title
 ...
 ```
 
@@ -197,13 +196,11 @@ The following status identifiers are currently supported:
 - :material-alert-decagram: – `new`
 - :material-trash-can: – `deprecated`
 
-  [Page status support]: https://github.com/squidfunk/mkdocs-material/releases/tag/9.2.0
-
 ### Setting the page `subtitle`
 
-[:octicons-heart-fill-24:{ .mdx-heart } Sponsors only][Insiders]{ .mdx-insiders } ·
+<!-- md:sponsors -->
-[:octicons-tag-24: insiders-4.25.0][Insiders] ·
+<!-- md:version insiders-4.25.0 -->
-:octicons-beaker-24: Experimental
+<!-- md:flag 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
@@ -214,14 +211,14 @@ adding the following lines:
 subtitle: Nullam urna elit, malesuada eget finibus ut, ac tortor
 ---
 
-# Document title
+# Page title
 ...
 ```
 
 ### Setting the page `template`
 
 If you're using [theme extension] and created a new page template in the
-`overrides` directory, you can enable it for a specific page. Add the following 
+`overrides` directory, you can enable it for a specific page. Add the following
 lines at the top of a Markdown file:
 
 ``` yaml
@@ -229,7 +226,7 @@ lines at the top of a Markdown file:
 template: custom.html
 ---
 
-# Document title
+# Page title
 ...
 ```
 

docs/reference/tooltips.md

@@ -35,9 +35,9 @@ See additional configuration options:
 
 ### Improved tooltips
 
-[:octicons-heart-fill-24:{ .mdx-heart } Sponsors only][Insiders]{ .mdx-insiders } ·
+<!-- md:sponsors -->
-[:octicons-tag-24: insiders-4.15.0][Insiders] ·
+<!-- md:version insiders-4.15.0 -->
-:octicons-beaker-24: Experimental
+<!-- md:flag experimental -->
 
 When improved tooltips are enabled, Material for MkDocs replaces the browser's
 rendering logic for `title` attribute with beautiful little tooltips.
@@ -55,14 +55,12 @@ Now, tooltips will be rendered for the following elements:
 - __Header__ – home button, header title, color palette switch and repository link
 - __Navigation__ – links that are shortened with ellipsis, i.e. `...`
 
-[Insiders]: ../insiders/index.md
-
 ## Usage
 
 ### Adding tooltips
 
 The [Markdown syntax] allows to specify a `title` for each link, which will
-render as a beautiful tooltip when [improved tooltips] are enabled. Add a 
+render as a beautiful tooltip when [improved tooltips] are enabled. Add a
 tooltip to a link with the following lines:
 
 ``` markdown title="Link with tooltip, inline syntax"
@@ -107,7 +105,7 @@ extension:
 
 ### Adding abbreviations
 
-Abbreviations can be defined by using a special syntax similar to URLs and 
+Abbreviations can be defined by using a special syntax similar to URLs and
 [footnotes], starting with a `*` and immediately followed by the term or
 acronym to be associated in square brackets:
 
@@ -137,7 +135,7 @@ pages with the following configuration:
 
   [^1]:
     It's highly recommended to put the Markdown file containing the
-    abbreviations outside of the `docs` folder (here, a folder with the name 
+    abbreviations outside of the `docs` folder (here, a folder with the name
     `includes` is used), as MkDocs might otherwise complain about an
     unreferenced file.
 

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

@@ -93,7 +93,7 @@ property to `true`:
 comments: true
 ---
 
-# Document title
+# Page title
 ...
 ```
 

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

@@ -9,8 +9,8 @@ static site, including stars and forks. Furthermore, the
 
 ### Repository
 
-[:octicons-tag-24: 0.1.0][Repository support] ·
+<!-- md:version 0.1.0 -->
-:octicons-milestone-24: Default: _none_
+<!-- md:default none -->
 
 In order to display a link to the repository of your project as part of your
 documentation, set [`repo_url`][repo_url] in `mkdocs.yml` to the public URL of
@@ -29,20 +29,18 @@ GitHub repositories also include the tag of the latest release.[^1]
 
   [^1]:
     Unfortunately, GitHub only provides an API endpoint to obtain the [latest
-    release] - not the latest tag. Thus, make sure to [create a release] (not 
+    release] - not the latest tag. Thus, make sure to [create a release] (not
     pre-release) for the latest tag you want to display next to the number of
     stars and forks.
 
-  [Repository support]: https://github.com/squidfunk/mkdocs-material/releases/tag/0.1.0
   [repo_url]: https://www.mkdocs.org/user-guide/configuration/#repo_url
   [latest release]: https://docs.github.com/en/rest/reference/releases#get-the-latest-release
   [create a release]: https://docs.github.com/en/repositories/releasing-projects-on-github/managing-releases-in-a-repository#creating-a-release
 
 #### Repository name
 
-[:octicons-tag-24: 0.1.0][Repository name support] ·
+<!-- md:version 0.1.0 -->
-:octicons-milestone-24: Default: _automatically set to_ `GitHub`, `GitLab` _or_
+<!-- md:default _automatically set to_ `GitHub`, `GitLab` _or_ `Bitbucket` -->
-`Bitbucket`
 
 MkDocs will infer the source provider by examining the URL and try to set the
 _repository name_ automatically. If you wish to customize the name, set
@@ -52,14 +50,12 @@ _repository name_ automatically. If you wish to customize the name, set
 repo_name: squidfunk/mkdocs-material
 ```
 
-  [Repository name support]: https://github.com/squidfunk/mkdocs-material/releases/tag/0.1.0
   [repo_name]: https://www.mkdocs.org/user-guide/configuration/#repo_name
 
 #### Repository icon
 
-[:octicons-tag-24: 5.0.0][Repository icon support] ·
+<!-- md:version 5.0.0 -->
-:octicons-milestone-24: Default:
+<!-- md:default computed -->
-:fontawesome-brands-git-alt: – `fontawesome/brands/git-alt`
 
 While the default repository icon is a generic git icon, it can be set to
 any icon bundled with the theme by referencing a valid icon path in
@@ -93,14 +89,12 @@ Some popular choices:
 - :fontawesome-brands-bitbucket: – `fontawesome/brands/bitbucket`
 - :fontawesome-solid-trash: – `fontawesome/solid/trash`
 
-  [Repository icon support]: https://github.com/squidfunk/mkdocs-material/releases/tag/5.0.0
-  [Repository icon default]: https://github.com/squidfunk/mkdocs-material/blob/master/material/.icons/fontawesome/brands/git-alt.svg
   [icon search]: ../reference/icons-emojis.md#search
 
 #### Code actions
 
-[:octicons-tag-24: 9.0.0][Code actions support] ·
+<!-- md:version 9.0.0 -->
-:octicons-unlock-24: Feature flag
+<!-- md:feature -->
 
 If the [repository URL] points to a valid [GitHub], [GitLab] or [Bitbucket]
 repository, [MkDocs] provides a setting called [`edit_uri`][edit_uri], which
@@ -152,7 +146,6 @@ theme:
       </div>
     </div>
 
-  [Code actions support]: https://github.com/squidfunk/mkdocs-material/releases/tag/9.0.0
   [repository URL]: #repository
   [GitHub]: https://github.com/
   [GitLab]: https://about.gitlab.com/
@@ -172,8 +165,8 @@ links to all [contributors] or [authors] involved.
 
 #### Document dates
 
-[:octicons-tag-24: 4.6.0][Document dates support] ·
+<!-- md:version 4.6.0 -->
-[:octicons-cpu-24: Plugin][git-revision-date-localized]
+<!-- md:plugin [git-revision-date-localized] -->
 
 The [git-revision-date-localized] plugin adds support for adding the date of
 last update and creation of a document at the bottom of each page. Install it
@@ -193,9 +186,9 @@ plugins:
 
 The following configuration options are supported:
 
-[`enabled`](#+git-revision-date-localized.enabled){ #+git-revision-date-localized.enabled }
+<!-- md:option git-revision-date-localized.enabled -->
 
-:   :octicons-milestone-24: Default: `true` – This option specifies whether
+:   <!-- md:default `true` --> This option specifies whether
     the plugin is enabled when building your project. If you want to switch
     the plugin off, e.g. for local builds, use an [environment variable]:
 
@@ -205,9 +198,9 @@ The following configuration options are supported:
           enabled: !ENV [CI, false]
     ```
 
-[`type`](#+git-revision-date-localized.type){ #+git-revision-date-localized.type }
+<!-- md:option git-revision-date-localized.type -->
 
-:   :octicons-milestone-24: Default: `date` – The format of the date to be
+:   <!-- md:default `date` --> The format of the date to be
     displayed. Valid values are `date`, `datetime`, `iso_date`, `iso_datetime`
     and `timeago`:
 
@@ -217,9 +210,9 @@ The following configuration options are supported:
           type: date
     ```
 
-[`enable_creation_date`](#+git-revision-date-localized.enable_creation_date){ #+git-revision-date-localized.enable_creation_date }
+<!-- md:option git-revision-date-localized.enable_creation_date -->
 
-:   :octicons-milestone-24: Default: `false` – Enables the display of the
+:   <!-- md:default `false` --> Enables the display of the
     creation date of the file associated with the page next to the last updated
     date at the bottom of the page:
 
@@ -229,9 +222,9 @@ The following configuration options are supported:
           enable_creation_date: true
     ```
 
-[`fallback_to_build_date`](#+git-revision-date-localized.fallback_to_build_date){ #+git-revision-date-localized.fallback_to_build_date }
+<!-- md:option git-revision-date-localized.fallback_to_build_date -->
 
-:   :octicons-milestone-24: Default: `false` – Enables falling back to
+:   <!-- md:default `false` --> Enables falling back to
     the time when `mkdocs build` was executed. Can be used as a fallback when
     the build is performed outside of a git repository:
 
@@ -245,15 +238,14 @@ The other configuration options of this extension are not officially supported
 by Material for MkDocs, which is why they may yield unexpected results. Use
 them at your own risk.
 
-  [Document dates support]: https://github.com/squidfunk/mkdocs-material/releases/tag/4.6.0
   [git-revision-date-localized]: https://github.com/timvink/mkdocs-git-revision-date-localized-plugin
 
 #### Document contributors
 
-[:octicons-heart-fill-24:{ .mdx-heart } Sponsors only][Insiders]{ .mdx-insiders } ·
+<!-- md:sponsors -->
-[:octicons-tag-24: insiders-4.19.0][Insiders] ·
+<!-- md:version insiders-4.19.0 -->
-[:octicons-cpu-24: Plugin][git-committers] ·
+<!-- md:plugin [git-committers] -->
-:octicons-beaker-24: Experimental
+<!-- md:flag experimental -->
 
 The [git-committers][^2] plugin renders the GitHub avatars of all contributors,
 linking to their GitHub profiles at the bottom of each page. As always, it can
@@ -280,9 +272,9 @@ plugins:
 
 The following configuration options are supported:
 
-[`enabled`](#+git-committers.enabled){ #+git-committers.enabled }
+<!-- md:option git-committers.enabled -->
 
-:   :octicons-milestone-24: Default: `true` – This option specifies whether
+:   <!-- md:default `true` --> This option specifies whether
     the plugin is enabled when building your project. If you want to switch
     the plugin off, e.g. for local builds, use an [environment variable]:
 
@@ -292,9 +284,9 @@ The following configuration options are supported:
           enabled: !ENV [CI, false]
     ```
 
-[`repository`](#+git-committers.repository){ #+git-committers.repository }
+<!-- md:option git-committers.repository -->
 
-:   :octicons-milestone-24: Default: _none_ · :octicons-alert-24: __Required__ –
+:   <!-- md:default none --> <!-- md:flag required -->
     This property must be set to the slug of the repository that contains your
     documentation. The slug must follow the pattern `<username>/<repository>`:
 
@@ -304,9 +296,9 @@ The following configuration options are supported:
           repository: squidfunk/mkdocs-material
     ```
 
-[`branch`](#+git-committers.branch){ #+git-committers.branch }
+<!-- md:option git-committers.branch -->
 
-:   :octicons-milestone-24: Default: `master` – This property should be set to
+:   <!-- md:default `master` --> This property should be set to
     the branch of the repository from which to retrieve the contributors. To use the `main` branch:
 
     ``` yaml
@@ -326,10 +318,10 @@ them at your own risk.
 
 #### Document authors
 
-[:octicons-heart-fill-24:{ .mdx-heart } Sponsors only][Insiders]{ .mdx-insiders } ·
+<!-- md:sponsors -->
-[:octicons-tag-24: insiders-4.19.0][Insiders] ·
+<!-- md:version insiders-4.19.0 -->
-[:octicons-cpu-24: Plugin][git-authors] ·
+<!-- md:plugin [git-authors] -->
-:octicons-beaker-24: Experimental
+<!-- md:flag experimental -->
 
 The [git-authors] plugin is a lightweight alternative to the
 [git-committers] plugin and extracts the authors of a document from git to display

docs/setup/building-an-optimized-site.md

@@ -11,10 +11,10 @@ further useful automatic optimization techniques.
 
 ### Built-in projects plugin :material-alert-decagram:{ .mdx-pulse title="Added on July 29, 2023" }
 
-[:octicons-heart-fill-24:{ .mdx-heart } Sponsors only][Insiders]{ .mdx-insiders } ·
+<!-- md:sponsors -->
-[:octicons-tag-24: insiders-4.38.0][Insiders] ·
+<!-- md:version insiders-4.38.0 -->
-:octicons-cpu-24: Plugin ·
+<!-- md:plugin [projects] – built-in -->
-:octicons-beaker-24: Experimental
+<!-- md:flag experimental -->
 
 The built-in projects plugin allows to split your documentation into multiple
 distinct MkDocs projects, __build them concurrently__ and
@@ -25,31 +25,10 @@ plugins:
   - projects
 ```
 
-Next, create a folder called `projects` in your root directory which will
+For a list of all settings, please consult the [plugin documentation].
-contain all projects. For example, if we want to build a project with two
-additional languages, we can use:
 
-``` { .sh .no-copy }
+  [projects]: ../plugins/projects.md
-.
+  [plugin documentation]: ../plugins/projects.md
-├─ projects/
-│  ├─ de/
-│  │  ├─ docs/
-│  │  └─ mkdocs.yml
-│  └─ fr/
-│     ├─ docs/
-│     └─ mkdocs.yml
-└─ mkdocs.yml
-```
-
-If you now invoke `mkdocs serve` and change a file in one of the projects,
-the projects plugin makes sure that MkDocs will also reload those files. Note
-that the projects are currently entirely separate, which means they will have
-separate search indexes and sitemaps. We're happy to receive feedback on this
-plugin and learn about your requirements to make it better, as we plan to add
-support for merging and hoisting files.
-[Create a discussion to share your thoughts!][discussion]
-
-  [discussion]: https://github.com/squidfunk/mkdocs-material/discussions
 
 ??? info "Use cases for the projects plugin"
 
@@ -63,89 +42,12 @@ support for merging and hoisting files.
     so that we can improve it together with our users and make it even more
     powerful as we discover new use cases.
 
-The following configuration options are available:
-
-[`enabled`](#+projects.enabled){ #+projects.enabled }
-
-:   :octicons-milestone-24: Default: `true` – This option specifies whether
-    the plugin is enabled when building your project. If you want to speed up
-    local builds, you can use an [environment variable]:
-
-    ``` yaml
-    plugins:
-      - projects:
-          enabled: !ENV [CI, false]
-    ```
-
-[`concurrency`](#+projects.concurrency){ #+projects.concurrency }
-
-:   :octicons-milestone-24: Default: _number of CPUs_ – This option specifies
-    how many CPUs the plugin is allowed to use when building projects.
-    With more CPUs, the plugin can do more work in the same time, thus complete
-    optimization faster. Concurrent processing can be disabled with:
-
-    ``` yaml
-    plugins:
-      - projects:
-          concurrency: 1
-    ```
-
-#### Projects
-
-The following configuration options are available for projects:
-
-[`projects`](#+projects.projects){ #+projects.projects }
-
-:   :octicons-milestone-24: Default: `true` – This option specifies whether
-    to build nested projects. If you want to switch the plugin off, e.g.
-    for local builds, you can use an [environment variable]:
-
-    ``` yaml
-    plugins:
-      - projects:
-          projects: !ENV [CI, false]
-    ```
-
-[`projects_dir`](#+projects.projects_dir){ #+projects.projects_dir }
-
-:   :octicons-milestone-24: Default: `projects` – This option specifies the
-    name of the folder the plugin expects your projects to be stored. While it's
-    usually not necessary to change this option, change it with:
-
-    ``` yaml
-    plugins:
-      - projects:
-          projects_dir: path/to/folder
-    ```
-
-#### Hoisting
-
-The following configuration options are available for hoisting:
-
-[`hoisting`](#+projects.hoisting){ #+projects.hoisting }
-
-:   [:octicons-tag-24: insiders-4.39.0][Insiders] · :octicons-milestone-24:
-    Default: `true` – This option specifies whether the plugin should hoist all 
-    themes files to the top-level project. If you disable this setting, each
-    project will have a copy of the themes files, which in general, can be
-    considered redundant:
-
-    ``` yaml
-    plugins:
-      - projects:
-          hoisting: false
-    ```
-
-    It's generally advisable to enable hoisting, as it leads to faster
-    deployments and faster loading of your project's sites, because the files
-    are the same for all projects.
-
 ### Built-in optimize plugin
 
-[:octicons-heart-fill-24:{ .mdx-heart } Sponsors only][Insiders]{ .mdx-insiders } ·
+<!-- md:sponsors -->
-[:octicons-tag-24: insiders-4.29.0][Insiders] ·
+<!-- md:version insiders-4.29.0 -->
-:octicons-cpu-24: Plugin ·
+<!-- md:plugin [optimize] – built-in -->
-:octicons-beaker-24: Experimental
+<!-- md:flag experimental -->
 
 The built-in optimize plugin automatically identifies and optimizes all media
 files as part of the build using compression and conversion techniques. Add
@@ -156,177 +58,6 @@ plugins:
   - optimize # (1)!
 ```
 
-1.  Please ensure that all [dependencies for image processing] are installed,
+For a list of all settings, please consult the [plugin documentation][optimize].
-    or the plugin will not work properly.
 
-> If you need to be able to build your documentation with and without
+  [optimize]: ../plugins/optimize.md
-> [Insiders], please refer to the [built-in plugins] section to learn how
-> shared configurations help to achieve this.
-
-The following configuration options are available:
-
-[`enabled`](#+optimize.enabled){ #+optimize.enabled }
-
-:   :octicons-milestone-24: Default: `true` – This option specifies whether
-    the plugin is enabled when building your project. If you want to speed up
-    local builds, you can use an [environment variable]:
-
-    ``` yaml
-    plugins:
-      - optimize:
-          enabled: !ENV [CI, false]
-    ```
-
-[`concurrency`](#+optimize.concurrency){ #+optimize.concurrency }
-
-:   :octicons-milestone-24: Default: _number of CPUs_ – This option specifies
-    how many CPUs the plugin is allowed to use when optimizing media files.
-    With more CPUs, the plugin can do more work in the same time, thus complete
-    optimization faster. Concurrent processing can be disabled with:
-
-    ``` yaml
-    plugins:
-      - optimize:
-          concurrency: 1
-    ```
-
-#### Optimization
-
-Technical documentation often includes screenshots or diagrams, both of which
-are prime candidates for compression. The [built-in optimize plugin] allows to
-automatically compress images using [pngquant] (for PNGs), and [Pillow]
-(for JPGs).
-
-The following configuration options are available for optimization:
-
-[`optimize_png`](#+optimize.optimize_png){ #+optimize.optimize_png }
-
-:   :octicons-milestone-24: Default: `true` – This option specifies whether
-    the plugin should optimize PNG files using [pngquant], which must be
-    installed on the system. PNG optimization can be disabled with:
-
-    ``` yaml
-    plugins:
-      - optimize:
-          optimize_png: false
-    ```
-
-[`optimize_png_speed`](#+optimize.optimize_png_speed){ #+optimize.optimize_png_speed }
-
-:   :octicons-milestone-24: Default: `4` of `[1,10]` – This option specifies the
-    speed/quality tradeoff that [pngquant] applies when compressing. The lower
-    the number, the more time will be spent optimizing:
-
-    === "Slower <small>small</small>"
-
-        ``` yaml
-        plugins:
-          - optimize:
-              optimize_png_speed: 1
-        ```
-
-    === "Faster <small>rough</small>"
-
-        ``` yaml
-        plugins:
-          - optimize:
-              optimize_png_speed: 10
-        ```
-
-    A factor of `10` has 5% lower quality, but is 8x faster than the default `4`.
-
-[`optimize_png_strip`](#+optimize.optimize_png_strip){ #+optimize.optimize_png_strip }
-
-:   :octicons-milestone-24: Default: `true` – This option specifies whether
-    [pngquant] should remove all non-optional metadata that is not necessary
-    for rendering images in a browser:
-
-    ``` yaml
-    plugins:
-      - optimize:
-          optimize_png_strip: false
-    ```
-
-[`optimize_jpg`](#+optimize.optimize_jpg){ #+optimize.optimize_jpg }
-
-:   :octicons-milestone-24: Default: `true` – This option specifies whether
-    the plugin should optimize JPG files using [Pillow], a Python image
-    processing library. JPG optimization can be disabled with:
-
-    ``` yaml
-    plugins:
-      - optimize:
-          optimize_jpg: false
-    ```
-
-[`optimize_jpg_quality`](#+optimize.optimize_jpg_quality){ #+optimize.optimize_jpg_quality }
-
-:   :octicons-milestone-24: Default: `60` of `[0,100]` – This option specifies
-    the image quality that [Pillow] uses when compressing. If the images look
-    blurry, it's a good idea to tune and change this setting:
-
-    ``` yaml
-    plugins:
-      - optimize:
-          optimize_jpg_quality: 75
-    ```
-
-[`optimize_jpg_progressive`](#+optimize.optimize_jpg_progressive){ #+optimize.optimize_jpg_progressive }
-
-:   :octicons-milestone-24: Default: `true` – This option specifies whether
-    [Pillow] should use [progressive encoding] (faster rendering) when
-    compressing JPGs. Progressive encoding can be disabled with:
-
-    ``` yaml
-    plugins:
-      - optimize:
-          optimize_jpg_progressive: false
-    ```
-
-  [Insiders]: ../insiders/index.md
-  [built-in plugins]: ../insiders/getting-started.md#built-in-plugins
-  [dependencies for image processing]: dependencies/image-processing.md
-  [environment variable]: https://www.mkdocs.org/user-guide/configuration/#environment-variables
-  [pngquant]: https://pngquant.org/
-  [Pillow]: https://pillow.readthedocs.io/
-  [progressive encoding]: https://medium.com/hd-pro/jpeg-formats-progressive-vs-baseline-73b3938c2339
-
-#### Caching
-
-The [built-in optimize plugin] implements an intelligent caching mechanism,
-ensuring that media files are only pushed through the optimization pipeline when
-their contents change. If you swap out or update an image, the plugin will
-detect it and update the optimized version.
-
-The following configuration options are available for caching:
-
-[`cache`](#+optimize.cache){ #+optimize.cache }
-
-:   :octicons-milestone-24: Default: `true` – This option specifies whether
-    the plugin queries its cache for an existing artifact before starting an
-    optimization job. It's normally not necessary to change this setting,
-    except for when debugging the plugin itself. Caching can be disabled with:
-
-    ``` yaml
-    plugins:
-      - optimize:
-          cache: false
-    ```
-
-[`cache_dir`](#+optimize.cache_dir){ #+optimize.cache_dir }
-
-:   :octicons-milestone-24: Default: `.cache/plugins/optimize` – This option
-    specifies the file system location of the plugin's cache. It's normally not
-    necessary to change this setting, except for when debugging the plugin
-    itself. The cache directory can be changed with:
-
-    ``` yaml
-    plugins:
-      - optimize:
-          cache_dir: .cache/plugins/optimize
-    ```
-
-    By default, all built-in plugins that implement caching will create a
-    `.cache` directory in the same folder your `mkdocs.yml` resides, and create
-    subfolders to not interfere with each other. If you use multiple instances
-    of this plugin, it could be necessary to change this setting.

docs/setup/building-for-offline-usage.md

@@ -11,8 +11,8 @@ support for many of its features.
 
 ### Built-in offline plugin
 
-[:octicons-tag-24: 9.0.0][offline support] ·
+<!-- md:version 9.0.0 -->
-:octicons-cpu-24: Plugin
+<!-- md:plugin [offline] – built-in -->
 
 The built-in offline plugin makes sure that the [site search] works when you
 distribute the contents of your [site directory] as a download. Simply add
@@ -23,27 +23,10 @@ plugins:
   - offline
 ```
 
-The plugin will automatically disable the [`use_directory_urls`][use_directory_urls]
+For a list of all settings, please consult the [plugin documentation].
-setting, ensuring that users can open your documentation directly from the local
-file system.
 
-The following configuration options are available:
+  [offline]: ../plugins/offline.md
-
+  [plugin documentation]: ../plugins/offline.md
-[`enabled`](#+offline.enabled){ #+offline.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, e.g. for local builds, use an [environment variable]:
-
-    ``` yaml
-    plugins:
-      - offline:
-          enabled: !ENV [OFFLINE, false]
-    ```
-
-Now, after invoking `mkdocs build`, you can open `site/index.html` directly
-in your browser and the [site search] will work as if the documentation was
-hosted on a regular server.
 
 !!! tip "Automatically bundle all external assets"
 
@@ -51,11 +34,8 @@ hosted on a regular server.
     while building documentation for offline usage, as it will automatically
     download all external assets to distribute them with your documentation.
 
-  [offline support]: https://github.com/squidfunk/mkdocs-material/releases/tag/9.0.0
   [site search]: setting-up-site-search.md
   [site directory]: https://www.mkdocs.org/user-guide/configuration/#site_dir
-  [use_directory_urls]: https://www.mkdocs.org/user-guide/configuration/#use_directory_urls
-  [environment variable]: https://www.mkdocs.org/user-guide/configuration/#environment-variables
   [built-in privacy plugin]: ensuring-data-privacy.md#built-in-privacy-plugin
 
 #### Limitations

docs/setup/changing-the-colors.md

@@ -1,7 +1,7 @@
 # Changing the colors
 
 As any proper Material Design implementation, Material for MkDocs supports
-Google's original [color palette], which can be easily configured through 
+Google's original [color palette], which can be easily configured through
 `mkdocs.yml`. Furthermore, colors can be customized with a few lines of CSS to
 fit your brand's identity by using [CSS variables][custom colors].
 
@@ -14,8 +14,8 @@ fit your brand's identity by using [CSS variables][custom colors].
 
 #### Color scheme
 
-[:octicons-tag-24: 5.2.0][Color scheme support] ·
+<!-- md:version 5.2.0 -->
-:octicons-milestone-24: Default: `default`
+<!-- md:default `default` -->
 
 Material for MkDocs supports two color schemes: a __light mode__, which is just
 called `default`, and a __dark mode__, which is called `slate`. The color scheme
@@ -50,12 +50,10 @@ Click on a tile to change the color scheme:
   })
 </script>
 
-  [Color scheme support]: https://github.com/squidfunk/mkdocs-material/releases/tag/5.2.0
-
 #### Primary color
 
-[:octicons-tag-24: 0.2.0][Primary color support] ·
+<!-- md:version 0.2.0 -->
-:octicons-milestone-24: Default: `indigo`
+<!-- md:default `indigo` -->
 
 The primary color is used for the header, the sidebar, text links and several
 other components. In order to change the primary color, set the following value
@@ -107,12 +105,10 @@ Click on a tile to change the primary color:
 
 See our guide below to learn how to set [custom colors].
 
-  [Primary color support]: https://github.com/squidfunk/mkdocs-material/releases/tag/0.2.0
-
 #### Accent color
 
-[:octicons-tag-24: 0.2.0][Accent color support] ·
+<!-- md:version 0.2.0 -->
-:octicons-milestone-24: Default: `indigo`
+<!-- md:default `indigo` -->
 
 The accent color is used to denote elements that can be interacted with, e.g.
 hovered links, buttons and scrollbars. It can be changed in `mkdocs.yml` by
@@ -166,12 +162,10 @@ Click on a tile to change the accent color:
 
 See our guide below to learn how to set [custom colors].
 
-  [Accent color support]: https://github.com/squidfunk/mkdocs-material/releases/tag/0.2.0
-
 ### Color palette toggle
 
-[:octicons-tag-24: 7.1.0][Color palette toggle support] ·
+<!-- md:version 7.1.0 -->
-:octicons-milestone-24: Default: _none_
+<!-- md:default none -->
 
 Offering a light _and_ dark color palette makes your documentation pleasant to
 read at different times of the day, so the user can choose accordingly. Add the
@@ -213,9 +207,9 @@ and [`accent`][palette.accent] per color palette.
 
 The following properties must be set for each toggle:
 
-[`icon`](#+palette.toggle.icon){ #+palette.toggle.icon }
+<!-- md:option palette.toggle.icon -->
 
-:   :octicons-milestone-24: Default: _none_ · :octicons-alert-24: __Required__ –
+:   <!-- md:default none --> <!-- md:flag required -->
     This property must point to a valid icon path referencing any icon bundled
     with the theme, or the build will not succeed. Some popular combinations:
 
@@ -225,13 +219,12 @@ The following properties must be set for each toggle:
     * :material-eye: + :material-eye-outline: – `material/eye` + `material/eye-outline`
     * :material-lightbulb: + :material-lightbulb-outline: – `material/lightbulb` + `material/lightbulb-outline`
 
-[`name`](#+palette.toggle.name){ #+palette.toggle.name }
+<!-- md:option palette.toggle.name -->
 
-:   :octicons-milestone-24: Default: _none_ · :octicons-alert-24: __Required__ –
+:   <!-- md:default none --> <!-- md:flag required -->
     This property is used as the toggle's `title` attribute and should be set to
     a discernable name to improve accessibility. It's rendered as a [tooltip].
 
-  [Color palette toggle support]: https://github.com/squidfunk/mkdocs-material/releases/tag/7.1.0
   [palette.scheme]: #color-scheme
   [palette.primary]: #primary-color
   [palette.accent]: #accent-color
@@ -240,8 +233,8 @@ The following properties must be set for each toggle:
 
 ### System preference
 
-[:octicons-tag-24: 7.1.0][System preference support] ·
+<!-- md:version 7.1.0 -->
-:octicons-milestone-24: Default: _none_
+<!-- md:default none -->
 
 Each color palette can be linked to the user's system preference for light and
 dark appearance by using a media query. Simply add a `media` property next to
@@ -270,13 +263,11 @@ When the user first visits your site, the media queries are evaluated in the
 order of their definition. The first media query that matches selects the
 default color palette.
 
-  [System preference support]: https://github.com/squidfunk/mkdocs-material/releases/tag/7.1.0
-
 #### Automatic light / dark mode
 
-[:octicons-heart-fill-24:{ .mdx-heart } Sponsors only][Insiders]{ .mdx-insiders } ·
+<!-- md:sponsors -->
-[:octicons-tag-24: insiders-4.18.0][Insiders] ·
+<!-- md:version insiders-4.18.0 -->
-:octicons-beaker-24: Experimental
+<!-- md:flag experimental -->
 
 Newer operating system allow to automatically switch between light and dark
 appearance during day and night times. [Insiders] adds support for automatic

docs/setup/changing-the-fonts.md

@@ -11,8 +11,8 @@ or another destination should be used.
 
 ### Regular font
 
-[:octicons-tag-24: 0.1.2][Font support] ·
+<!-- md:version 0.1.2 -->
-:octicons-milestone-24: Default: [`Roboto`][Roboto]
+<!-- md:default [`Roboto`][Roboto] -->
 
 The regular font is used for all body copy, headlines, and essentially
 everything that does not need to be monospaced. It can be set to any
@@ -27,12 +27,11 @@ theme:
 The typeface will be loaded in 300, 400, _400i_ and __700__.
 
   [Roboto]: https://fonts.google.com/specimen/Roboto
-  [Font support]: https://github.com/squidfunk/mkdocs-material/releases/tag/0.1.2
 
 ### Monospaced font
 
-[:octicons-tag-24: 0.1.2][Font support] ·
+<!-- md:version 0.1.2 -->
-:octicons-milestone-24: Default: [`Roboto Mono`][Roboto Mono]
+<!-- md:default [`Roboto Mono`][Roboto Mono] -->
 
 The _monospaced font_ is used for code blocks and can be configured separately.
 Just like the regular font, it can be set to any valid [Google Font]
@@ -50,8 +49,8 @@ The typeface will be loaded in 400.
 
 ### Autoloading
 
-[:octicons-tag-24: 1.0.0][Autoloading support] ·
+<!-- md:version 1.0.0 -->
-:octicons-milestone-24: Default: _none_
+<!-- md:default none -->
 
 If you want to prevent typefaces from being loaded from [Google Fonts], e.g.
 to adhere to [data privacy] regulations, and fall back to system fonts, add the
@@ -69,7 +68,6 @@ theme:
     by automatically downloading and self-hosting the web font files.
 
   [data privacy]: https://developers.google.com/fonts/faq#what_does_using_the_google_fonts_api_mean_for_the_privacy_of_my_users
-  [Autoloading support]: https://github.com/squidfunk/mkdocs-material/releases/tag/1.0.0
   [built-in privacy plugin]: ensuring-data-privacy.md#built-in-privacy-plugin
 
 ## Customization
@@ -96,7 +94,7 @@ corresponding `@font-face` definition:
       - stylesheets/extra.css
     ```
 
-The font can then be applied to specific elements, e.g. only headlines, or 
+The font can then be applied to specific elements, e.g. only headlines, or
 globally to be used as the site-wide regular or monospaced font:
 
 === "Regular font"

docs/setup/changing-the-language.md

@@ -9,8 +9,8 @@ available.
 
 ### Site language
 
-[:octicons-tag-24: 1.12.0][Site language support] ·
+<!-- md:version 1.12.0 -->
-:octicons-milestone-24: Default: `en`
+<!-- md:default `en` -->
 
 You can set the site language in `mkdocs.yml` with:
 
@@ -41,7 +41,6 @@ the default slug function works. Consider using a [Unicode-aware slug function].
     that some translations are missing, click on the link to add them. If your
     language is not in the list, click here to [add a new language].
 
-  [Site language support]: https://github.com/squidfunk/mkdocs-material/releases/tag/1.12.0
   [single language per document]: https://www.w3.org/International/questions/qa-html-language-declarations.en#attributes
   [language selector]: #site-language-selector
   [Unicode-aware slug function]: extensions/python-markdown.md#toc-slugify
@@ -49,8 +48,8 @@ the default slug function works. Consider using a [Unicode-aware slug function].
 
 ### Site language selector
 
-[:octicons-tag-24: 7.0.0][Site language selector support] ·
+<!-- md:version 7.0.0 -->
-:octicons-milestone-24: Default: _none_
+<!-- md:default none -->
 
 If your documentation is available in multiple languages, a language selector
 pointing to those languages can be added to the header. Alternate languages
@@ -73,36 +72,35 @@ extra:
 
 The following properties are available for each alternate language:
 
-[`name`](#+alternate.name){ #+alternate.name }
+<!-- md:option alternate.name -->
 
-:   :octicons-milestone-24: Default: _none_ · :octicons-alert-24: __Required__ –
+:   <!-- md:default none --> <!-- md:flag required -->
     This value of this property is used inside the language selector as the
     name of the language and must be set to a non-empty string.
 
-[`link`](#+alternate.link){ #+alternate.link }
+<!-- md:option alternate.link -->
 
-:   :octicons-milestone-24: Default: _none_ · :octicons-alert-24: __Required__ –
+:   <!-- md:default none --> <!-- md:flag required -->
     This property must be set to an absolute link, which might also point to
     another domain or subdomain not necessarily generated with MkDocs.
 
-[`lang`](#+alternate.lang){ #+alternate.lang }
+<!-- md:option alternate.lang -->
 
-:   :octicons-milestone-24: Default: _none_ · :octicons-alert-24: __Required__ –
+:   <!-- md:default none --> <!-- md:flag required -->
     This property must contain an [ISO 639-1 language code] and is used for
     the `hreflang` attribute of the link, improving discoverability via search
     engines.
 
 [![Language selector preview]][Language selector preview]
 
-  [Site language selector support]: https://github.com/squidfunk/mkdocs-material/releases/tag/7.0.0
   [site_url]: https://www.mkdocs.org/user-guide/configuration/#site_url
   [ISO 639-1 language code]: https://en.wikipedia.org/wiki/List_of_ISO_639-1_codes
   [Language selector preview]: ../assets/screenshots/language-selection.png
 
 ### Directionality
 
-[:octicons-tag-24: 2.5.0][Directionality support] ·
+<!-- md:version 2.5.0 -->
-:octicons-milestone-24: Default: _automatically set_
+<!-- md:default computed -->
 
 While many languages are read `ltr` (left-to-right), Material for MkDocs also
 supports `rtl` (right-to-left) directionality which is deduced from the
@@ -132,8 +130,6 @@ Click on a tile to change the directionality:
   })
 </script>
 
-  [Directionality support]: https://github.com/squidfunk/mkdocs-material/releases/tag/2.5.0
-
 ## Customization
 
 ### Custom translations

docs/setup/changing-the-logo-and-icons.md

@@ -1,7 +1,7 @@
 # Changing the logo and icons
 
-When installing Material for MkDocs, you immediately get access to _over 8,000 
+When installing Material for MkDocs, you immediately get access to _over 8,000
-icons_ ready to be used for customization of specific parts of the theme and/or 
+icons_ ready to be used for customization of specific parts of the theme and/or
 when writing your documentation in Markdown. Not enough? You can also add
 [additional icons] with minimal effort.
 
@@ -11,8 +11,8 @@ when writing your documentation in Markdown. Not enough? You can also add
 
 ### Logo
 
-[:octicons-tag-24: 0.1.0][Logo support] ·
+<!-- md:version 0.1.0 -->
-:octicons-milestone-24: Default: :material-library: – `material/library`
+<!-- md:default `material/library` -->
 
 The logo can be changed to a user-provided image (any type, incl. `*.png` and
 `*.svg`) located in the `docs` folder, or to any icon bundled with the theme.
@@ -44,7 +44,6 @@ Add the following lines to `mkdocs.yml`:
           </div>
         </div>
 
-  [Logo support]: https://github.com/squidfunk/mkdocs-material/releases/tag/0.1.0
   [icon search]: ../reference/icons-emojis.md#search
 
 Normally, the logo in the header and sidebar links to the homepage of the
@@ -58,10 +57,10 @@ extra:
 
 ### Favicon
 
-[:octicons-tag-24: 0.1.0][Favicon support] ·
+<!-- md:version 0.1.0 -->
-:octicons-milestone-24: Default: [`assets/images/favicon.png`][Favicon default]
+<!-- md:default [`assets/images/favicon.png`][Favicon default] -->
 
-The favicon can be changed to a path pointing to a user-provided image, which 
+The favicon can be changed to a path pointing to a user-provided image, which
 must be located in the `docs` folder. Add the following lines to `mkdocs.yml`:
 
 ``` yaml
@@ -69,7 +68,6 @@ theme:
   favicon: images/favicon.png
 ```
 
-  [Favicon support]: https://github.com/squidfunk/mkdocs-material/releases/tag/0.1.0
   [Favicon default]: https://github.com/squidfunk/mkdocs-material/blob/master/material/assets/images/favicon.png
 
 ### Site icons

docs/setup/ensuring-data-privacy.md

@@ -1,6 +1,6 @@
 # Ensuring data privacy
 
-Material for MkDocs makes compliance with data privacy regulations very easy, 
+Material for MkDocs makes compliance with data privacy regulations very easy,
 as it offers a native [cookie consent] solution to seek explicit consent from
 users before setting up [analytics]. Additionally, external assets can be
 automatically downloaded for [self-hosting].
@@ -13,9 +13,9 @@ automatically downloaded for [self-hosting].
 
 ### Cookie consent
 
-[:octicons-tag-24: 8.4.0][Cookie consent support] ·
+<!-- md:version 8.4.0 -->
-:octicons-milestone-24: Default: _none_ ·
+<!-- md:default none -->
-:octicons-beaker-24: Experimental
+<!-- md:flag experimental -->
 
 Material for MkDocs ships a native and extensible cookie consent form which
 asks the user for consent prior to sending requests to third parties. Add the
@@ -37,21 +37,21 @@ extra:
 
 The following properties are available:
 
-[`title`](#+consent.title){ #+consent.title }
+<!-- md:option consent.title -->
 
-:   :octicons-milestone-24: Default: _none_ · :octicons-alert-24: __Required__ –
+:   <!-- md:default none --> <!-- md:flag required -->
-    This property sets the title of the cookie consent, which is rendered at the 
+    This property sets the title of the cookie consent, which is rendered at the
     top of the form and must be set to a non-empty string.
 
-[`description`](#+consent.description){ #+consent.description }
+<!-- md:option consent.description -->
 
-:   :octicons-milestone-24: Default: _none_ · :octicons-alert-24: __Required__ –
+:   <!-- md:default none --> <!-- md:flag required -->
     This property sets the description of the cookie consent, is rendered below
     the title, and may include raw HTML (e.g. a links to the terms of service).
 
-[`cookies`](#+consent.cookies){ #+consent.cookies }
+<!-- md:option consent.cookies -->
 
-:   :octicons-milestone-24: Default: _none_ – This property allows to add custom 
+:   <!-- md:default none --> This property allows to add custom
     cookies or change the initial `checked` state and name of built-in cookies.
     Currently, the following cookies are built-in:
 
@@ -100,10 +100,10 @@ The following properties are available:
     automatically include a setting for the user to disable it. [Custom cookies]
     can be used from JavaScript.
 
-[`actions`](#+consent.actions){ #+consent.actions }
+<!-- md:option consent.actions -->
 
-:   :octicons-milestone-24: Default: `[accept, manage]` – This property defines
+:   <!-- md:default `[accept, manage]` --> This property defines
-    which buttons are shown and in which order, e.g. to allow the user to accept 
+    which buttons are shown and in which order, e.g. to allow the user to accept
     cookies and manage settings:
 
     ``` yaml
@@ -128,13 +128,12 @@ When a user first visits your site, a cookie consent form is rendered:
 [![Cookie consent enabled]][Cookie consent enabled]
 
   [Custom cookies]: #custom-cookies
-  [Cookie consent support]: https://github.com/squidfunk/mkdocs-material/releases/tag/8.4.0
   [Cookie consent enabled]: ../assets/screenshots/consent.png
 
 #### Change cookie settings
 
 In order to comply with GDPR, users must be able to change their cookie settings
-at any time. This can be done by adding a simple link to your [copyright notice] 
+at any time. This can be done by adding a simple link to your [copyright notice]
 in `mkdocs.yml`:
 
 ``` yaml
@@ -147,12 +146,12 @@ copyright: >
 
 ### Built-in privacy plugin
 
-[:octicons-heart-fill-24:{ .mdx-heart } Sponsors only][Insiders]{ .mdx-insiders } ·
+<!-- md:sponsors -->
-[:octicons-tag-24: insiders-4.9.0][Insiders] ·
+<!-- md:version insiders-4.9.0 -->
-:octicons-cpu-24: Plugin ·
+<!-- md:plugin [privacy][built-in privacy plugin] -->
-:octicons-beaker-24: Experimental
+<!-- md:flag experimental -->
 
-The built-in privacy plugin automatically identifies [external assets] as part
+The built-in privacy plugin automatically identifies external assets as part
 of the build process and downloads all assets for very simple self-hosting. Add
 the following lines to `mkdocs.yml`:
 
@@ -161,254 +160,52 @@ plugins:
   - privacy
 ```
 
-> If you need to be able to build your documentation with and without
+For a list of all settings, please consult the [plugin documentation].
-> [Insiders], please refer to the [built-in plugins] section to learn how
-> shared configurations help to achieve this.
 
-The following configuration options are available:
+  [plugin documentation]: ../plugins/privacy.md
 
-[`enabled`](#+privacy.enabled){ #+privacy.enabled }
+!!! tip "Hosting images externally and optimizing them automatically"
 
-:   :octicons-milestone-24: Default: `true` – This option specifies whether
+    This option makes the [built-in privacy plugin] an excellent choice for
-    the plugin is enabled when building your project. If you want to speed up
+    when you want to host assets like images outside of your git repository
-    local builds, you can use an [environment variable]:
+    in another location to keep them fresh and your repository lean.
 
-    ``` yaml
+    Additionally, as of <!-- md:version insiders-4.30.0 -->, the
-    plugins:
+    built-in privacy plugin was entirely rewritten and now works perfectly
-      - privacy:
+    with the [built-in optimize plugin], which means that external assets
-          enabled: !ENV [CI, false]
+    can be passed through the same optimization pipeline as the rest of your
-    ```
+    documentation. This means you can store and edit unoptimized files
+    outside of your repository, and let both plugins built a highly
+    optimized site for you.
 
-[`concurrency`](#+privacy.concurrency){ #+privacy.concurrency }
+    If you want to implement separate pipelines, i.e., optimize some images
-
+    differently from others or exclude some images from downloading, you can
-:   :octicons-milestone-24: Default: _number of CPUs_ – This option specifies
+    use multiple instances of the [built-in privacy plugin].
-    how many CPUs the plugin is allowed to use when downloading external assets.
-    With more CPUs, the plugin can do more work in the same time, thus complete
-    its work faster. Concurrent processing can be disabled with:
-
-    ``` yaml
-    plugins:
-      - privacy:
-          concurrency: 1
-    ```
-
-  [Insiders]: ../insiders/index.md
-  [built-in plugins]: ../insiders/getting-started.md#built-in-plugins
-
-#### External assets
-
-The following configuration options are available for external assets:
-
-[`assets`](#+privacy.assets){ #+privacy.assets }
-
-:   :octicons-milestone-24: Default: `true` – This option specifies whether the
-    plugin should scan the HTML output to detect and process external assets:
-
-    ``` yaml
-    plugins:
-      - privacy:
-          assets: true
-    ```
-
-    If you've removed all external assets from your project via [customization],
-    it's still a good idea to enable the plugin, as the plugin will make sure
-    that there are no hidden external links in any Markdown files that were 
-    unintentionally added.
-
-    Using `assets` in [strict mode] will make the build fail when external
-    assets are detected.
-
-[`assets_fetch`](#+privacy.assets_fetch){ #+privacy.assets_fetch }
-
-:   :octicons-milestone-24: Default: `true` – This option specifies whether the
-    plugin should download external assets it encountered and bundle them with
-    your documentation:
-
-    ``` yaml
-    plugins:
-      - privacy:
-          assets_fetch: true
-    ```
-
-[`assets_fetch_dir`](#+privacy.assets_fetch_dir){ #+privacy.assets_fetch_dir }
-
-:   :octicons-milestone-24: Default: `assets/external` – This option
-    specifies where the downloaded [external assets] will be stored. It's
-    normally not necessary to change this option:
-
-    ``` yaml
-    plugins:
-      - privacy:
-          assets_fetch_dir: assets/external
-    ```
-
-    The path must be defined relative to [`docs_dir`][docs_dir].
-
-[`assets_include`](#+privacy.assets_include){ #+privacy.assets_include }
-
-:   :octicons-milestone-24: Default: _none_ – This option allows to only include
-    certain external assets for processing by the privacy plugin, so they will
-    be downloaded and bundled during the build:
-
-    ``` yaml
-    plugins:
-      - privacy:
-          assets_include:
-            - unsplash.com/*
-    ```
-
-    !!! tip "Hosting images externally and optimizing them automatically"
-
-        This option makes the [built-in privacy plugin] an excellent choice for
-        when you want to host assets like images outside of your git repository
-        in another location to keep them fresh and your repository lean.
-
-        Additionally, as of [:octicons-tag-24: insiders-4.30.0][Insiders], the
-        built-in privacy plugin was entirely rewritten and now works perfectly
-        with the [built-in optimize plugin], which means that external assets
-        can be passed through the same optimization pipeline as the rest of your
-        documentation. This means you can store and edit unoptimized files
-        outside of your repository, and let both plugins built a highly
-        optimized site for you.
-
-        If you want to implement separate pipelines, i.e., optimize some images
-        differently from others or exclude some images from downloading, you can
-        use multiple instances of the [built-in privacy plugin].
-
-[`assets_exclude`](#+privacy.assets_exclude){ #+privacy.assets_exclude }
-
-:   :octicons-milestone-24: Default: _none_ – This option allows to exclude
-    certain external assets from processing by the privacy plugin, so they will
-    not be downloaded and bundled during the build:
-
-    ``` yaml
-    plugins:
-      - privacy:
-          assets_exclude: # (1)!
-            - cdn.jsdelivr.net/npm/mathjax@3/* 
-            - giscus.app/*
-    ```
-
-    1.  [MathJax] loads web fonts for typesetting of mathematical content
-        through relative URLs, and thus cannot be automatically bundled by the
-        privacy plugin. [MathJax can be self-hosted].
-
-        Giscus, which we recommend to use as a [comment system], uses a technique
-        called code-splitting to load only the code that is necessary, which
-        is implemented via relative URLs. [Giscus can be self-hosted] as well.
-
-    Excluding specific external assets can be necessary if they contain
-    dynamically created or relative URLs, which can't be resolved by the privacy
-    plugin due to [technical limitations].
 
 !!! question "Why can't Material for MkDocs bundle all assets by design?"
 
     The primary reason why Material for MkDocs can't just bundle all of its own
     assets is the integration with [Google Fonts], which offers over a thousand
     different fonts that can be used to render your documentation. Most of the
-    fonts include several weights and are split up into different character sets 
+    fonts include several weights and are split up into different character sets
     to keep the download size small, so the browser only downloads what is
     really needed. For Roboto, our default [regular font], this results in [42
     `*.woff2` files in total][example].
-    
+
     If Material for MkDocs would bundle all font files, the download size would
-    be in the hundreds of megabytes, slowing down automated builds. Furthermore, 
+    be in the hundreds of megabytes, slowing down automated builds. Furthermore,
-    authors might add external assets like third-party scripts or style sheets 
+    authors might add external assets like third-party scripts or style sheets
     that would need to be remembered to be defined as further local assets.
-    
+
     This is the very reason the [built-in privacy plugin] exists — it automates
     the process of downloading all external assets manually to ensure compliance
     with GDPR with some some [technical limitations].
 
-  [customization]: ../customization.md
-  [strict mode]: https://www.mkdocs.org/user-guide/configuration/#strict
-  [docs_dir]: https://www.mkdocs.org/user-guide/configuration/#docs_dir
-  [MathJax]: ../reference/math.md
-  [MathJax can be self-hosted]: https://docs.mathjax.org/en/latest/web/hosting.html
-  [Giscus can be self-hosted]: https://github.com/giscus/giscus/blob/main/SELF-HOSTING.md
-  [comment system]: adding-a-comment-system.md
-  [external assets]: #how-it-works
-  [environment variable]: https://www.mkdocs.org/user-guide/configuration/#environment-variables
   [Google Fonts]: changing-the-fonts.md
   [regular font]: changing-the-fonts.md#regular-font
   [example]: #example
-  [technical limitations]: #limitations
+  [built-in optimize plugin]: ../plugins/optimize.md
-  [built-in optimize plugin]: building-an-optimized-site.md#built-in-optimize-plugin
 
-#### External links
-
-[:octicons-heart-fill-24:{ .mdx-heart } Sponsors only][Insiders]{ .mdx-insiders } ·
-[:octicons-tag-24: insiders-4.26.0][Insiders] ·
-:octicons-beaker-24: Experimental
-
-The following configuration options are available for external links:
-
-[`links`](#+privacy.links){ #+privacy.links }
-
-:   :octicons-milestone-24: Default: `true` – This option specifies whether the
-    plugin should parse and process external links. If you want to speed up
-    local builds, you can use an [environment variable]:
-
-    ``` yaml
-    plugins:
-      - privacy:
-          links: !ENV [CI, false]
-    ```
-
-[`links_attr_map`](#+privacy.links_attr_map){ #+privacy.links_attr_map }
-
-:   :octicons-milestone-24: Default: _None_ – This option specifies custom
-    attributes that should be added to external links, like for example
-    `target="_blank"` so all external links open in a new window:
-
-    ``` yaml
-    plugins:
-      - privacy:
-          links_attr_map:
-            target: _blank
-    ```
-
-[`links_noopener`](#+privacy.links_noopener){ #+privacy.links_noopener }
-
-:   :octicons-milestone-24: Default: `true` – This option specifies whether the
-    plugin should automatically add [`rel="noopener"`][noopener] to all links
-    with `target="_blank"` for security reasons:
-
-    ``` yaml
-    plugins:
-      - privacy:
-          links_noopener: true
-    ```
-
-  [noopener]: https://mathiasbynens.github.io/rel-noopener/
-
-#### How it works
-
-The [built-in privacy plugin] scans the resulting HTML for links to external
-resources, including external scripts, style sheets, images and web fonts, and
-downloads them to bundle them with your documentation site. Every URL referring
-to an external resource, no matter if part of a template or Markdown file, is
-then replaced with the URL to the local copy. An example:
-
-``` html
-<script src="https://example.com/script.js"></script>
-```
-
-The external script is downloaded, and the link is replaced with:
-
-``` html
-<script src="assets/external/example.com/script.js"></script>
-```
-
-Style sheets are scanned for external `url(...)` references, e.g. images and
-web fonts, which are then also downloaded and bundled with your documentation
-site. This means that [Google Fonts] can be configured in `mkdocs.yml` as usual,
-as the [built-in privacy plugin] automatically downloads and bundles all
-dependent resources.
-
-As a third measure, [`preconnect`][preconnect] hints used for DNS pre-fetching
-which might also leak the visitors IP address to a third party are automatically
-removed during the build process.
 
 ??? example "Expand to inspect example"
 
@@ -480,68 +277,9 @@ removed during the build process.
        └─ polyfill.io/v3/polyfill.min.js
     ```
 
-  [built-in privacy plugin]: #built-in-privacy-plugin
+  [built-in privacy plugin]: ../plugins/privacy.md
   [preconnect]: https://developer.mozilla.org/en-US/docs/Web/Performance/dns-prefetch
 
-#### Caching <small>recommended</small> { #caching data-toc-label="Caching" }
-
-All downloaded files are written to the `.cache` directory, significantly 
-reducing the duration of subsequent builds as only replacements need to be 
-carried out. You might want to:
-
-1.  Ignore the `.cache` directory in your project, by adding it to `.gitignore`.
-2.  When building your site for publishing, use a build cache to save the
-    `.cache` directory in between builds. Taking the example from the
-    [publishing guide], add the following lines:
-
-    ``` yaml hl_lines="15-21"
-    name: ci
-      on:
-        push:
-          branches:
-            - master
-            - main
-    jobs:
-      deploy:
-        runs-on: ubuntu-latest
-        steps:
-          - uses: actions/checkout@v3
-          - uses: actions/setup-python@v4
-            with:
-              python-version: 3.x
-          - run: echo "cache_id=$(date --utc '+%V')" >> $GITHUB_ENV
-          - uses: actions/cache@v3
-            with:
-              key: mkdocs-material-${{ env.cache_id }}
-              path: .cache
-              restore-keys: |
-                mkdocs-material-
-          - run: pip install mkdocs-material
-          - run: mkdocs gh-deploy --force
-    ```
-
-  [publishing guide]: ../publishing-your-site.md#with-github-actions
-
-#### Limitations
-
-Note that dynamically created URLs as part of scripts are not detected, and thus
-cannot be automatically downloaded. The [built-in privacy plugin] does not
-execute scripts – it can only detect fully qualified URLs to download and
-replace.
-
-In short, don't do this:
-
-``` js
-const cdn = "https://polyfill.io"
-const url = `${cdn}/v3/polyfill.min.js`
-```
-
-Instead, always use fully qualified URLs:
-
-``` js
-const url ="https://polyfill.io/v3/polyfill.min.js"
-```
-
 ## Customization
 
 ### Custom cookies

docs/setup/extensions/python-markdown-extensions.md

@@ -15,8 +15,8 @@ are natively supported, meaning they work without any further adjustments.
 
 ### Arithmatex
 
-[:octicons-tag-24: 1.0.0][Arithmatex support] ·
+<!-- md:version 1.0.0 -->
-[:octicons-workflow-24: Extension][Arithmatex]
+<!-- md:extension [pymdownx.arithmatex][Arithmatex] -->
 
 The [Arithmatex] extension allows for rendering of block and inline block
 equations and integrates seamlessly with [MathJax][^1] – a library for
@@ -33,7 +33,7 @@ markdown_extensions:
       generic: true
 ```
 
-Besides enabling the extension in `mkdocs.yml`, a MathJax configuration and 
+Besides enabling the extension in `mkdocs.yml`, a MathJax configuration and
 the JavaScript runtime need to be included, which can be done with a few lines
 of [additional JavaScript]:
 
@@ -77,7 +77,6 @@ See reference for usage:
 - [Using inline block syntax]
 
   [Arithmatex]: https://facelessuser.github.io/pymdown-extensions/extensions/arithmatex/
-  [Arithmatex support]: https://github.com/squidfunk/mkdocs-material/releases/tag/1.0.0
   [Arithmatex documentation on KaTeX]: https://facelessuser.github.io/pymdown-extensions/extensions/arithmatex/#loading-katex
   [MathJax]: https://www.mathjax.org/
   [KaTeX]: https://github.com/Khan/KaTeX
@@ -87,8 +86,8 @@ See reference for usage:
 
 ### BetterEm
 
-[:octicons-tag-24: 0.1.0][BetterEm support] ·
+<!-- md:version 0.1.0 -->
-[:octicons-workflow-24: Extension][BetterEm]
+<!-- md:extension [pymdownx.betterem][BetterEm] -->
 
 The [BetterEm] extension improves the detection of Markup to emphasize text
 in Markdown using special characters, i.e. for `**bold**` and `_italic_`
@@ -100,16 +99,15 @@ markdown_extensions:
 ```
 
 The configuration options of this extension are not specific to Material for
-MkDocs, as they only impact the Markdown parsing stage. See the [BetterEm 
+MkDocs, as they only impact the Markdown parsing stage. See the [BetterEm
 documentation][BetterEm] for more information.
 
   [BetterEm]: https://facelessuser.github.io/pymdown-extensions/extensions/betterem/
-  [BetterEm support]: https://github.com/squidfunk/mkdocs-material/releases/tag/0.1.0
 
 ### Caret, Mark & Tilde
 
-[:octicons-tag-24: 1.0.0][Caret support] ·
+<!-- md:version 1.0.0 -->
-[:octicons-workflow-24: Extension][Caret]
+<!-- md:extension [pymdownx.caret][Caret] -->
 
 The [Caret], [Mark] and [Tilde] extensions add the ability to highlight text
 and define sub- and superscript using a simple syntax. Enable them together
@@ -132,7 +130,6 @@ See reference for usage:
 - [Sub- and superscripts]
 
   [Caret]: https://facelessuser.github.io/pymdown-extensions/extensions/caret/
-  [Caret support]: https://github.com/squidfunk/mkdocs-material/releases/tag/1.0.0
   [Mark]: https://facelessuser.github.io/pymdown-extensions/extensions/mark/
   [Tilde]: https://facelessuser.github.io/pymdown-extensions/extensions/tilde/
   [Highlighting text]: ../../reference/formatting.md#highlighting-text
@@ -140,8 +137,8 @@ See reference for usage:
 
 ### Critic
 
-[:octicons-tag-24: 1.0.0][Critic support] ·
+<!-- md:version 1.0.0 -->
-[:octicons-workflow-24: Extension][Critic]
+<!-- md:extension [pymdownx.critic][Critic] -->
 
 The [Critic] extension allows for the usage of [Critic Markup] to highlight
 added, deleted or updated sections in a document, i.e. for tracking changes in
@@ -154,9 +151,9 @@ markdown_extensions:
 
 The following configuration options are supported:
 
-[`mode`](#+pymdownx.critic.mode){ #+pymdownx.critic.mode }
+<!-- md:option pymdownx.critic.mode -->
 
-:   :octicons-milestone-24: Default: `view` – This option defines how the markup 
+:   <!-- md:default `view` --> This option defines how the markup
     should be parsed, i.e. whether to just `view` all suggested changes, or
     alternatively `accept` or `reject` them:
 
@@ -189,14 +186,13 @@ See reference for usage:
 - [Highlighting changes]
 
   [Critic]: https://facelessuser.github.io/pymdown-extensions/extensions/critic/
-  [Critic support]: https://github.com/squidfunk/mkdocs-material/releases/tag/1.0.0
   [Critic Markup]: https://github.com/CriticMarkup/CriticMarkup-toolkit
   [Highlighting changes]: ../../reference/formatting.md#highlighting-changes
 
 ### Details
 
-[:octicons-tag-24: 1.9.0][Details support] ·
+<!-- md:version 1.9.0 -->
-[:octicons-workflow-24: Extension][Details]
+<!-- md:extension [pymdownx.details][Details] -->
 
 The [Details] extension supercharges the [Admonition] extension, making the
 resulting _call-outs_ collapsible, allowing them to be opened and closed by the
@@ -212,14 +208,13 @@ No configuration options are available. See reference for usage:
 - [Collapsible blocks]
 
   [Details]: https://facelessuser.github.io/pymdown-extensions/extensions/details/
-  [Details support]: https://github.com/squidfunk/mkdocs-material/releases/tag/1.9.0
   [Admonition]: python-markdown.md#admonition
   [Collapsible blocks]: ../../reference/admonitions.md#collapsible-blocks
 
 ### Emoji
 
-[:octicons-tag-24: 1.0.0][Emoji support] ·
+<!-- md:version 1.0.0 -->
-[:octicons-workflow-24: Extension][Emoji]
+<!-- md:extension [pymdownx.emoji][Emoji] -->
 
 The [Emoji] extension automatically inlines bundled and custom icons and emojis
 in `*.svg` file format into the resulting HTML page. Enable it via `mkdocs.yml`:
@@ -237,9 +232,9 @@ markdown_extensions:
 
 The following configuration options are supported:
 
-[`emoji_index`](#+pymdownx.emoji.emoji_index){ #+pymdownx.emoji.emoji_index }
+<!-- md:option pymdownx.emoji.emoji_index -->
 
-:   :octicons-milestone-24: Default: `emojione` – This option defines which set
+:   <!-- md:default `emojione` --> This option defines which set
     of emojis is used for rendering. Note that the use of `emojione` is not
     recommended due to [restrictions in licensing][Emoji index]:
 
@@ -249,9 +244,9 @@ The following configuration options are supported:
           emoji_index: !!python/name:materialx.emoji.twemoji
     ```
 
-[`emoji_generator`](#+pymdownx.emoji.emoji_generator){ #+pymdownx.emoji.emoji_generator }
+<!-- md:option pymdownx.emoji.emoji_generator -->
 
-:   :octicons-milestone-24: Default: `to_png` – This option defines how the
+:   <!-- md:default `to_png` --> This option defines how the
     resolved emoji or icon shortcode is render. Note that icons can only be
     used together with the `to_svg` configuration:
 
@@ -261,10 +256,10 @@ The following configuration options are supported:
           emoji_generator: !!python/name:materialx.emoji.to_svg
     ```
 
-[`options.custom_icons`](#+pymdownx.emoji.options.custom_icons){ #+pymdownx.emoji.options.custom_icons }
+<!-- md:option pymdownx.emoji.options.custom_icons -->
 
-:   :octicons-milestone-24: Default: _none_ – This option allows to list folders
+:   <!-- md:default none --> This option allows to list folders
-    with additional icon sets to be used in Markdown or `mkdocs.yml`, which is 
+    with additional icon sets to be used in Markdown or `mkdocs.yml`, which is
     explained in more detail in the [icon customization guide]:
 
     ``` yaml
@@ -288,7 +283,6 @@ See reference for usage:
 - [Using icons in templates]
 
   [Emoji]: https://facelessuser.github.io/pymdown-extensions/extensions/emoji/
-  [Emoji support]: https://github.com/squidfunk/mkdocs-material/releases/tag/1.0.0
   [Emoji index]: https://facelessuser.github.io/pymdown-extensions/extensions/emoji/#default-emoji-indexes
   [icon customization guide]: ../changing-the-logo-and-icons.md#additional-icons
   [Using emojis]: ../../reference/icons-emojis.md#using-emojis
@@ -297,9 +291,8 @@ See reference for usage:
 
 ### Highlight
 
-[:octicons-tag-24: 5.0.0][Highlight support] ·
+<!-- md:version 5.0.0 -->
-[:octicons-workflow-24: Extension][Highlight] ·
+<!-- md:extension [pymdownx.highlight][Highlight] -->
-:octicons-zap-24: Supersedes [CodeHilite]
 
 The [Highlight] extension adds support for syntax highlighting of code blocks
 (with the help of [SuperFences][pymdownx.superfences]) and inline code blocks
@@ -319,9 +312,9 @@ markdown_extensions:
 
 The following configuration options are supported:
 
-[`use_pygments`](#+pymdownx.highlight.use_pygments){ #+pymdownx.highlight.use_pygments }
+<!-- md:option pymdownx.highlight.use_pygments -->
 
-:   :octicons-milestone-24: Default: `true` – This option allows to control
+:   <!-- md:default `true` --> This option allows to control
     whether highlighting should be carried out during build time using
     [Pygments] or in the browser with a JavaScript syntax highlighter:
 
@@ -342,7 +335,7 @@ The following configuration options are supported:
               use_pygments: false
         ```
 
-        As an example, [Highlight.js], a JavaScript syntax highlighter, can be 
+        As an example, [Highlight.js], a JavaScript syntax highlighter, can be
         integrated with some [additional JavaScript] and an [additional style
         sheet] in `mkdocs.yml`:
 
@@ -371,9 +364,9 @@ The following configuration options are supported:
     syntax highlighting using [Pygments], so they don't apply if `use_pygments`
     is set to `false`.
 
-[`pygments_lang_class`](#+pymdownx.highlight.pygments_lang_class){ #+pymdownx.highlight.pygments_lang_class }
+<!-- md:option pymdownx.highlight.pygments_lang_class -->
 
-:   :octicons-milestone-24: Default: `false` – This option instructs [Pygments]
+:   <!-- md:default `false` --> This option instructs [Pygments]
     to add a CSS class to identify the language of the code block, which is
     essential for custom annotation markers to function:
 
@@ -383,9 +376,9 @@ markdown_extensions:
       pygments_lang_class: true
 ```
 
-[`auto_title`](#+pymdownx.highlight.auto_title){ #+pymdownx.highlight.auto_title }
+<!-- md:option pymdownx.highlight.auto_title -->
 
-:   :octicons-milestone-24: Default: `false` – This option will automatically
+:   <!-- md:default `false` --> This option will automatically
     add a [title] to all code blocks that shows the name of the language being
     used, e.g. `Python` is printed for a `py` block:
 
@@ -395,9 +388,9 @@ markdown_extensions:
           auto_title: true
     ```
 
-[`linenums`](#+pymdownx.highlight.linenums){ #+pymdownx.highlight.linenums }
+<!-- md:option pymdownx.highlight.linenums -->
 
-:   :octicons-milestone-24: Default: `false` – This option will add line numbers
+:   <!-- md:default `false` --> This option will add line numbers
     to _all_ code blocks. If you wish to add line numbers to _some_, but not all
     code blocks, consult the section on [adding line numbers][Adding line
     numbers] in the code block reference, which also contains some tips on
@@ -409,9 +402,9 @@ markdown_extensions:
           linenums: true
     ```
 
-[`linenums_style`](#+pymdownx.highlight.linenums_style){ #+pymdownx.highlight.linenums_style }
+<!-- md:option pymdownx.highlight.linenums_style -->
 
-:   :octicons-milestone-24: Default: `table` – The [Highlight] extension
+:   <!-- md:default `table` --> The [Highlight] extension
     provides three ways to add line numbers, two of which are supported by
     Material for MkDocs. While `table` wraps a code block in a `<table>`
     element, `pymdownx-inline` renders line numbers as part of the line itself:
@@ -423,13 +416,13 @@ markdown_extensions:
     ```
 
     Note that `inline` will put line numbers next to the actual code, which
-    means that they will be included when selecting text with the cursor or 
+    means that they will be included when selecting text with the cursor or
     copying a code block to the clipboard. Thus, the usage of either `table`
     or `pymdownx-inline` is recommended.
 
-[`anchor_linenums`](#+pymdownx.highlight.anchor_linenums){ #+pymdownx.highlight.anchor_linenums }
+<!-- md:option pymdownx.highlight.anchor_linenums -->
 
-:   [:octicons-tag-24: 8.1.0][anchor_linenums support] · :octicons-milestone-24:
+:   <!-- md:version 8.1.0 --> :octicons-milestone-24:
     Default: `false` – If a code blocks contains line numbers, enabling this
     setting will wrap them with anchor links, so they can be hyperlinked and
     shared more easily:
@@ -440,9 +433,9 @@ markdown_extensions:
           anchor_linenums: true
     ```
 
-[`line_spans`](#+pymdownx.highlight.line_spans){ #+pymdownx.highlight.line_spans }
+<!-- md:option pymdownx.highlight.line_spans -->
 
-:   :octicons-milestone-24: Default: _none_ – When this option is set, each
+:   <!-- md:default none --> When this option is set, each
     line of a code block is wrapped in a `span`, which is essential for features
     like line highlighting to work correctly:
 
@@ -465,7 +458,6 @@ See reference for usage:
 - [Custom syntax theme]
 
   [Highlight]: https://facelessuser.github.io/pymdown-extensions/extensions/highlight/
-  [Highlight support]: https://github.com/squidfunk/mkdocs-material/releases/tag/5.0.0
   [CodeHilite]: python-markdown.md#codehilite
   [pymdownx.superfences]: #superfences
   [pymdownx.inlinehilite]: #inlinehilite
@@ -473,7 +465,6 @@ See reference for usage:
   [additional style sheet]: ../../customization.md#additional-css
   [Highlight.js]: https://highlightjs.org/
   [title]: ../../reference/code-blocks.md#adding-a-title
-  [anchor_linenums support]: https://github.com/squidfunk/mkdocs-material/releases/tag/8.1.0
   [Adding line numbers]: ../../reference/code-blocks.md#adding-line-numbers
   [Using code blocks]: ../../reference/code-blocks.md#usage
   [Adding a title]: ../../reference/code-blocks.md#adding-a-title
@@ -482,10 +473,10 @@ See reference for usage:
 
 ### InlineHilite
 
-[:octicons-tag-24: 5.0.0][InlineHilite support] ·
+<!-- md:version 5.0.0 -->
-[:octicons-workflow-24: Extension][InlineHilite]
+<!-- md:extension [pymdownx.inlinehilite][InlineHilite] -->
 
-The [InlineHilite] extension add support for syntax highlighting of inline code 
+The [InlineHilite] extension add support for syntax highlighting of inline code
 blocks. It's built on top of the [Highlight][pymdownx.highlight] extension, from
 which it sources its configuration. Enable it via `mkdocs.yml`:
 
@@ -497,7 +488,7 @@ markdown_extensions:
 
 The configuration options of this extension are not specific to Material for
 MkDocs, as they only impact the Markdown parsing stage. The only exception is
-the [`css_class`][InlineHilite options] option, which must not be changed. See the 
+the [`css_class`][InlineHilite options] option, which must not be changed. See the
 [InlineHilite documentation][InlineHilite] for guidance.
 
 See reference for usage:
@@ -505,17 +496,16 @@ See reference for usage:
 - [Highlighting inline code blocks]
 
   [InlineHilite]: https://facelessuser.github.io/pymdown-extensions/extensions/inlinehilite/
-  [InlineHilite support]: https://github.com/squidfunk/mkdocs-material/releases/tag/5.0.0
   [InlineHilite options]: https://facelessuser.github.io/pymdown-extensions/extensions/inlinehilite/#options
   [pymdownx.highlight]: #highlight
   [Highlighting inline code blocks]: ../../reference/code-blocks.md#highlighting-inline-code-blocks
 
 ### Keys
 
-[:octicons-tag-24: 1.0.0][Keys support] ·
+<!-- md:version 1.0.0 -->
-[:octicons-workflow-24: Extension][Keys]
+<!-- md:extension [pymdownx.keys][Keys] -->
 
-The [Keys] extension adds a simple syntax to allow for the rendering of keyboard 
+The [Keys] extension adds a simple syntax to allow for the rendering of keyboard
 keys and combinations, e.g. ++ctrl+alt+del++. Enable it via `mkdocs.yml`:
 
 ``` yaml
@@ -525,7 +515,7 @@ markdown_extensions:
 
 The configuration options of this extension are not specific to Material for
 MkDocs, as they only impact the Markdown parsing stage. The only exception is
-the [`class`][Keys options] option, which must not be changed. See the 
+the [`class`][Keys options] option, which must not be changed. See the
 [Keys documentation][Keys] for more information.
 
 See reference for usage:
@@ -533,16 +523,15 @@ See reference for usage:
 - [Adding keyboard keys]
 
   [Keys]: https://facelessuser.github.io/pymdown-extensions/extensions/keys/
-  [Keys support]: https://github.com/squidfunk/mkdocs-material/releases/tag/1.0.0
   [Keys options]: https://facelessuser.github.io/pymdown-extensions/extensions/keys/#options
   [Adding keyboard keys]: ../../reference/formatting.md#adding-keyboard-keys
 
 ### SmartSymbols
 
-[:octicons-tag-24: 0.1.0][SmartSymbols support] ·
+<!-- md:version 0.1.0 -->
-[:octicons-workflow-24: Extension][SmartSymbols]
+<!-- md:extension [pymdownx.smartsymbols][SmartSymbols] -->
 
-The [SmartSymbols] extension converts some sequences of characters into their 
+The [SmartSymbols] extension converts some sequences of characters into their
 corresponding symbols, e.h. copyright symbols or fractions. Enable it via
 `mkdocs.yml`:
 
@@ -552,16 +541,15 @@ markdown_extensions:
 ```
 
 The configuration options of this extension are not specific to Material for
-MkDocs, as they only impact the Markdown parsing stage. See the [SmartSymbols 
+MkDocs, as they only impact the Markdown parsing stage. See the [SmartSymbols
 documentation][SmartSymbols] for guidance.
 
   [SmartSymbols]: https://facelessuser.github.io/pymdown-extensions/extensions/smartsymbols/
-  [SmartSymbols support]: https://github.com/squidfunk/mkdocs-material/releases/tag/0.1.0
 
 ### Snippets
 
-[:octicons-tag-24: 0.1.0][Snippets support] ·
+<!-- md:version 0.1.0 -->
-[:octicons-workflow-24: Extension][Snippets]
+<!-- md:extension [pymdownx.snippets][Snippets] -->
 
 The [Snippets] extension adds the ability to embed content from arbitrary files
 into a document, including other documents or source files, by using a simple
@@ -573,7 +561,7 @@ markdown_extensions:
 ```
 
 The configuration options of this extension are not specific to Material for
-MkDocs, as they only impact the Markdown parsing stage. See the [Snippets 
+MkDocs, as they only impact the Markdown parsing stage. See the [Snippets
 documentation][Snippets] for more information.
 
 See reference for usage:
@@ -582,15 +570,13 @@ See reference for usage:
 - [Embedding external files]
 
   [Snippets]: https://facelessuser.github.io/pymdown-extensions/extensions/snippets/
-  [Snippets support]: https://github.com/squidfunk/mkdocs-material/releases/tag/0.1.0
   [Adding a glossary]: ../../reference/tooltips.md#adding-a-glossary
   [Embedding external files]: ../../reference/code-blocks.md#embedding-external-files
 
 ### SuperFences
 
-[:octicons-tag-24: 0.1.0][SuperFences support] ·
+<!-- md:version 0.1.0 -->
-[:octicons-workflow-24: Extension][SuperFences] ·
+<!-- md:extension [pymdownx.superfences][SuperFences] -->
-:octicons-zap-24: Supersedes [Fenced Code Blocks]
 
 The [SuperFences] extension allows for arbitrary nesting of code and content
 blocks inside each other, including admonitions, tabs, lists and all other
@@ -603,9 +589,9 @@ markdown_extensions:
 
 The following configuration options are supported:
 
-[`custom_fences`](#+pymdownx.superfences.custom_fences){ #+pymdownx.superfences.custom_fences }
+<!-- md:option pymdownx.superfences.custom_fences -->
 
-:   :octicons-milestone-24: Default: _none_ – This option allows to define a
+:   <!-- md:default none --> This option allows to define a
     handler for custom fences, e.g. to preserve the definitions of [Mermaid.js]
     diagrams to be interpreted in the browser:
 
@@ -638,7 +624,6 @@ See reference for usage:
 - [Using entity-relationship diagrams]
 
   [SuperFences]: https://facelessuser.github.io/pymdown-extensions/extensions/superfences/
-  [SuperFences support]: https://github.com/squidfunk/mkdocs-material/releases/tag/0.1.0
   [Fenced Code Blocks]: python-markdown.md#fenced-code-blocks
   [Mermaid.js]: https://mermaid-js.github.io/mermaid/
   [diagrams]: ../../reference/diagrams.md
@@ -652,8 +637,8 @@ See reference for usage:
 
 ### Tabbed
 
-[:octicons-tag-24: 5.0.0][Tabbed support] ·
+<!-- md:version 5.0.0 -->
-[:octicons-workflow-24: Extension][Tabbed]
+<!-- md:extension [pymdownx.tabbed][Tabbed] -->
 
 The [Tabbed] extension allows the usage of content tabs, a simple way to group
 related content and code blocks under accessible tabs. Enable it via
@@ -667,12 +652,12 @@ markdown_extensions:
 
 The following configuration options are supported:
 
-[`alternate_style`](#+pymdownx.tabbed.alternate_style){ #+pymdownx.tabbed.alternate_style }
+<!-- md:option pymdownx.tabbed.alternate_style -->
 
-:   [:octicons-tag-24: 7.3.1][Tabbed alternate support] ·
+:   <!-- md:version 7.3.1 --> <!-- md:default `false` -->
-    :octicons-milestone-24: Default: `false` · :octicons-alert-24: __Required__
+    <!-- md:flag required -->  This option enables the content tabs
-    –  This option enables the content tabs [alternate style], which has
+    [alternate style], which has [better behavior on mobile viewports], and is
-    [better behavior on mobile viewports], and is the only supported style:
+    the only supported style:
 
     ``` yaml
     markdown_extensions:
@@ -680,9 +665,9 @@ The following configuration options are supported:
           alternate_style: true
     ```
 
-[`slugify`](#+pymdownx.tabbed.slugify){ #+pymdownx.tabbed.slugify }
+<!-- md:option pymdownx.tabbed.slugify -->
 
-:   :octicons-milestone-24: Default: `headerid.slugify` – This option allows for
+:   <!-- md:default `toc.slugify` --> This option allows for
     customization of the slug function. For some languages, the default may not
     produce good and readable identifiers – consider using another slug function
     like for example those from [Python Markdown Extensions][Slugs]:
@@ -716,8 +701,6 @@ See reference for usage:
 - [Embedded content]
 
   [Tabbed]: https://facelessuser.github.io/pymdown-extensions/extensions/tabbed/
-  [Tabbed support]: https://github.com/squidfunk/mkdocs-material/releases/tag/5.0.0
-  [Tabbed alternate support]: https://github.com/squidfunk/mkdocs-material/releases/tag/7.3.1
   [alternate style]: https://facelessuser.github.io/pymdown-extensions/extensions/tabbed/#alternate-style
   [better behavior on mobile viewports]: https://twitter.com/squidfunk/status/1424740370596958214
   [Grouping code blocks]: ../../reference/content-tabs.md#grouping-code-blocks
@@ -727,8 +710,8 @@ See reference for usage:
 
 ### Tasklist
 
-[:octicons-tag-24: 1.0.0][Tasklist support] ·
+<!-- md:version 1.0.0 -->
-[:octicons-workflow-24: Extension][Tasklist]
+<!-- md:extension [pymdownx.tasklist][Tasklist] -->
 
 The [Tasklist] extension allows for the usage of [GitHub Flavored Markdown]
 inspired [task lists][Tasklist specification], following the same syntactical
@@ -742,10 +725,10 @@ markdown_extensions:
 
 The following configuration options are supported:
 
-[`custom_checkbox`](#+pymdownx.tasklist.custom_checkbox){ #+pymdownx.tasklist.custom_checkbox }
+<!-- md:option pymdownx.tasklist.custom_checkbox -->
 
-:   :octicons-milestone-24: Default: `false` · This option toggles the rendering
+:   <!-- md:default `false` --> This option toggles the rendering
-    style of checkboxes, replacing native checkbox styles with beautiful icons, 
+    style of checkboxes, replacing native checkbox styles with beautiful icons,
     and is therefore recommended:
 
     ``` yaml
@@ -754,10 +737,10 @@ The following configuration options are supported:
           custom_checkbox: true
     ```
 
-[`clickable_checkbox`](#+pymdownx.tasklist.clickable_checkbox){ #+pymdownx.tasklist.clickable_checkbox }
+<!-- md:option pymdownx.tasklist.clickable_checkbox -->
 
-:   :octicons-milestone-24: Default: `false` · This option toggles whether
+:   <!-- md:default `false` --> This option toggles whether
-    checkboxes are clickable. As the state is not persisted, the use of this 
+    checkboxes are clickable. As the state is not persisted, the use of this
     option is _rather discouraged_ from a user experience perspective:
 
     ``` yaml
@@ -775,7 +758,6 @@ See reference for usage:
 - [Using task lists]
 
   [Tasklist]: https://facelessuser.github.io/pymdown-extensions/extensions/tasklist/
-  [Tasklist support]: https://github.com/squidfunk/mkdocs-material/releases/tag/1.0.0
   [GitHub Flavored Markdown]: https://github.github.com/gfm/
   [Tasklist specification]: https://github.github.com/gfm/#task-list-items-extension-
   [Using task lists]: ../../reference/lists.md#using-task-lists

docs/setup/extensions/python-markdown.md

@@ -11,8 +11,8 @@ reference for which features they need to be enabled.
 
 ### Abbreviations
 
-[:octicons-tag-24: 1.0.0][Abbreviations support] ·
+<!-- md:version 1.0.0 -->
-[:octicons-workflow-24: Extension][Abbreviations]
+<!-- md:extension [abbr][Abbreviations] -->
 
 The [Abbreviations] extension adds the ability to add a small tooltip to an
 element, by wrapping it with an `abbr` tag. Only plain text (no markup) is
@@ -29,16 +29,15 @@ No configuration options are available. See reference for usage:
 - [Adding a glossary]
 
   [Abbreviations]: https://python-markdown.github.io/extensions/abbreviations/
-  [Abbreviations support]: https://github.com/squidfunk/mkdocs-material/releases/tag/1.0.0
   [Adding abbreviations]: ../../reference/tooltips.md#adding-abbreviations
   [Adding a glossary]: ../../reference/tooltips.md#adding-a-glossary
 
 ### Admonition
 
-[:octicons-tag-24: 0.1.0][Admonition support] ·
+<!-- md:version 0.1.0 -->
-[:octicons-workflow-24: Extension][Admonition]
+<!-- md:extension [admonition][Admonition] -->
 
-The [Admonition] extension adds support for admonitions, more commonly known as 
+The [Admonition] extension adds support for admonitions, more commonly known as
 _call-outs_, which can be defined in Markdown by using a simple syntax. Enable
 it via `mkdocs.yml`:
 
@@ -55,7 +54,6 @@ No configuration options are available. See reference for usage:
 - [Supported types]
 
   [Admonition]: https://python-markdown.github.io/extensions/admonition/
-  [Admonition support]: https://github.com/squidfunk/mkdocs-material/releases/tag/0.1.0
   [Adding admonitions]: ../../reference/admonitions.md#usage
   [Changing the title]: ../../reference/admonitions.md#changing-the-title
   [Removing the title]: ../../reference/admonitions.md#removing-the-title
@@ -63,8 +61,8 @@ No configuration options are available. See reference for usage:
 
 ### Attribute Lists
 
-[:octicons-tag-24: 0.1.0][Attribute Lists support] ·
+<!-- md:version 0.1.0 -->
-[:octicons-workflow-24: Extension][Attribute Lists]
+<!-- md:extension [attr_list][Attribute Lists] -->
 
 The [Attribute Lists] extension allows to add HTML attributes and CSS classes
 to [almost every][Attribute Lists limitations] Markdown inline- and block-level
@@ -87,7 +85,6 @@ No configuration options are available. See reference for usage:
 - [Image lazy-loading]
 
   [Attribute Lists]: https://python-markdown.github.io/extensions/attr_list/
-  [Attribute Lists support]: https://github.com/squidfunk/mkdocs-material/releases/tag/0.1.0
   [Attribute Lists limitations]: https://python-markdown.github.io/extensions/attr_list/#limitations
   [Using grids]: ../../reference/grids.md#using-grids
   [Adding buttons]: ../../reference/buttons.md#adding-buttons
@@ -99,8 +96,8 @@ No configuration options are available. See reference for usage:
 
 ### Definition Lists
 
-[:octicons-tag-24: 1.1.0][Definition Lists support] ·
+<!-- md:version 1.1.0 -->
-[:octicons-workflow-24: Extension][Definition Lists]
+<!-- md:extension [def_list][Definition Lists] -->
 
 The [Definition Lists] extension adds the ability to add definition lists (more
 commonly known as [description lists] – `dl` in HTML) via Markdown to a
@@ -116,14 +113,13 @@ No configuration options are available. See reference for usage:
 - [Using definition lists]
 
   [Definition Lists]: https://python-markdown.github.io/extensions/definition_lists/
-  [Definition Lists support]: https://github.com/squidfunk/mkdocs-material/releases/tag/1.1.0
   [description lists]: https://developer.mozilla.org/en-US/docs/Web/HTML/Element/dl
   [Using definition lists]: ../../reference/lists.md#using-definition-lists
 
 ### Footnotes
 
-[:octicons-tag-24: 1.0.0][Footnotes support] ·
+<!-- md:version 1.0.0 -->
-[:octicons-workflow-24: Extension][Footnotes]
+<!-- md:extension [footnotes][Footnotes] -->
 
 The [Footnotes] extension allows to define inline footnotes, which are then
 rendered below all Markdown content of a document. Enable it via `mkdocs.yml`:
@@ -139,14 +135,13 @@ No configuration options are supported. See reference for usage:
 - [Adding footnote content]
 
   [Footnotes]: https://python-markdown.github.io/extensions/footnotes/
-  [Footnotes support]: https://github.com/squidfunk/mkdocs-material/releases/tag/1.0.0
   [Adding footnote references]: ../../reference/footnotes.md#adding-footnote-references
   [Adding footnote content]: ../../reference/footnotes.md#adding-footnote-content
 
 ### Markdown in HTML
 
-[:octicons-tag-24: 0.1.0][Markdown in HTML support] ·
+<!-- md:version 0.1.0 -->
-[:octicons-workflow-24: Extension][Markdown in HTML]
+<!-- md:extension [md_in_html][Markdown in HTML] -->
 
 The [Markdown in HTML] extension allows for writing Markdown inside of HTML,
 which is useful for wrapping Markdown content with custom elements. Enable it
@@ -170,18 +165,17 @@ No configuration options are available. See reference for usage:
 - [Image captions]
 
   [Markdown in HTML]: https://python-markdown.github.io/extensions/md_in_html/
-  [Markdown in HTML support]: https://github.com/squidfunk/mkdocs-material/releases/tag/0.1.0
   [Using annotations]: ../../reference/annotations.md#usage
   [Using grids]: ../../reference/grids.md#usage
   [Image captions]: ../../reference/images.md#image-captions
 
 ### Table of Contents
 
-[:octicons-tag-24: 0.1.0][Table of Contents support] ·
+<!-- md:version 0.1.0 -->
-[:octicons-workflow-24: Extension][Table of Contents]
+<!-- md:extension [toc][Table of Contents] -->
 
 The [Table of Contents] extension automatically generates a table of contents
-from a document, which Material for MkDocs will render as part of the resulting 
+from a document, which Material for MkDocs will render as part of the resulting
 page. Enable it via `mkdocs.yml`:
 
 ``` yaml
@@ -192,13 +186,12 @@ markdown_extensions:
 
 The following configuration options are supported:
 
-[`title`](#+toc.title){ #+toc.title }
+<!-- md:option toc.title -->
 
-:   [:octicons-tag-24: 7.3.5][title support] ·
+:   <!-- md:version 7.3.5 --> <!-- md:default computed --> –
-    :octicons-milestone-24: Default: _automatically set_ – This option sets the
+    This option sets the title of the table of contents in the right navigation
-    title of the table of contents in the right navigation sidebar, which is
+    sidebar, which is normally automatically sourced from the translations for
-    normally automatically sourced from the translations for the [site language]
+    the [site language] as set in `mkdocs.yml`:
-    as set in `mkdocs.yml`:
 
     ``` yaml
     markdown_extensions:
@@ -206,9 +199,9 @@ The following configuration options are supported:
           title: On this page
     ```
 
-[`permalink`](#+toc.permalink){ #+toc.permalink }
+<!-- md:option toc.permalink -->
 
-:   :octicons-milestone-24: Default: `false` – This option adds an anchor link
+:   <!-- md:default `false` --> This option adds an anchor link
     containing the paragraph symbol `¶` or another custom symbol at the end of
     each headline, exactly like on the page you're currently viewing, which
     Material for MkDocs will make appear on hover:
@@ -229,11 +222,11 @@ The following configuration options are supported:
               permalink: ⚓︎
         ```
 
-[`permalink_title`](#+toc.permalink_title){ #+toc.permalink_title }
+<!-- md:option toc.permalink_title -->
 
-:   :octicons-milestone-24: Default: `Permanent link` – This option sets the
+:   <!-- md:default `Permanent link` --> This option sets the
     title of the anchor link which is shown on hover and read by screen readers.
-    For accessibility reasons, it might be beneficial to change it to a more 
+    For accessibility reasons, it might be beneficial to change it to a more
     discernable name, stating that the anchor links to the section itself:
 
     ``` yaml
@@ -242,9 +235,9 @@ The following configuration options are supported:
           permalink_title: Anchor link to this section for reference
     ```
 
-[`slugify`](#+toc.slugify){ #+toc.slugify }
+<!-- md:option toc.slugify -->
 
-:   :octicons-milestone-24: Default: `headerid.slugify` – This option allows for
+:   <!-- md:default `toc.slugify` --> This option allows for
     customization of the slug function. For some languages, the default may not
     produce good and readable identifiers – consider using another slug function
     like for example those from [Python Markdown Extensions][Slugs]:
@@ -267,9 +260,9 @@ The following configuration options are supported:
               slugify: !!python/object/apply:pymdownx.slugs.slugify
         ```
 
-[`toc_depth`](#+toc.toc_depth){ #+toc.toc_depth }
+<!-- md:option toc.toc_depth -->
 
-:   :octicons-milestone-24: Default: `6` – Define the range of levels to be
+:   <!-- md:default `6` --> Define the range of levels to be
     included in the table of contents. This may be useful for project
     documentation with deeply structured headings to decrease the length of the
     table of contents, or to remove the table of contents altogether:
@@ -295,17 +288,15 @@ by Material for MkDocs, which is why they may yield unexpected results. Use
 them at your own risk.
 
   [Table of Contents]: https://python-markdown.github.io/extensions/toc/
-  [Table of Contents support]: https://github.com/squidfunk/mkdocs-material/releases/tag/0.1.0
-  [title support]: https://github.com/squidfunk/mkdocs-material/releases/tag/7.3.5
   [site language]: ../changing-the-language.md#site-language
   [Slugs]: https://facelessuser.github.io/pymdown-extensions/extras/slugs/
 
 ### Tables
 
-[:octicons-tag-24: 0.1.0][Tables support] ·
+<!-- md:version 0.1.0 -->
-[:octicons-workflow-24: Extension][Tables]
+<!-- md:extension [tables][Tables] -->
 
-The [Tables] extension adds the ability to create tables in Markdown by using a 
+The [Tables] extension adds the ability to create tables in Markdown by using a
 simple syntax. Enable it via `mkdocs.yml` (albeit it should be enabled by
 default):
 
@@ -320,36 +311,34 @@ No configuration options are available. See reference for usage:
 - [Column alignment]
 
   [Tables]: https://python-markdown.github.io/extensions/tables/
-  [Tables support]: https://github.com/squidfunk/mkdocs-material/releases/tag/0.1.0
   [Using data tables]: ../../reference/data-tables.md#usage
   [Column alignment]: ../../reference/data-tables.md#column-alignment
 
 ## Superseded extensions
 
-The following [Python Markdown] extensions are not (or might not be) supported 
+The following [Python Markdown] extensions are not (or might not be) supported
 anymore, and are therefore not recommended for use. Instead, the alternatives
 should be considered.
 
 ### Fenced Code Blocks
 
-[:octicons-tag-24: 0.1.0][Fenced Code Blocks support] ·
+<!-- md:version 0.1.0 -->
-[:octicons-workflow-24: Extension][Fenced Code Blocks]
+<!-- md:extension [fenced_code_blocks][Fenced Code Blocks] -->
 
 Superseded by [SuperFences]. This extension might still work, but the
-[SuperFences] extension is superior in many ways, as it allows for arbitrary 
+[SuperFences] extension is superior in many ways, as it allows for arbitrary
 nesting, and is therefore recommended.
 
   [Fenced Code Blocks]: https://python-markdown.github.io/extensions/fenced_code_blocks/
-  [Fenced Code Blocks support]: https://github.com/squidfunk/mkdocs-material/releases/tag/0.1.0
   [SuperFences]: https://facelessuser.github.io/pymdown-extensions/extensions/superfences/
 
 ### CodeHilite
 
-[:octicons-tag-24: 0.1.0 ... 5.5.14][CodeHilite support] ·
+<!-- md:version 0.1.0 -->
-[:octicons-workflow-24: Extension][CodeHilite]
+<!-- md:extension [codehilite][CodeHilite] -->
 
 Superseded by [Highlight]. Support for CodeHilite was dropped in
-:octicons-tag-24: 6.0.0, as [Highlight] has a better integration with other 
+<!-- md:version 6.0.0 -->, as [Highlight] has a better integration with other
 essential extensions like [SuperFences] and [InlineHilite].
 
   [CodeHilite]: https://python-markdown.github.io/extensions/code_hilite/

docs/setup/index.md

@@ -16,7 +16,7 @@ setting up site search, and more.
 - :fontawesome-solid-earth-americas: __[Language]__ – Choose out of the 60+ supported languages or add a new one
 - :material-page-layout-sidebar-left: __[Navigation]__ – Create a clear, concise, and comprehensive navigation structure
 - :material-page-layout-header: __[Header]__ – Customize the behavior of the header, add an announcement bar
-- :material-page-layout-footer: __[Footer]__ – Add links to your social media profiles or websites in the footer 
+- :material-page-layout-footer: __[Footer]__ – Add links to your social media profiles or websites in the footer
 - :material-tab-search: __[Search]__ – Set up and configure search, running entirely in the user's browser
 - :material-tag-plus-outline: __[Tags]__ – Categorize your pages with tags and group related pages
 
@@ -66,7 +66,7 @@ versioned documentation that matches your project's versioning methodology.
 
   [Blog]: setting-up-a-blog.md
   [Comment System]: adding-a-comment-system.md
-  [Versioning]: setting-up-versioning.md  
+  [Versioning]: setting-up-versioning.md
   [Repository]: adding-a-git-repository.md
 
 ## Optimization

docs/setup/setting-up-navigation.md

@@ -1,6 +1,6 @@
 # Setting up navigation
 
-A clear and concise navigation structure is an important aspect of good project 
+A clear and concise navigation structure is an important aspect of good project
 documentation. Material for MkDocs provides a multitude of options to configure
 the behavior of navigational elements, including [tabs] and [sections], and one
 of its flagship features: [instant loading].
@@ -13,8 +13,8 @@ of its flagship features: [instant loading].
 
 ### Instant loading
 
-[:octicons-tag-24: 5.0.0][Instant loading support] ·
+<!-- md:version 5.0.0 -->
-:octicons-unlock-24: Feature flag
+<!-- md:feature -->
 
 When instant loading is enabled, clicks on all internal links will be
 intercepted and dispatched via [XHR] without fully reloading the page. Add
@@ -31,14 +31,14 @@ are rebound automatically, i.e., __Material for MkDocs now behaves like a Single
 Page Application__. Now, the search index survives navigation, which is
 especially useful for large documentation sites.
 
-  [Instant loading support]: https://github.com/squidfunk/mkdocs-material/releases/tag/5.0.0
   [XHR]: https://developer.mozilla.org/en-US/docs/Web/API/XMLHttpRequest
 
 #### Instant prefetching :material-alert-decagram:{ .mdx-pulse title="Added on June 15, 2023" }
 
-[:octicons-heart-fill-24:{ .mdx-heart } Sponsors only][Insiders]{ .mdx-insiders } ·
+<!-- md:sponsors -->
-[:octicons-tag-24: insiders-4.36.0][Insiders] ·
+<!-- md:version insiders-4.36.0 -->
-:octicons-beaker-24: Experimental
+<!-- md:feature -->
+<!-- md:flag experimental -->
 
 Instant prefetching is a new experimental feature that will start to fetch a
 page once the user hovers over a link. This will reduce the perceived loading
@@ -52,12 +52,10 @@ theme:
     - navigation.instant.prefetch
 ```
 
-  [Insiders]: ../insiders/index.md
-
 ### Anchor tracking
 
-[:octicons-tag-24: 8.0.0][Anchor tracking support] ·
+<!-- md:version 8.0.0 -->
-:octicons-unlock-24: Feature flag
+<!-- md:feature -->
 
 When anchor tracking is enabled, the URL in the address bar is automatically
 updated with the active anchor as highlighted in the table of contents. Add the
@@ -69,24 +67,22 @@ theme:
     - navigation.tracking
 ```
 
-  [Anchor tracking support]: https://github.com/squidfunk/mkdocs-material/releases/tag/8.0.0
-
 ### Navigation tabs
 
-[:octicons-tag-24: 1.1.0][Navigation tabs support] ·
+<!-- md:version 1.1.0 -->
-:octicons-unlock-24: Feature flag
+<!-- md:feature -->
 
 When tabs are enabled, top-level sections are rendered in a menu layer below
 the header for viewports above `1220px`, but remain as-is on mobile.[^1] Add
 the following lines to `mkdocs.yml`:
 
   [^1]:
-    Prior to :octicons-tag-24: 6.2.0, navigation tabs had a slightly different
+    Prior to <!-- md:version 6.2.0 -->, navigation tabs had a slightly different
     behavior. All top-level pages (i.e. all top-level entries directly
     referring to a `*.md` file) defined inside the `nav` entry of `mkdocs.yml`
     were grouped under the first tab which received the title of the first page.
     This made it impossible to include a top-level page (or external link) as a
-    tab item, as was reported in #1884 and #2072. From :octicons-tag-24: 6.2.0
+    tab item, as was reported in #1884 and #2072. From <!-- md:version 6.2.0 -->
     on, navigation tabs include all top-level pages and sections.
 
 ``` yaml
@@ -103,14 +99,13 @@ theme:
 
     [![Navigation tabs disabled]][Navigation tabs disabled]
 
-  [Navigation tabs support]: https://github.com/squidfunk/mkdocs-material/releases/tag/1.1.0
   [Navigation tabs enabled]: ../assets/screenshots/navigation-tabs.png
   [Navigation tabs disabled]: ../assets/screenshots/navigation.png
 
 #### Sticky navigation tabs
 
-[:octicons-tag-24: 7.3.0][Sticky navigation tabs support] ·
+<!-- md:version 7.3.0 -->
-:octicons-unlock-24: Feature flag
+<!-- md:feature -->
 
 When sticky tabs are enabled, navigation tabs will lock below the header and
 always remain visible when scrolling down. Just add the following two feature
@@ -131,14 +126,13 @@ theme:
 
     [![Sticky navigation tabs disabled]][Sticky navigation tabs disabled]
 
-  [Sticky navigation tabs support]: https://github.com/squidfunk/mkdocs-material/releases/tag/7.3.0
   [Sticky navigation tabs enabled]: ../assets/screenshots/navigation-tabs-sticky.png
   [Sticky navigation tabs disabled]: ../assets/screenshots/navigation-tabs-collapsed.png
 
 ### Navigation sections
 
-[:octicons-tag-24: 6.2.0][Navigation sections support] ·
+<!-- md:version 6.2.0 -->
-:octicons-unlock-24: Feature flag
+<!-- md:feature -->
 
 When sections are enabled, top-level sections are rendered as groups in the
 sidebar for viewports above `1220px`, but remain as-is on mobile. Add the
@@ -158,7 +152,6 @@ theme:
 
     [![Navigation sections disabled]][Navigation sections disabled]
 
-  [Navigation sections support]: https://github.com/squidfunk/mkdocs-material/releases/tag/6.2.0
   [Navigation sections enabled]: ../assets/screenshots/navigation-sections.png
   [Navigation sections disabled]: ../assets/screenshots/navigation.png
 
@@ -168,8 +161,8 @@ feature flags are enabled, sections are rendered for level 2 navigation items.
 
 ### Navigation expansion
 
-[:octicons-tag-24: 6.2.0][Navigation expansion support] ·
+<!-- md:version 6.2.0 -->
-:octicons-unlock-24: Feature flag
+<!-- md:feature -->
 
 When expansion is enabled, the left sidebar will expand all collapsible
 subsections by default, so the user doesn't have to open subsections manually.
@@ -189,15 +182,15 @@ theme:
 
     [![Navigation expansion disabled]][Navigation expansion disabled]
 
-  [Navigation expansion support]: https://github.com/squidfunk/mkdocs-material/releases/tag/6.2.0
   [Navigation expansion enabled]: ../assets/screenshots/navigation-expand.png
   [Navigation expansion disabled]: ../assets/screenshots/navigation.png
 
 ### Navigation path <small>Breadcrumbs</small> { id=navigation-path }
 
-[:octicons-heart-fill-24:{ .mdx-heart } Sponsors only][Insiders]{ .mdx-insiders } ·
+<!-- md:sponsors -->
-[:octicons-tag-24: insiders-4.28.0][Insiders] ·
+<!-- md:version insiders-4.28.0 -->
-:octicons-beaker-24: Experimental
+<!-- md:feature -->
+<!-- md:flag experimental -->
 
 When navigation paths are activated, a breadcrumb navigation is rendered above
 the title of each page, which might make orientation easier for users visiting your
@@ -223,11 +216,12 @@ theme:
 
 ### Navigation pruning
 
-[:octicons-tag-24: 9.2.0][Navigation pruning support] ·
+<!-- md:version 9.2.0 -->
-:octicons-beaker-24: Experimental
+<!-- md:feature -->
+<!-- md:flag experimental -->
 
-When pruning is enabled, only the visible navigation items are included in the 
+When pruning is enabled, only the visible navigation items are included in the
-rendered HTML, __reducing the size of the built site by 33% or more__. Add the 
+rendered HTML, __reducing the size of the built site by 33% or more__. Add the
 following lines to `mkdocs.yml`:
 
 ``` yaml
@@ -245,13 +239,12 @@ This feature flag is especially useful for documentation sites with 100+ or even
 Navigation pruning will replace all expandable sections with links to the first
 page in that section (or the section index page).
 
-  [Navigation pruning support]: https://github.com/squidfunk/mkdocs-material/releases/tag/9.2.0
   [navigation.expand]: #navigation-expansion
 
 ### Section index pages
 
-[:octicons-tag-24: 7.3.0][Section index pages support] ·
+<!-- md:version 7.3.0 -->
-:octicons-unlock-24: Feature flag
+<!-- md:feature -->
 
 When section index pages are enabled, documents can be directly attached to
 sections, which is particularly useful for providing overview pages. Add the
@@ -289,7 +282,6 @@ nav:
 
 1.  MkDocs also considers files called `README.md` as [index pages].
 
-  [Section index pages support]: https://github.com/squidfunk/mkdocs-material/releases/tag/7.3.0
   [Section index pages enabled]: ../assets/screenshots/navigation-index-on.png
   [Section index pages disabled]: ../assets/screenshots/navigation-index-off.png
   [toc.integrate]: #navigation-integration
@@ -299,8 +291,9 @@ nav:
 
 #### Anchor following
 
-[:octicons-tag-24: 8.5.0][Anchor following support] ·
+<!-- md:version 8.5.0 -->
-:octicons-beaker-24: Experimental
+<!-- md:feature -->
+<!-- md:flag experimental -->
 
 When anchor following for the [table of contents] is enabled, the sidebar is
 automatically scrolled so that the active anchor is always visible. Add the
@@ -312,12 +305,10 @@ theme:
     - toc.follow
 ```
 
-  [Anchor following support]: https://github.com/squidfunk/mkdocs-material/releases/tag/8.5.0
-
 #### Navigation integration
 
-[:octicons-tag-24: 6.2.0][Navigation integration support] ·
+<!-- md:version 6.2.0 -->
-:octicons-unlock-24: Feature flag
+<!-- md:feature -->
 
 When navigation integration for the [table of contents] is enabled, it is always
 rendered as part of the navigation sidebar on the left. Add the following lines
@@ -342,15 +333,14 @@ theme:
     [![Navigation integration disabled]][Navigation integration disabled]
 
   [table of contents]: extensions/python-markdown.md#table-of-contents
-  [Navigation integration support]: https://github.com/squidfunk/mkdocs-material/releases/tag/7.3.0
   [Navigation integration enabled]: ../assets/screenshots/toc-integrate.png
   [Navigation integration disabled]: ../assets/screenshots/navigation-tabs.png
   [navigation.indexes]: #section-index-pages
 
 ### Back-to-top button
 
-[:octicons-tag-24: 7.1.0][Back-to-top button support] ·
+<!-- md:version 7.1.0 -->
-:octicons-unlock-24: Feature flag
+<!-- md:feature -->
 
 A back-to-top button can be shown when the user, after scrolling down, starts
 to scroll up again. It's rendered centered and just below the header. Add the
@@ -362,14 +352,15 @@ theme:
     - navigation.top
 ```
 
-  [Back-to-top button support]: https://github.com/squidfunk/mkdocs-material/releases/tag/7.1.0
-
 ## Usage
 
 ### Hiding the sidebars
 
+<!-- md:version 6.2.0 -->
+<!-- md:flag metadata -->
+
 The navigation and/or table of contents sidebars can be hidden for a document
-with the front matter `hide` property. Add the following lines at the top of a 
+with the front matter `hide` property. Add the following lines at the top of a
 Markdown file:
 
 ``` yaml
@@ -379,7 +370,7 @@ hide:
   - toc
 ---
 
-# Document title
+# Page title
 ...
 ```
 
@@ -401,6 +392,10 @@ hide:
 
 ### Hiding the navigation path
 
+<!-- md:sponsors -->
+<!-- md:version insiders-4.28.0 -->
+<!-- md:flag metadata -->
+
 While the [navigation path] is rendered above the main headline, sometimes, it
 might be desirable to hide it for a specific page, which can be achieved with
 the front matter `hide` property:
@@ -411,7 +406,7 @@ hide:
   - path
 ---
 
-# Document title
+# Page title
 ...
 ```
 
@@ -424,7 +419,7 @@ hide:
 Material for MkDocs includes several keyboard shortcuts that make it possible
 to navigate your project documentation via keyboard. There are two modes:
 
-[`search`](#mode:search){ #mode:search }
+<!-- md:option mode:search -->
 
 :   This mode is active when the _search is focused_. It provides several key
     bindings to make search accessible and navigable via keyboard:
@@ -433,7 +428,7 @@ to navigate your project documentation via keyboard. There are two modes:
     * ++esc++ , ++tab++ : close search dialog
     * ++enter++ : follow selected result
 
-[`global`](#mode:global){ #mode:global }
+<!-- md:option mode:global -->
 
 :   This mode is active when _search is not focussed_ and when there's no other
     focussed element that is susceptible to keyboard input. The following keys

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

@@ -13,8 +13,8 @@ MkDocs natively integrates with [Google Analytics] and offers a customizable
 
 ### Google Analytics
 
-[:octicons-tag-24: 7.1.8][Google Analytics support] ·
+<!-- md:version 7.1.8 -->
-:octicons-milestone-24: Default: _none_
+<!-- md:default none -->
 
 Material for MkDocs integrates natively with Google Analytics 4[^1]. If you
 already set up Google Analytics and have a property, enable it by adding the
@@ -32,8 +32,6 @@ extra:
     property: G-XXXXXXXXXX
 ```
 
-  [Google Analytics support]: https://github.com/squidfunk/mkdocs-material/releases/tag/7.1.8
-
 ??? question "How to measure site search usage?"
 
     Besides page views and events, [site search] can be tracked to better
@@ -50,8 +48,8 @@ extra:
 
 ### Was this page helpful?
 
-[:octicons-tag-24: 8.4.0][Was this page helpful? support] ·
+<!-- md:version 8.4.0 -->
-:octicons-milestone-24: Default: _none_
+<!-- md:default none -->
 
 A simple [feedback widget] can be included at the bottom of each page,
 encouraging users to give instant feedback whether a page was helpful or not.
@@ -85,7 +83,7 @@ extra:
 
 Both properties, `title` and `ratings`, are required. Note that it's allowed to
 define more than two ratings, e.g. to implement a 1-5 star rating. Since the
-feedback widget sends data to a third-party service, it is, of course, natively 
+feedback widget sends data to a third-party service, it is, of course, natively
 integrated with the [cookie consent] feature[^2].
 
   [^2]:
@@ -103,7 +101,7 @@ integrated with the [cookie consent] feature[^2].
     2.  Go to the __configure__ page on the left hand menu, then select
         __custom definitions__
 
-    3.  Click the __custom metrics__ tab and then __create custom metrics__, 
+    3.  Click the __custom metrics__ tab and then __create custom metrics__,
         enter the following values:
 
         * Metric name: Page helpful
@@ -121,7 +119,7 @@ integrated with the [cookie consent] feature[^2].
           (the custom metric created in step 3)
         * Rows: `Page location`
         * Values: Drag in both `Event count` and `Page helpful`
-        * Filters: Add a new filter for 
+        * Filters: Add a new filter for
           `Event name / exactly matches / feedback`
 
     !!! warning "Delay in data availability"
@@ -143,9 +141,9 @@ integrated with the [cookie consent] feature[^2].
 
 The following properties are available for each rating:
 
-[`icon`](#+analytics.feedback.ratings.icon){ #+analytics.feedback.ratings.icon }
+<!-- md:option analytics.feedback.ratings.icon -->
 
-:   :octicons-milestone-24: Default: _none_ · :octicons-alert-24: __Required__ –
+:   <!-- md:default none --> <!-- md:flag required -->
     This property must point to a valid icon path referencing [any icon bundled
     with the theme][custom icons], or the build will not succeed. Some popular
     combinations:
@@ -154,24 +152,24 @@ The following properties are available for each rating:
     * :material-thumb-up-outline: + :material-thumb-down-outline: – `material/thumb-up-outline` + `material/thumb-down-outline`
     * :material-heart: + :material-heart-broken: – `material/heart` + `material/heart-broken`
 
-[`name`](#+analytics.feedback.ratings.name){ #+analytics.feedback.ratings.name }
+<!-- md:option analytics.feedback.ratings.name -->
 
-:   :octicons-milestone-24: Default: _none_ · :octicons-alert-24: __Required__ –
+:   <!-- md:default none --> <!-- md:flag required -->
     The value of this property is shown on user interaction (i.e. keyboard focus
     or mouse hover), explaining the meaning of the rating behind the icon.
 
-[`data`](#+analytics.feedback.ratings.data){ #+analytics.feedback.ratings.data }
+<!-- md:option analytics.feedback.ratings.data -->
 
-:   :octicons-milestone-24: Default: _none_ · :octicons-alert-24: __Required__ –
+:   <!-- md:default none --> <!-- md:flag required -->
     The value of this property is sent as a data value with the custom event
     that is transmitted to Google Analytics[^3] (or any custom integration).
 
   [^3]:
     Note that for Google Analytics, the data value must be an integer.
 
-[`note`](#+analytics.feedback.ratings.note){ #+analytics.feedback.ratings.note }
+<!-- md:option analytics.feedback.ratings.note -->
 
-:   :octicons-milestone-24: Default: _none_ · :octicons-alert-24: __Required__ –
+:   <!-- md:default none --> <!-- md:flag required -->
     The value of this property is shown after the user selected the rating.
     It may contain arbitrary HTML tags, which is especially useful to ask the
     user to provide more detailed feedback for the current page through a form.
@@ -185,7 +183,7 @@ The following properties are available for each rating:
     https://github.com/.../issues/new/?title=[Feedback]+{title}+-+{url}
     ```
 
-    In this example, when clicking the link, the user is redirected to the "new 
+    In this example, when clicking the link, the user is redirected to the "new
     issue" form of your repository, with a pre-filled title including the path
     of the current document, e.g.:
 
@@ -195,7 +193,6 @@ The following properties are available for each rating:
 
     An alternative to GitHub issues is [Google Forms].
 
-  [Was this page helpful? support]: https://github.com/squidfunk/mkdocs-material/releases/tag/8.4.0
   [feedback widget]: #feedback
   [analytics]: #google-analytics
   [feedback report]: ../assets/screenshots/feedback-report.png
@@ -216,7 +213,7 @@ hide:
   - feedback
 ---
 
-# Document title
+# Page title
 ...
 ```
 
@@ -224,7 +221,7 @@ hide:
 
 ### Custom site analytics
 
-In order to integrate another analytics service provider offering a 
+In order to integrate another analytics service provider offering a
 JavaScript-based tracking solution, just follow the guide on [theme extension]
 and create a new partial in the `overrides` folder. The name of the partial is
 used to configure the custom integration via `mkdocs.yml`:

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

@@ -16,11 +16,11 @@ not be compliant with privacy regulations. Moreover, search even works
 
 ### Built-in search plugin
 
-[:octicons-tag-24: 0.1.0][Search support] ·
+<!-- md:version 0.1.0 -->
-:octicons-cpu-24: Plugin
+<!-- md:plugin -->
 
 The built-in search plugin integrates seamlessly with Material for MkDocs,
-adding multilingual client-side search with [lunr] and [lunr-languages]. It's 
+adding multilingual client-side search with [lunr] and [lunr-languages]. It's
 enabled by default, but must be re-added to `mkdocs.yml` when other plugins
 are used:
 
@@ -29,227 +29,18 @@ plugins:
   - search
 ```
 
-The following configuration options are supported:
+For a list of all settings, please consult the [plugin documentation].
 
-[`lang`](#+search.lang){ #+search.lang }
+  [plugin documentation]: ../plugins/search.md
 
-:   :octicons-milestone-24: Default: _automatically set_ – This option allows
-    to include the language-specific stemmers provided by [lunr-languages].
-    Note that Material for MkDocs will set this automatically based on the
-    [site language], but it may be overridden, e.g. to support multiple
-    languages:
-
-    === "A single language"
-
-        ``` yaml
-        plugins:
-          - search:
-              lang: en
-        ```
-
-    === "Multiple languages"
-
-        ``` yaml
-        plugins:
-          - search:
-              lang: # (1)!
-                - en
-                - de
-        ```
-
-        1.  Be aware that including support for other languages increases the
-            general JavaScript payload by around 20kb (before `gzip`) and by
-            another 15-30kb per language.
-
-    The following languages are supported by [lunr-languages]:
-
-    <div class="mdx-columns" markdown>
-
-    - `ar` – Arabic
-    - `da` – Danish
-    - `de` – German
-    - `du` – Dutch
-    - `en` – English
-    - `es` – Spanish
-    - `fi` – Finnish
-    - `fr` – French
-    - `hi` – Hindi
-    - `hu` – Hungarian
-    - `hy` – Armenian
-    - `it` – Italian
-    - `ja` – Japanese
-    - `kn` - Kannada
-    - `ko` – Korean
-    - `no` – Norwegian
-    - `pt` – Portuguese
-    - `ro` – Romanian
-    - `ru` – Russian
-    - `sa` – Sanskrit
-    - `sv` – Swedish
-    - `ta` – Tamil
-    - `te` – Telugu
-    - `th` – Thai
-    - `tr` – Turkish
-    - `vi` – Vietnamese
-    - `zh` – Chinese
-
-    </div>
-
-    Material for MkDocs goes to great lengths to support languages that are not
-    part of this list by automatically falling back to the stemmer yielding the
-    best result.
-
-[`separator`](#+search.separator){ #+search.separator }
-
-:   :octicons-milestone-24: Default: _automatically set_ – The separator for
-    indexing and query tokenization can be customized, making it possible to
-    index parts of words separated by other characters than whitespace and `-`,
-    e.g. by including `.`:
-
-    ``` yaml
-    plugins:
-      - search:
-          separator: '[\s\-\.]+'
-    ```
-
-    With :octicons-tag-24: 9.0.0, a faster and more flexible tokenizer method
-    is shipped, allowing for __tokenizing with lookahead__, which yields more
-    influence on the way documents are indexed. As a result, we use the
-    following separator setting for this site's search:
-
-    ``` yaml
-    plugins:
-      - search:
-          separator: '[\s\-,:!=\[\]()"/]+|(?!\b)(?=[A-Z][a-z])|\.(?!\d)|&[lg]t;'
-    ```
-
-    Broken into its parts, the separator induces the following behavior:
-
-    === "Special characters"
-
-        ```
-        [\s\-,:!=\[\]()"/]+
-        ```
-
-        The first part of the expression inserts token boundaries for each
-        document before and after whitespace, hyphens, commas, brackets and
-        other special characters. If several of those special characters are
-        adjacent, they are treated as one.
-
-    === "Case changes"
-
-        ```
-        (?!\b)(?=[A-Z][a-z])
-        ```
-
-        Many programming languages have naming conventions like `PascalCase` or
-        `camelCase`. By adding this subexpression to the separator,
-        [words are split at case changes], tokenizing the word `PascalCase`
-        into `Pascal` and `Case`.
-
-        [:octicons-arrow-right-24: Read more on tokenizing case changes]
-        [tokenize case changes]
-
-    === "Version strings"
-
-        ```
-        \.(?!\d)
-        ```
-
-        When adding `.` to the separator, version strings like `1.2.3` are split
-        into `1`, `2` and `3`, which makes them undiscoverable via search. When
-        using this subexpression, a small lookahead is introduced which will
-        [preserve version strings] and keep them discoverable.
-
-        [:octicons-arrow-right-24: Read more on tokenizing version numbers]
-        [tokenize version numbers]
-
-    === "HTML/XML tags"
-
-        ```
-        &[lg]t;
-        ```
-
-        If your documentation includes HTML/XML code examples, you may want to allow
-        users to find specific tag names. Unfortunately, the `<` and `>` control
-        characters are encoded in code blocks as `&lt;` and `&gt;`. Adding this
-        subexpression to the separator allows for just that.
-
-        [:octicons-arrow-right-24: Read more on tokenizing HTML/XML tags]
-        [tokenize html-xml tags]
-
-  [Search support]: https://github.com/squidfunk/mkdocs-material/releases/tag/0.1.0
   [lunr]: https://lunrjs.com
   [lunr-languages]: https://github.com/MihaiValentin/lunr-languages
-  [lunr's default tokenizer]: https://github.com/olivernn/lunr.js/blob/aa5a878f62a6bba1e8e5b95714899e17e8150b38/lunr.js#L413-L456
-  [site language]: changing-the-language.md#site-language
-  [words are split at case changes]: ?q=searchHighlight
-  [preserve version strings]: ?q=9.0.0
-  [tokenize case changes]: ../blog/posts/search-better-faster-smaller.md#case-changes
-  [tokenize version numbers]: ../blog/posts/search-better-faster-smaller.md#version-numbers
-  [tokenize html-xml tags]: ../blog/posts/search-better-faster-smaller.md#htmlxml-tags
-
-#### Chinese language support
-
-[:octicons-tag-24: 9.2.0][Chinese language support] ·
-:octicons-beaker-24: Experimental
-
-In order to add support for Chinese languages to the [built-in search plugin],
-install the text segmentation library [jieba] via `pip`, and the plugin will
-run all text through the segmenter:
-
-``` sh
-pip install jieba
-```
-
-The following configuration options are available:
-
-[`jieba_dict`](#+search.jieba_dict){ #+search.jieba_dict }
-
-:   :octicons-milestone-24: Default: _none_ – This option allows for specifying
-    a [custom dictionary] to be used by [jieba] for segmenting text, replacing
-    the default dictionary:
-
-    ``` yaml
-    plugins:
-      - search:
-          jieba_dict: dict.txt # (1)!
-    ```
-
-    1.  The following alternative dictionaries are provided by [jieba]:
-
-        - [dict.txt.small] – 占用内存较小的词典文件
-        - [dict.txt.big] – 支持繁体分词更好的词典文件
-
-[`jieba_dict_user`](#+search.jieba_dict_user){ #+search.jieba_dict_user }
-
-:   :octicons-milestone-24: Default: _none_ – This option allows for specifying
-    an additional [user dictionary] to be used by [jieba] for segmenting text, 
-    augmenting the default dictionary:
-
-    ``` yaml
-    plugins:
-      - search:
-          jieba_dict_user: user_dict.txt
-    ```
-
-    User dictionaries can be used for tuning the segmenter to preserve
-    technical terms.
-
-  [Chinese language support]: https://github.com/squidfunk/mkdocs-material/releases/tag/9.2.0
-  [chinese search]: ../blog/posts/chinese-search-support.md
-  [jieba]: https://pypi.org/project/jieba/
-  [built-in search plugin]: #built-in-search-plugin
-  [custom dictionary]: https://github.com/fxsjy/jieba#%E5%85%B6%E4%BB%96%E8%AF%8D%E5%85%B8
-  [dict.txt.small]: https://github.com/fxsjy/jieba/raw/master/extra_dict/dict.txt.small
-  [dict.txt.big]: https://github.com/fxsjy/jieba/raw/master/extra_dict/dict.txt.big
-  [user dictionary]: https://github.com/fxsjy/jieba#%E8%BD%BD%E5%85%A5%E8%AF%8D%E5%85%B8
 
 ### Search suggestions
 
-[:octicons-tag-24: 7.2.0][Search suggestions support] ·
+<!-- md:version 7.2.0 -->
-:octicons-unlock-24: Feature flag ·
+<!-- md:feature -->
-:octicons-beaker-24: Experimental
+<!-- md:flag experimental -->
 
 When search suggestions are enabled, the search will display the likeliest
 completion for the last word which can be accepted with the ++arrow-right++ key.
@@ -264,14 +55,13 @@ theme:
 Searching for [:octicons-search-24: search su][Search suggestions example]
 yields ^^search suggestions^^ as a suggestion.
 
-  [Search suggestions support]: https://github.com/squidfunk/mkdocs-material/releases/tag/7.2.0
   [Search suggestions example]: ?q=search+su
 
 ### Search highlighting
 
-[:octicons-tag-24: 7.2.0][Search highlighting support] ·
+<!-- md:version 7.2.0 -->
-:octicons-unlock-24: Feature flag ·
+<!-- md:feature -->
-:octicons-beaker-24: Experimental
+<!-- md:flag experimental -->
 
 When search highlighting is enabled and a user clicks on a search result,
 Material for MkDocs will highlight all occurrences after following the link.
@@ -286,13 +76,12 @@ theme:
 Searching for [:octicons-search-24: code blocks][Search highlighting example]
 highlights all occurrences of both terms.
 
-  [Search highlighting support]: https://github.com/squidfunk/mkdocs-material/releases/tag/7.2.0
   [Search highlighting example]: ../reference/code-blocks.md?h=code+blocks
 
 ### Search sharing
 
-[:octicons-tag-24: 7.2.0][Search sharing support] ·
+<!-- md:version 7.2.0 -->
-:octicons-unlock-24: Feature flag
+<!-- md:feature -->
 
 When search sharing is activated, a :material-share-variant: share button is
 rendered next to the reset button, which allows to deep link to the current
@@ -307,13 +96,12 @@ theme:
 When a user clicks the share button, the URL is automatically copied to the
 clipboard.
 
-  [Search sharing support]: https://github.com/squidfunk/mkdocs-material/releases/tag/7.2.0
-
 ## Usage
 
 ### Search boosting
 
-[:octicons-tag-24: 8.3.0][boost support]
+<!-- md:version 8.3.0 -->
+<!-- md:flag metadata -->
 
 Pages can be boosted in search with the front matter `search.boost` property,
 which will make them rank higher. Add the following lines at the top of a
@@ -327,7 +115,7 @@ Markdown file:
       boost: 2 # (1)!
     ---
 
-    # Document title
+    # Page title
     ...
     ```
 
@@ -342,19 +130,18 @@ Markdown file:
       boost: 0.5
     ---
 
-    # Document title
+    # Page title
     ...
     ```
 
-  [boost support]: https://github.com/squidfunk/mkdocs-material/releases/tag/8.3.0
-
 ### Search exclusion
 
-[:octicons-tag-24: 9.0.0][exclusion support] ·
+<!-- md:version 9.0.0 -->
-:octicons-beaker-24: Experimental
+<!-- md:flag metadata -->
+<!-- md:flag experimental -->
 
 Pages can be excluded from search with the front matter `search.exclude`
-property, removing them from the index. Add the following lines at the top of a 
+property, removing them from the index. Add the following lines at the top of a
 Markdown file:
 
 ``` yaml
@@ -363,12 +150,10 @@ search:
   exclude: true
 ---
 
-# Document title
+# Page title
 ...
 ```
 
-  [exclusion support]: https://github.com/squidfunk/mkdocs-material/releases/tag/9.0.0
-
 #### Excluding sections
 
 When [Attribute Lists] is enabled, specific sections of pages can be excluded
@@ -378,7 +163,7 @@ heading:
 === ":octicons-file-code-16: `docs/page.md`"
 
     ``` markdown
-    # Document title
+    # Page title
 
     ## Section 1
 
@@ -420,7 +205,7 @@ inline- or block-level element:
 === ":octicons-file-code-16: `docs/page.md`"
 
     ``` markdown
-    # Document title
+    # Page title
 
     The content of this block is included
 

docs/setup/setting-up-social-cards.md

@@ -4,8 +4,8 @@ status: new
 
 # Setting up social cards
 
-Material for MkDocs can automatically create beautiful social cards for your 
+Material for MkDocs can automatically create beautiful social cards for your
-documentation, which appear as link previews on social media platforms. You 
+documentation, which appear as link previews on social media platforms. You
 can select from several [pre-designed layouts][default layouts] or create
 [custom layouts] to match your unique style and branding.
 
@@ -36,35 +36,22 @@ Social card of our [formatting] reference
 
 ### Built-in social plugin
 
-[:octicons-tag-24: 8.5.0][Social cards support] ·
+<!-- md:version 8.5.0 -->
-:octicons-cpu-24: Plugin ·
+<!-- md:plugin -->
-:octicons-beaker-24: Experimental
+<!-- md:flag experimental -->
 
-The built-in social plugin automatically generate a custom preview image for 
+The built-in social plugin automatically generate a custom preview image for
-each page. Install all [dependencies for image processing][^1] and add the 
+each page. Install all [dependencies for image processing] and add the
 following lines to `mkdocs.yml`:
 
-  [^1]:
-    The awesome thing about social cards is that they are generated during 
-    build time and directly distributed with your documentation, no external 
-    services involved. While it would technically be simpler to generate 
-    social cards using a web browser and an automation framework like 
-    [Puppeteer], it would add further liabilities to the toolchain, with the 
-    potential to make build pipelines more complex and resource intense.
-
-    For this reason, Material for MkDocs again follows its core principle of 
-    making it as simple and powerful as possible, providing an easy-to-use 
-    framework for building [custom layouts] using Python image processing 
-    libraries.
-
 ``` yaml
 plugins:
   - social
 ```
 
-> Note that [Insiders] contains a ground up rewrite of the social plugin that 
+For a list of all settings, please consult the [plugin documentation].
-> generates images much more efficiently in parallel and allows to build 
+
-> entirely [custom layouts].
+  [plugin documentation]: ../plugins/blog.md
 
 !!! info "The [`site_url`][site_url] setting must be set"
 
@@ -78,481 +65,18 @@ plugins:
     site_url: https://example.com
     ```
 
+  [dependencies for image processing]: ../plugins/requirements/image-processing.md
   [site_url]: https://www.mkdocs.org/user-guide/configuration/#site_url
 
-The following configuration options are available:
-
-[`enabled`](#+social.enabled){ #+social.enabled }
-
-:   :octicons-milestone-24: Default: `true` – This option specifies whether
-    the plugin is enabled when building your project. If you want to speed up
-    local builds, you can use an [environment variable]:
-
-    ``` yaml
-    plugins:
-      - social:
-          enabled: !ENV [CI, false]
-    ```
-
-[`concurrency`](#+social.concurrency){ #+social.concurrency }
-
-:   [:octicons-tag-24: insiders-4.33.0][Insiders] · :octicons-milestone-24: 
-    Default: _number of CPUs_ – How many CPUs the plugin is allowed to use when
-    generating social cards. With more CPUs, the plugin can do more work in the
-    same time, thus complete generation faster. Concurrent processing can be
-    disabled with:
-
-    ``` yaml
-    plugins:
-      - social:
-          concurrency: 1
-    ```
-
-  [Social cards support]: https://github.com/squidfunk/mkdocs-material/releases/tag/8.5.0
-  [built-in plugins]: ../insiders/getting-started.md#built-in-plugins
-  [dependencies for image processing]: dependencies/image-processing.md
-  [Puppeteer]: https://github.com/puppeteer/puppeteer
-  [Insiders]: ../insiders/index.md
-  [environment variable]: https://www.mkdocs.org/user-guide/configuration/#environment-variables
-
-#### Social cards
-
-The following configuration options are available for card generation:
-
-[`cards`](#+social.cards){ #+social.cards }
-
-:   :octicons-milestone-24: Default: `true` – This option specifies whether
-    to generate social card images. If you want to switch the plugin off, e.g.
-    for local builds, you can use an [environment variable]:
-
-    ``` yaml
-    plugins:
-      - social:
-          cards: !ENV [CI, false]
-    ```
-
-[`cards_dir`](#+social.cards_dir){ #+social.cards_dir }
-
-:   :octicons-milestone-24: Default: `assets/images/social` – This option
-    specifies where the generated social cards will be stored. While it's
-    usually not necessary to change this option, change it with:
-
-    ``` yaml
-    plugins:
-      - social:
-          cards_dir: assets/images/social
-    ```
-
-<div class="mdx-deprecated" markdown>
-
-[`cards_color`](#+social.cards_color){ #+social.cards_color } – <small>:material-trash-can: Deprecated, use [`cards_layout_options`][layout options]</small>
-
-:   :octicons-milestone-24: Default: [`theme.palette.primary`][primary color] – 
-    This option specifies the colors for the background `fill` and foreground
-    `text` when generating the social card:
-
-    ``` yaml
-    plugins:
-      - social:
-          cards_color:
-            fill: "#0FF1CE"
-            text: "#FFFFFF"
-    ```
-
-[`cards_font`](#+social.cards_font){ #+social.cards_font } – <small>:material-trash-can: Deprecated, use [`cards_layout_options`][layout options]</small>
-
-:   :octicons-milestone-24: Default: [`theme.font.text`][font] – This option
-    specifies which font to use for rendering the social card, which can be
-    any font hosted on [Google Fonts]:
-
-    ``` yaml
-    plugins:
-      - social:
-          cards_font: Ubuntu
-    ```
-
-</div>
-
-[`cards_layout_dir`](#+social.cards_layout_dir){ #+social.cards_layout_dir }
-
-:   [:octicons-tag-24: insiders-4.33.0][Insiders] · :octicons-milestone-24:
-    Default: _none_ – This option specifies where the social plugin should try
-    to resolve [custom layouts] from, taking precedence over the included
-    layouts:
-
-    ``` yaml
-    plugins:
-      - social:
-          cards_layout_dir: layouts
-    ```
-
-[`cards_layout`](#+social.cards_layout){ #+social.cards_layout } :material-alert-decagram:{ .mdx-pulse title="Added on May 8, 2023" }
-
-:   [:octicons-tag-24: insiders-4.33.0][Insiders] · :octicons-milestone-24:
-    Default: `default` – Layout specification the social card should use. The
-    plugin includes the following layouts which make use of the [color palette]
-    and [font]:
-
-    === "`default`"
-
-        ``` yaml
-        plugins:
-          - social:
-              cards_layout: default
-        ```
-
-        This layout uses the configured [primary color] as a background:
-
-        [![Layout default]][Layout default]
-
-    === "`default/variant`"
-
-        ``` yaml
-        plugins:
-          - social:
-              cards_layout: default/variant
-        ```
-
-        This layout includes the [page icon] as a watermark, if defined:
-
-        [![Layout default variant]][Layout default variant]
-
-    === "`default/accent`"
-
-        ``` yaml
-        plugins:
-          - social:
-              cards_layout: default/accent
-        ```
-
-        This layout uses the configured [accent color] as a background:
-
-        [![Layout default accent]][Layout default accent]
-
-    === "`default/invert`"
-
-        ``` yaml
-        plugins:
-          - social:
-              cards_layout: default/invert
-        ```
-
-        This layout inverts the background and foreground colors:
-
-        [![Layout default invert]][Layout default invert]
-
-    === "`default/only/image`"
-
-        ``` yaml
-        plugins:
-          - social:
-              cards_layout: default/only/image
-              cards_layout_options:
-                background_image: layouts/background.png
-
-        ```
-
-        This layout will only show the given background image and scale to fit:
-
-        [![Layer background image]][Layer background image]
-
-    All [`default`][default layouts] layouts make use of the following
-    [template variables]:
-
-    - :material-page-layout-header: – `config.site_name`
-    - :material-page-layout-body: – `page.meta.title` or `page.title`
-    - :material-page-layout-footer: – `page.meta.description` or `config.site_description`
-    - :material-page-layout-sidebar-right: – `theme.logo` or `theme.icon.logo`
-
-[`cards_layout_options`](#+social.cards_layout_options){ #+social.cards_layout_options }
-
-:   [:octicons-tag-24: 9.1.10][Layout options support] · :octicons-milestone-24:
-    Default: _none_ – This option allows to set [parameters] as provided by
-    the layout specification. For [custom layouts], this key can be used to
-    provide layout-specific options, making layouts entirely configurable.
-
-    ---
-
-    All [`default`][default layouts] layouts expose the following parameters:
-
-    [`background_color`](#+social.cards_layout_options.background_color){ #+social.cards_layout_options.background_color }
-
-    :   Set a background color, which can be a [CSS color keyword], or a 3, 4, 6
-        or 8 letter HEX color code. Alpha channels are supported as well:
-
-        ``` yaml
-        plugins:
-          - social:
-              cards_layout_options:
-                background_color: "#0FF1CE"
-        ```
-
-    [`background_image`](#+social.cards_layout_options.background_image){ #+social.cards_layout_options.background_image }
-
-    :   [:octicons-tag-24: insiders-4.33.0][Insiders] – Set a background image. 
-        If a `background_color` is set, like for the
-        [`default`][default layouts] layouts, the image is tinted (overlayed)
-        with the color. Thus, the background color must be (partially)
-        transparent for the image to become visible:
-
-        ``` yaml
-        plugins:
-          - social:
-              cards_layout_options:
-                background_color: "#00000000"
-                background_image: layouts/background.png
-        ```
-
-        The path of the image must be defined relative to the project root.
-
-    [`color`](#+social.cards_layout_options.color){ #+social.cards_layout_options.color }
-
-    :   Set a foreground color, which can be a [CSS color keyword], or a 3, 4, 6
-        or 8 letter HEX color code. The color is primarily used to tint text and
-        icons:
-
-        ``` yaml
-        plugins:
-          - social:
-              cards_layout_options:
-                color: "#0FF1CE"
-        ```
-
-    [`font_family`](#+social.cards_layout_options.font_family){ #+social.cards_layout_options.font_family }
-
-    :   Set a font family. This overrides the [font] that is set as part of the
-        theme configuration. The [built-in social plugin] will automatically
-        download the font from [Google Fonts]:
-
-        ``` yaml
-        plugins:
-          - social:
-              cards_layout_options:
-                font_family: Ubuntu
-        ```
-
-    [`title`](#+social.cards_layout_options.title){ #+social.cards_layout_options.title }
-
-    :   [:octicons-tag-24: insiders-4.40.0][Insiders] – Set the social card
-        title, which takes precedence over `page.title` and `page.meta.title`:
-
-        ``` yaml
-        plugins:
-          - social:
-              cards_layout_options:
-                title: Social card title
-        ```
-
-    [`description`](#+social.cards_layout_options.description){ #+social.cards_layout_options.description }
-
-    :   [:octicons-tag-24: insiders-4.40.0][Insiders] – Set the social card
-        description, which takes precedence over `site_description` and
-        `page.meta.description`:
-
-        ``` yaml
-        plugins:
-          - social:
-              cards_layout_options:
-                description: Social card description
-        ```
-
-    [`logo`](#+social.cards_layout_options.logo){ #+social.cards_layout_options.logo }
-
-    :   [:octicons-tag-24: insiders-4.40.0][Insiders] – Set the logo used as
-        part of the social card, overriding the `theme.logo` or
-        `theme.icon.logo` settings which are used as defaults:
-
-        ``` yaml
-        plugins:
-          - social:
-              cards_layout_options:
-                logo: layouts/logo.png
-        ```
-
-        The path of the image must be defined relative to the project root.
-
-[`cards_include`](#+privacy.cards_include){ #+privacy.cards_include }
-
-:   [:octicons-tag-24: insiders-4.35.0][Insiders] · :octicons-milestone-24:
-    Default: _none_ – This option allows to only generate social cards for
-    certain subsections of your documentation, e.g. to generate different
-    cards for different subfolders with multiple instances of the plugin:
-
-    ``` yaml
-    plugins:
-      - social:
-          cards_include:
-            - blog/*
-    ```
-
-[`cards_exclude`](#+privacy.cards_exclude){ #+privacy.cards_exclude }
-
-:   :octicons-milestone-24: Default: _none_ – This option allows to exclude
-    certain subsections of your documentation from generating social cards:
-
-    ``` yaml
-    plugins:
-      - social:
-          cards_exclude:
-            - changelog/*.md
-    ```
-
-  [color palette]: ./changing-the-colors.md#color-palette
-  [primary color]: ./changing-the-colors.md#primary-color
-  [accent color]: ./changing-the-colors.md#accent-color
-  [font]: ./changing-the-fonts.md#regular-font
-  [Google Fonts]: https://fonts.google.com/
-  [layout options]: #+social.cards_layout_options
-  [page icon]: ../reference/index.md#setting-the-page-icon
-  [Layout default]: ../assets/screenshots/social-cards.png
-  [Layout default variant]: ../assets/screenshots/social-cards-variant.png
-  [Layout default accent]: ../assets/screenshots/social-cards-accent.png
-  [Layout default invert]: ../assets/screenshots/social-cards-invert.png
-  [template variables]: https://www.mkdocs.org/dev-guide/themes/#template-variables
-  [parameters]: #parameters
-  [default layouts]: #+social.cards_layout
-  [CSS color keyword]: https://developer.mozilla.org/en-US/docs/Web/CSS/color_value#color_keywords
-  [Layout options support]: https://github.com/squidfunk/mkdocs-material/releases/tag/9.1.10
-
-#### Debugging
-
-The following configuration options are available for debugging:
-
-[`debug`](#+social.debug){ #+social.debug }
-
-:   [:octicons-tag-24: insiders-4.33.0][Insiders] · :octicons-milestone-24:
-    Default: `false` – This option enables a special debug mode, which renders
-    each layer with an outline and its `x` and `y` offset in order to understand
-    how the layout is composed, and optionally renders a grid for easier
-    alignment:
-
-    ``` yaml
-    plugins:
-      - social:
-          debug: true
-    ```
-
-    === "With debug mode"
-
-        [![Debug mode enabled]][Debug mode enabled]
-
-    === "Without"
-
-        [![Debug mode disabled]][Debug mode disabled]
-
-    [Debug mode enabled]: ../assets/screenshots/social-cards-debug.png
-    [Debug mode disabled]: ../assets/screenshots/social-cards-variant.png
-
-[`debug_on_build`](#+social.debug_on_build){ #+social.debug_on_build }
-
-:   [:octicons-tag-24: insiders-4.34.1][Insiders] · :octicons-milestone-24:
-    Default: `false` – Whether debug mode should be automatically disabled
-    [when building your site] with `mkdocs build`. It can be changed with:
-
-    ``` yaml
-    plugins:
-      - social:
-          debug_on_build: true
-    ```
-
-    This setting is just intended to be a safety net, so that when building
-    your site social cards definitely won't contain the dot grid or layer
-    outlines by accident.
-
-[`debug_grid`](#+social.debug_grid){ #+social.debug_grid }
-
-:   [:octicons-tag-24: insiders-4.33.0][Insiders] · :octicons-milestone-24:
-    Default: `true` – This option enables the rendering of a dot grid when
-    [`debug`][debug] is enabled (see screenshot above). The grid can be switched
-    off with:
-
-    ``` yaml
-    plugins:
-      - social:
-          debug_grid: false
-    ```
-
-[`debug_grid_step`](#+social.debug_grid_step){ #+social.debug_grid_step }
-
-:   [:octicons-tag-24: insiders-4.33.0][Insiders] · :octicons-milestone-24:
-    Default: `32` – This option specifies the step size of the grid in pixels,
-    if enabled, which can be used to align elements. It can be changed with:
-
-    ``` yaml
-    plugins:
-      - social:
-          debug_grid_step: 64
-    ```
-
-[`debug_color`](#+social.debug_color){ #+social.debug_color }
-
-:   [:octicons-tag-24: insiders-4.33.0][Insiders] · :octicons-milestone-24:
-    Default: `grey` – This option sets the color of the layer outlines and
-    the grid which are rendered when [`debug`][debug] is enabled. It can be
-    changed with:
-
-    ``` yaml
-    plugins:
-      - social:
-          debug_color: yellow
-    ```
-
-  [debug]: #+social.debug
-  [when building your site]: ../creating-your-site.md#building-your-site
-
-#### Caching
-
-The [built-in social plugin] implements an intelligent caching mechanism,
-ensuring that social cards are only re-generated when they're not contained in
-the cache or their contents change. If any of the variables used in a layout 
-changes, the plugin will detect it and re-generate the card.
-
-The following configuration options are available for caching:
-
-[`cache`](#+social.cache){ #+social.cache }
-
-:   [:octicons-tag-24: insiders-4.33.0][Insiders] · :octicons-milestone-24:
-    Default: `true` – Whether the plugin queries its cache for an existing
-    artifact before starting a generation job. It's normally not necessary to
-    change this setting, except for when debugging the plugin itself. Caching
-    can be disabled with:
-
-    ``` yaml
-    plugins:
-      - social:
-          cache: false
-    ```
-
-[`cache_dir`](#+social.cache_dir){ #+social.cache_dir }
-
-:   :octicons-milestone-24: Default: `.cache/plugins/social` – This option
-    specifies the file system location of the plugin's cache. It's normally not
-    necessary to change this setting, except for when debugging the plugin
-    itself. The cache directory can be changed with:
-
-    ``` yaml
-    plugins:
-      - social:
-          cache_dir: .cache/plugins/social
-    ```
-
-    By default, all built-in plugins that implement caching will create a
-    `.cache` directory in the same folder your `mkdocs.yml` resides, and create
-    subfolders to not interfere with each other. If you use multiple instances
-    of this plugin, it could be necessary to change this setting.
-
-  [built-in social plugin]: #built-in-social-plugin
-  [publishing guide]: ../publishing-your-site.md#with-github-actions
-
 ## Usage
 
 If you want to adjust the title or set a custom description for the social card,
 you can set the front matter [`title`][Changing the title] and
-[`description`][Changing the description] properties, which take precedence over 
+[`description`][Changing the description] properties, which take precedence over
 the defaults, or use:
 
-- [`cards_layout_options.title`](#+social.cards_layout_options.title)
+- [`cards_layout_options.title`](../plugins/social.md#option.title)
-- [`cards_layout_options.description`](#+social.cards_layout_options.description)
+- [`cards_layout_options.description`](../plugins/social.md#option.description)
 
   [Changing the title]: ../reference/index.md#setting-the-page-title
   [Changing the description]: ../reference/index.md#setting-the-page-description
@@ -602,12 +126,14 @@ comes with CJK characters, e.g. one from the `Noto Sans` font family:
 
 ### Changing the layout
 
-[:octicons-tag-24: insiders-4.37.0][Insiders] ·
+<!-- md:version insiders-4.37.0 -->
-:octicons-beaker-24: Experimental
+<!-- md:flag metadata -->
+<!-- md:flag experimental -->
 
 If you want to use a different layout for a single page (e.g. your landing
 page), you can use the `social` front matter property together with the
-[`cards_layout`](#+social.cards_layout) key, exactly as in `mkdocs.yml`:
+[`cards_layout`](../plugins/social.md#meta.social.cards_layout) key, exactly as
+in `mkdocs.yml`:
 
 ``` yaml
 ---
@@ -615,7 +141,7 @@ social:
   cards_layout: custom
 ---
 
-# Headline
+# Page title
 ...
 ```
 
@@ -623,17 +149,18 @@ You can apply those changes for entire subtrees of your documentation, e.g.,
 to generate different social cards for your blog and API reference, by using
 the [built-in meta plugin].
 
-  [built-in meta plugin]: ../reference/index.md#built-in-meta-plugin
+  [built-in meta plugin]: ../plugins/meta.md
 
 ### Parametrizing the layout
 
-[:octicons-tag-24: insiders-4.37.0][Insiders] ·
+<!-- md:version insiders-4.37.0 -->
-:octicons-beaker-24: Experimental
+<!-- md:flag metadata -->
+<!-- md:flag experimental -->
 
 Besides changing the entire layout, you can override all options that a layout
 exposes. This means you can parametrize social cards with custom front matter
 properties, such as `tags`, `date`, `author` or anything you can think of.
-Simply define [`cards_layout_options`](#+social.cards_layout_options):
+Simply define [`cards_layout_options`](../plugins/social.md#meta.social.cards_layout_options):
 
 ``` yaml
 ---
@@ -643,7 +170,7 @@ social:
     background_image: null # Remove background image
 ---
 
-# Headline
+# Page title
 ...
 ```
 
@@ -653,8 +180,9 @@ the [built-in meta plugin].
 
 ### Disabling social cards
 
-[:octicons-tag-24: insiders-4.37.0][Insiders] ·
+<!-- md:version insiders-4.37.0 -->
-:octicons-beaker-24: Experimental
+<!-- md:flag metadata -->
+<!-- md:flag experimental -->
 
 If you wish to disable social cards for a page, simply add the following to the
 front matter of the Markdown document:
@@ -665,15 +193,15 @@ social:
   cards: false
 ---
 
-# Headline
+# Page title
 ...
 ```
 
 ## Customization
 
-[:octicons-heart-fill-24:{ .mdx-heart } Sponsors only][Insiders]{ .mdx-insiders } ·
+<!-- md:sponsors -->
-[:octicons-tag-24: insiders-4.33.0][Insiders] ·
+<!-- md:version insiders-4.33.0 -->
-:octicons-beaker-24: Experimental
+<!-- md:flag experimental -->
 
 [Insiders] ships a ground up rewrite of the [built-in social plugin] and
 introduces a brand new layout system based on a combination of YAML and
@@ -755,6 +283,9 @@ haven't defined any layers, the cards are transparent.
 
 The following sections explain how to create custom layouts.
 
+  [Insiders]: ../insiders/index.md
+  [built-in social plugin]: ../plugins/social.md
+  [Google Fonts]: https://fonts.google.com/
   [Jinja templates]: https://jinja.palletsprojects.com/en/3.1.x/
   [study the pre-designed layouts]: https://github.com/squidfunk/mkdocs-material-insiders/tree/master/src/plugins/social/layouts
 
@@ -785,8 +316,8 @@ useful for alignment and composition.
 
 #### Origin
 
-[:octicons-tag-24: insiders-4.35.0][Insiders] ·
+<!-- md:version insiders-4.35.0 -->
-:octicons-beaker-24: Experimental
+<!-- md:flag experimental -->
 
 The `origin` for the `x` and `y` values can be changed, so that the layer is
 aligned to one of the edges or corners of the layout, e.g., to the bottom right
@@ -934,7 +465,7 @@ automatically scaled down to fit the layer:
 
     ![Layer typography shrink]
 
-While truncating with an ellipsis is the default, auto-shrinking can be enabled 
+While truncating with an ellipsis is the default, auto-shrinking can be enabled
 by setting `overflow` to `shrink`:
 
 ``` yaml hl_lines="7"

docs/setup/setting-up-tags.md

@@ -11,8 +11,8 @@ can help to discover relevant information faster.
 
 ### Built-in tags plugin
 
-[:octicons-tag-24: 8.2.0][Tags support] ·
+<!-- md:version 8.2.0 -->
-:octicons-cpu-24: Plugin
+<!-- md:plugin -->
 
 The built-in tags plugin adds the ability to categorize any page with tags
 as part of the front matter of the page. In order to add support for tags, add
@@ -23,206 +23,14 @@ plugins:
   - tags
 ```
 
-The following configuration options are available:
+For a list of all settings, please consult the [plugin documentation].
 
-[`enabled`](#+tags.enabled){ #+tags.enabled }
+  [plugin documentation]: ../plugins/tags.md
-
-:   :octicons-milestone-24: Default: `true` – This option specifies whether
-    the plugin is enabled when building your project. If you want to speed up
-    local builds, you can use an [environment variable]:
-
-    ``` yaml
-    plugins:
-      - tags:
-          enabled: !ENV [CI, 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
-    become clickable, pointing to the corresponding section in the tags index:
-
-    ``` yaml
-    plugins:
-      - tags:
-          tags_file: tags.md
-    ```
-
-    The page holding the tags index can be linked anywhere in the `nav` section
-    of `mkdocs.yml`. Note, however, that this options is not required – only use
-    it if you want a tags index page.
-
-[`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 specifies additional pages, i.e. to render
-    subsets of the [tags index], in order to provide scoped tags indexes for 
-    specific sections:
-
-    ``` yaml
-    plugins:
-      - tags:
-          tags_extra_files:
-            compatibility.md:
-              - compat # (1)!
-            web.md:
-              - html
-              - js
-              - css
-    ```
-
-    1.  Each page can be assigned a list of [tag identifiers], which must be
-        defined as part of `extra.tags` in `mkdocs.yml`:
-
-        ``` yaml
-        extra:
-          tags:
-            Compatibility: compat
-            HTML5: html
-            JavaScript: js
-            CSS: css
-        ```
-
-        In this example, all pages with the tag `Compatibility` will be included 
-        in the additional tags index on `compatibility.md`, all pages defining
-        at least one of the tags `HTML5`, `JavaScript` or `CSS` will be included
-        in the additional tags index on `web.md`.
-
-    Note that the values listed under each tags extra file must be alphanumeric
-    [tag identifiers], not tags themselves. 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_compare`](#+tags.tags_compare){ #+tags.tags_compare }
-
-:   [:octicons-tag-24: insiders-4.26.2][Insiders] · :octicons-milestone-24:
-    Default: `None` – This option specifies which function to use when
-    comparing tag values for sorting. If you wish to compare tags irregardless
-    of casing, use:
-
-    ``` yaml
-    plugins:
-      - tags:
-          tags_compare: !!python/name:material.plugins.tags.casefold
-    ```
-
-    You can also define your own comparison function which must return a tag
-    value (as a string) that is used for sorting, and reference it accordingly.
-
-[`tags_compare_reverse`](#+tags.tags_compare_reverse){ #+tags.tags_compare_reverse }
-
-:   [:octicons-tag-24: insiders-4.26.2][Insiders] · :octicons-milestone-24:
-    Default: `false` – This option specifies whether tags are sorted in reverse
-    order. It is mainly provided for completeness. To change direction, use:
-
-    ``` yaml
-    plugins:
-      - tags:
-          tags_compare_reverse: true
-    ```
-
-[`tags_pages_compare`](#+tags.tags_pages_compare){ #+tags.tags_pages_compare }
-
-:   [:octicons-tag-24: insiders-4.39.0][Insiders] · :octicons-milestone-24:
-    Default: `None` – This option specifies which function to use when
-    comparing pages for sorting. If you wish to sort pages, use:
-
-    === "Sort by page title"
-
-        ``` yaml
-        plugins:
-          - tags:
-              tags_pages_compare: !!python/name:material.plugins.tags.page_title
-        ```
-
-    === "Sort by page URL"
-
-        ``` yaml
-        plugins:
-          - tags:
-              tags_pages_compare: !!python/name:material.plugins.tags.page_url
-        ```
-
-    You can also define your own comparison function which must return a page
-    value (as a string) that is used for sorting, and reference it accordingly.
-
-[`tags_pages_compare_reverse`](#+tags.tags_pages_compare_reverse){ #+tags.tags_pages_compare_reverse }
-
-:   [:octicons-tag-24: insiders-4.39.0][Insiders] · :octicons-milestone-24:
-    Default: `false` – This option specifies whether pages are sorted in reverse
-    order. It is mainly provided for completeness. To change direction, use:
-
-    ``` yaml
-    plugins:
-      - tags:
-          tags_pages_compare_reverse: true
-    ```
-
-[`tags_allowed`](#+tags.tags_allowed){ #+tags.tags_allowed }
-
-:   [: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
-  [environment variable]: https://www.mkdocs.org/user-guide/configuration/#environment-variables
-  [Insiders]: ../insiders/index.md
-  [tag identifiers]: #tag-icons-and-identifiers
-  [Python Markdown Extensions]: https://facelessuser.github.io/pymdown-extensions/extras/slugs/
 
 ### Tag icons and identifiers
 
-[:octicons-tag-24: 8.5.0][Tag icons support] ·
+<!-- md:version 8.5.0 -->
-:octicons-beaker-24: Experimental
+<!-- md:flag experimental -->
 
 Each tag can be associated with an icon, which is then rendered inside the tag.
 Before assigning icons to tags, associate each tag with a unique identifier,
@@ -248,7 +56,7 @@ extra:
     associated will use the default tag icon which is :material-pound:
 
 Next, each identifier can be associated with an icon, even a [custom icon], by
-adding the following lines to `mkdocs.yml` under the `theme.icon` configuration 
+adding the following lines to `mkdocs.yml` under the `theme.icon` configuration
 setting:
 
 === "Tag icon"
@@ -296,7 +104,6 @@ setting:
         CSS: css
     ```
 
-  [Tag icons support]: https://github.com/squidfunk/mkdocs-material/releases/tag/8.5.0
   [custom icon]: changing-the-logo-and-icons.md#additional-icons
   [icon search]: ../reference/icons-emojis.md#search
 
@@ -305,7 +112,7 @@ setting:
 ### Adding tags
 
 When the [built-in tags plugin] is enabled, tags can be added for a document
-with the front matter `tags` property. Add the following lines at the top of a 
+with the front matter `tags` property. Add the following lines at the top of a
 Markdown file:
 
 ``` sh
@@ -378,6 +185,6 @@ hide:
   - tags
 ---
 
-# Document title
+# Page title
 ...
 ```

docs/setup/setting-up-the-footer.md

@@ -1,7 +1,7 @@
 # Setting up the footer
 
 The footer of your project documentation is a great place to add links to
-websites or platforms you or your company are using as additional marketing 
+websites or platforms you or your company are using as additional marketing
 channels, e.g. :fontawesome-brands-mastodon:{ style="color: #5A4CE0" } or
 :fontawesome-brands-youtube:{ style="color: #EE0F0F" }, which you can easily
 configure via `mkdocs.yml`.
@@ -10,8 +10,8 @@ configure via `mkdocs.yml`.
 
 ### Navigation
 
-[:octicons-tag-24: 9.0.0][Navigation footer support] ·
+<!-- md:version 9.0.0 -->
-:octicons-unlock-24: Feature flag
+<!-- md:feature -->
 
 The footer can include links to the previous and next page of the current page.
 If you wish to enable this behavior, add the following lines to `mkdocs.yml`:
@@ -22,15 +22,13 @@ theme:
     - navigation.footer
 ```
 
-  [Navigation footer support]: https://github.com/squidfunk/mkdocs-material/releases/tag/9.0.0
-
 ### Social links
 
-[:octicons-tag-24: 1.0.0][Social links support] ·
+<!-- md:version 1.0.0 -->
-:octicons-milestone-24: Default: _none_
+<!-- md:default none -->
 
-Social links are rendered next to the copyright notice as part of the 
+Social links are rendered next to the copyright notice as part of the
-footer of your project documentation. Add a list of social links in `mkdocs.yml` 
+footer of your project documentation. Add a list of social links in `mkdocs.yml`
 with:
 
 ``` yaml
@@ -53,9 +51,9 @@ extra:
 
 The following properties are available for each link:
 
-[`icon`](#+social.icon){ #+social.icon }
+<!-- md:option social.icon -->
 
-:   :octicons-milestone-24: Default: _none_ · :octicons-alert-24: __Required__ –
+:   <!-- md:default none --> <!-- md:flag required -->
     This property must contain a valid path to any icon bundled with the theme,
     or the build will not succeed. Some popular choices:
 
@@ -72,10 +70,10 @@ The following properties are available for each link:
     * :fontawesome-brands-slack: – `fontawesome/brands/slack`
     * :fontawesome-brands-discord: – `fontawesome/brands/discord`
 
-[`link`](#+social.link){ #+social.link }
+<!-- md:option social.link -->
 
-:   :octicons-milestone-24: Default: _none_ · :octicons-alert-24: __Required__ –
+:   <!-- md:default none --> <!-- md:flag required -->
-    This property must be set to a relative or absolute URL including the URI 
+    This property must be set to a relative or absolute URL including the URI
     scheme. All URI schemes are supported, including `mailto` and `bitcoin`:
 
     === ":fontawesome-brands-mastodon: Mastodon"
@@ -96,10 +94,10 @@ The following properties are available for each link:
               link: mailto:<email-address>
         ```
 
-[`name`](#+social.name){ #+social.name }
+<!-- md:option social.name -->
 
-:   :octicons-milestone-24: Default: _domain name from_ `link`_, if available_ –
+:   <!-- md:default _domain name from_ `link`_, if available_ -->
-    This property is used as the link's `title` attribute and can be set to a 
+    This property is used as the link's `title` attribute and can be set to a
     discernable name to improve accessibility:
 
     ``` yaml
@@ -111,13 +109,12 @@ The following properties are available for each link:
     ```
 
   [icon search]: ../reference/icons-emojis.md#search
-  [Social links support]: https://github.com/squidfunk/mkdocs-material/releases/tag/1.0.0
   [rel=me]: https://docs.joinmastodon.org/user/profile/#verification
 
 ### Copyright notice
 
-[:octicons-tag-24: 0.1.0][Copyright notice support] ·
+<!-- md:version 0.1.0 -->
-:octicons-milestone-24: Default: _none_
+<!-- md:default none -->
 
 A custom copyright banner can be rendered as part of the footer, which is
 displayed next to the social links. It can be defined as part of `mkdocs.yml`:
@@ -126,12 +123,10 @@ displayed next to the social links. It can be defined as part of `mkdocs.yml`:
 copyright: Copyright &copy; 2016 - 2020 Martin Donath
 ```
 
-  [Copyright notice support]: https://github.com/squidfunk/mkdocs-material/releases/tag/0.1.0
-
 ### Generator notice
 
-[:octicons-tag-24: 7.3.0][Generator notice support] ·
+<!-- md:version 7.3.0 -->
-:octicons-milestone-24: Default: `true`
+<!-- md:default `true` -->
 
 The footer displays a _Made with Material for MkDocs_ notice to denote how
 the site was generated. The notice can be removed with the following option
@@ -155,7 +150,6 @@ extra:
     Thus, if you remove this notice, please consider [sponsoring][Insiders] the
     project. __Thank you__ :octicons-heart-fill-24:{ .mdx-heart .mdx-insiders }
 
-  [Generator notice support]: https://github.com/squidfunk/mkdocs-material/releases/tag/7.3.0
   [Insiders]: ../insiders/index.md
 
 ## Usage
@@ -163,7 +157,7 @@ extra:
 ### Hiding prev/next links
 
 The footer navigation showing links to the previous and next page can be hidden
-with the front matter `hide` property. Add the following lines at the top of a 
+with the front matter `hide` property. Add the following lines at the top of a
 Markdown file:
 
 ``` yaml
@@ -172,7 +166,7 @@ hide:
   - footer
 ---
 
-# Document title
+# Page title
 ...
 ```
 
@@ -180,14 +174,13 @@ hide:
 
 ### Custom copyright
 
-[:octicons-tag-24: 8.0.0][Custom copyright support] ·
+<!-- md:version 8.0.0 -->
-:octicons-file-symlink-file-24: Customization
+<!-- md:flag customization -->
 
 In order to customize and override the [copyright notice], [extend the theme]
 and [override the `copyright.html` partial][overriding partials], which normally
 includes the `copyright` property set in `mkdocs.yml`.
 
-  [Custom copyright support]: https://github.com/squidfunk/mkdocs-material/releases/tag/8.0.0
   [copyright notice]: #copyright-notice
   [generator notice]: #generator-notice
   [extend the theme]: ../customization.md#extending-the-theme

docs/setup/setting-up-the-header.md

@@ -1,6 +1,6 @@
 # Setting up the header
 
-Material for MkDocs' header can be customized to show an announcement bar that 
+Material for MkDocs' header can be customized to show an announcement bar that
 disappears upon scrolling, and provides some options for further configuration.
 It also includes the [search bar] and a place to display your project's
 [git repository], as explained in those dedicated guides.
@@ -12,8 +12,8 @@ It also includes the [search bar] and a place to display your project's
 
 ### Automatic hiding
 
-[:octicons-tag-24: 6.2.0][Automatic hiding support] ·
+<!-- md:version 6.2.0 -->
-:octicons-unlock-24: Feature flag
+<!-- md:feature -->
 
 When autohiding is enabled, the header is automatically hidden when the
 user scrolls past a certain threshold, leaving more space for content. Add the
@@ -25,12 +25,10 @@ theme:
     - header.autohide
 ```
 
-  [Automatic hiding support]: https://github.com/squidfunk/mkdocs-material/releases/tag/6.2.0
-
 ### Announcement bar
 
-[:octicons-tag-24: 5.0.0][Announcement bar support] ·
+<!-- md:version 5.0.0 -->
-:octicons-file-symlink-file-24: Customization
+<!-- md:flag customization -->
 
 Material for MkDocs includes an announcement bar, which is the perfect place to
 display project news or other important information to the user. When the user
@@ -46,15 +44,14 @@ block][overriding blocks], which is empty by default:
 {% endblock %}
 ```
 
-  [Announcement bar support]: https://github.com/squidfunk/mkdocs-material/releases/tag/5.0.0
   [extend the theme]: ../customization.md#extending-the-theme
   [overriding blocks]: ../customization.md#overriding-blocks
 
 #### Mark as read
 
-[:octicons-tag-24: 8.4.0][dismiss support] ·
+<!-- md:version 8.4.0 -->
-:octicons-unlock-24: Feature flag ·
+<!-- md:feature -->
-:octicons-beaker-24: Experimental
+<!-- md:flag experimental -->
 
 In order to render temporary announcements that can be marked as read by the
 user, a button to dismiss the current announcement can be included. Add the
@@ -72,5 +69,4 @@ automatically.
 
 [Scroll to the top of this page][top] to see it in action.
 
-  [dismiss support]: https://github.com/squidfunk/mkdocs-material/releases/tag/8.4.0
   [top]: #

docs/setup/setting-up-versioning.md

@@ -11,8 +11,8 @@ documentation remain untouched.
 
 ### Versioning
 
-[:octicons-tag-24: 7.0.0][Versioning support] ·
+<!-- md:version 7.0.0 -->
-[:octicons-package-24: Utility][mike]
+<!-- md:utility [mike] -->
 
 [mike] makes it easy to deploy multiple versions of your project documentation.
 It integrates natively with Material for MkDocs and can be enabled via
@@ -51,15 +51,14 @@ Check out the versioning example to see it in action –
     to particularly notable versions. This makes it easy to make permalinks to
     whatever version of the documentation you want to direct people to.
 
-  [Versioning support]: https://github.com/squidfunk/mkdocs-material/releases/tag/7.0.0
   [Version selector preview]: ../assets/screenshots/versioning.png
   [version example]: https://squidfunk.github.io/mkdocs-material-example-versioning/
   [Why use mike?]: https://github.com/jimporter/mike#why-use-mike
 
 ### Version warning
 
-[:octicons-tag-24: 8.0.0][Version warning support] ·
+<!-- md:version 8.0.0 -->
-:octicons-file-symlink-file-24: Customization
+<!-- md:flag customization -->
 
 If you're using versioning, you might want to display a warning when the user
 visits any other version than the latest version. Using [theme extension],
@@ -76,7 +75,7 @@ you can [override the `outdated` block][overriding blocks]:
 {% endblock %}
 ```
 
-1.  Given this value for the `href` attribute, the link will always redirect to 
+1.  Given this value for the `href` attribute, the link will always redirect to
     the root of your site, which will then redirect to the latest version. This
     ensures that older versions of your site do not depend on a specific alias,
     e.g. `latest`, to allow for changing the alias later on without breaking
@@ -113,7 +112,6 @@ extra:
 Make sure one alias matches the [default version], as this is where users are
 redirected to.
 
-  [Version warning support]: https://github.com/squidfunk/mkdocs-material/releases/tag/8.0.0
   [theme extension]: ../customization.md#extending-the-theme
   [overriding blocks]: ../customization.md#overriding-blocks
   [Version warning preview]: ../assets/screenshots/version-warning.png
@@ -121,7 +119,7 @@ redirected to.
 
 ## Usage
 
-While this section outlines the basic workflow for publishing new versions, 
+While this section outlines the basic workflow for publishing new versions,
 it's best to check out [mike's documentation][mike] to make yourself familiar
 with its mechanics.
 

includes/mkdocs.md

@@ -0,0 +1,11 @@
+  [mkdocs]: https://www.mkdocs.org
+  [mkdocs.dotfiles]: https://www.mkdocs.org/dev-guide/themes/#dot-files
+  [mkdocs.metadata]: https://www.mkdocs.org/user-guide/writing-your-docs/#yaml-style-meta-data
+  [mkdocs.env]: https://www.mkdocs.org/user-guide/configuration/#environment-variables
+  [mkdocs.docs_dir]: https://www.mkdocs.org/user-guide/configuration/#docs_dir
+  [mkdocs.site_dir]: https://www.mkdocs.org/user-guide/configuration/#site_dir
+  [mkdocs.site_description]: https://www.mkdocs.org/user-guide/configuration/#site_description
+  [mkdocs.nav]: https://www.mkdocs.org/user-guide/configuration/#nav
+  [mkdocs.plugins]: https://www.mkdocs.org/user-guide/configuration/#plugins
+  [mkdocs.strict]: https://www.mkdocs.org/user-guide/configuration/#strict
+  [mkdocs.use_directory_urls]: https://www.mkdocs.org/user-guide/configuration/#use_directory_urls

material/.overrides/assets/stylesheets/custom.024fa163.min.css.map

@@ -0,0 +1 @@
+{"version":3,"sources":["src/.overrides/assets/stylesheets/custom/_typeset.scss","../../../../src/.overrides/assets/stylesheets/custom.scss","src/assets/stylesheets/utilities/_break.scss","src/.overrides/assets/stylesheets/custom/layout/_banner.scss","src/.overrides/assets/stylesheets/custom/layout/_hero.scss","src/.overrides/assets/stylesheets/custom/layout/_iconsearch.scss","src/.overrides/assets/stylesheets/custom/layout/_sponsorship.scss"],"names":[],"mappings":"AA2BA,iBACE,cAIE,kBC7BF,CDgCA,QAEE,qBC/BF,CACF,CD0CE,qBACE,aCxCJ,CD6CE,sBACE,aC3CJ,CD+CE,uBACE,UC7CJ,CDgDI,8BAGE,QAAA,CACA,sBAAA,CAHA,iBAAA,CACA,UC5CN,CDkDI,8BAOE,WAAA,CAFA,WAAA,CAFA,MAAA,CAGA,eAAA,CALA,iBAAA,CACA,KAAA,CAEA,UC7CN,CDqDE,uBACE,2BCnDJ,CDuDE,0BACE,aCrDJ,CD2DE,uBACE,eCzDJ,CD4DI,8BACE,4BAAA,CACA,4BAAA,CACA,2CC1DN,CD6DM,uCACE,2BC3DR,CDgEI,uCAGE,4BC7DN,CD0DI,uCAGE,6BC7DN,CD0DI,uCAIE,+BC9DN,CD0DI,uCAIE,gCC9DN,CD0DI,6BAEE,iDAAA,CADA,aC3DN,CDiEM,wCACE,mBC/DR,CDoEI,uCAEE,6BChEN,CD8DI,uCAEE,4BChEN,CD8DI,uCAGE,gCCjEN,CD8DI,uCAGE,+BCjEN,CD8DI,6BAIE,iEAAA,CAHA,mBC/DN,CDyEE,+BACE,cAAA,CACA,uBCvEJ,CD0EI,0EACE,WCxEN,CD4EI,oCAGE,2CAAA,CADA,gCAAA,CADA,aCxEN,CDkFI,wDAEE,cAAA,CAAA,cChFN,CCqII,wCFvDA,wDAMI,oBAAA,CAAA,eC/EN,CACF,CDmFI,4BACE,8BAAA,CAAA,kBCjFN,CDsFE,uBACE,eCpFJ,CDuFI,0BACE,eCrFN,CDwFM,6BACE,iBCtFR,CD2FI,6BACE,YAAA,CACA,SCzFN,CD6FI,gCACE,YAAA,CACA,MAAA,CACA,qBC3FN,CD8FM,qCAEE,oBAAA,CADA,mBAAA,CAEA,6BC5FR,CDgGM,kDACE,aC9FR,CDkGM,qCACE,WChGR,CDsGE,wBAEE,sBAAA,CADA,iBCnGJ,CDuGI,iDACE,0BCrGN,CDyGI,+BAEE,eAAA,CADA,iBAAA,CAGA,2BAAA,CADA,uCCtGN,CD6GQ,wDACE,SC3GV,CD+GQ,wDACE,0BC7GV,CDiHQ,wDACE,SC/GV,CDqHI,+BACE,yCACE,CAGF,oDAAA,CADA,mBCpHN,CDwHM,mCACE,aCtHR,CD2HI,+BAKE,kDAAA,CADA,gCAAA,CAFA,aAAA,CAIA,SAAA,CAHA,mBAAA,CAFA,iBAAA,CAMA,mBCzHN,CD8HM,8DACE,2BC5HR,CD2HM,8DACE,2BCzHR,CDwHM,8DACE,2BCtHR,CDqHM,8DACE,uBCnHR,CDkHM,8DACE,0BChHR,CD+GM,6DACE,0BC7GR,CD4GM,8DACE,0BC1GR,CEtJA,WACE,wCFyJF,CEtJE,kBAEE,kBFwJJ,CErJE,+BAJE,+BF4JJ,CErJI,sCAEE,kBFsJN,CEpJM,wDACE,0CAAA,CACA,eFsJR,CEjJE,oBAME,kBAAA,CACA,0CAAA,CANA,oBAAA,CAEA,aAAA,CACA,cAAA,CAIA,mBAAA,CAHA,qBAAA,CAHA,YFyJJ,CEjJI,wBACE,aAAA,CACA,eFmJN,CGtLA,eAEE,uYACE,CAFF,gBH0LF,CG/KE,4CACE,yYHiLJ,CGrKA,UAEE,gCAAA,CADA,cHyKF,CGrKE,aAEE,kBAAA,CACA,eAAA,CAFA,kBHyKJ,CCfI,wCE3JF,aAOI,gBHuKJ,CACF,CGnKE,mBACE,mBHqKJ,CC1CI,mCE7IJ,UAwBI,mBAAA,CADA,YHqKF,CGjKE,mBAEE,iBAAA,CADA,eAAA,CAEA,mBHmKJ,CG/JE,iBACE,OAAA,CAEA,0BAAA,CADA,WHkKJ,CACF,CC1DI,sCEhGA,iBACE,0BH6JJ,CACF,CGzJE,qBAGE,gCAAA,CADA,kBAAA,CADA,gBH6JJ,CGxJI,sDAEE,0CAAA,CACA,sCAAA,CAFA,+BH4JN,CGtJI,8BAEE,2CAAA,CACA,uCAAA,CAFA,aH0JN,CIjPE,4BAEE,2CAAA,CACA,mBAAA,CACA,8BAAA,CAHA,iBAAA,CAIA,2BJoPJ,CIjPI,2EACE,8BJmPN,CI/OI,sCACE,qCAAA,CACA,eJiPN,CI9OM,mEACE,kCJgPR,CI1OE,mCAIE,kCAAA,CAAA,0BAAA,CAHA,eAAA,CACA,eAAA,CAKA,yDAAA,CADA,oBAAA,CADA,kBJ6OJ,CIxOI,+CACE,mBJ0ON,CItOI,sDAEE,YAAA,CADA,WJyON,CIpOI,4DACE,oDJsON,CInOM,kEACE,0CJqOR,CIhOI,yCAIE,yCAAA,CACA,gBAAA,CAJA,iBAAA,CAEA,WAAA,CADA,SJqON,CI9NI,mDAIE,aJgON,CIpOI,mDAIE,cJgON,CIpOI,yCAME,eAAA,CALA,QAAA,CAIA,SJ+NN,CI1NI,mDAIE,aJ4NN,CIhOI,mDAIE,cJ4NN,CIhOI,yCAME,+DAAA,CALA,QAAA,CAIA,mBJ2NN,CIvNM,oDACE,kBJyNR,CIrNM,2CACE,kBJuNR,CInNM,6CAEE,YAAA,CADA,WJsNR,CIlNQ,0FACE,gBJoNV,CKrTI,2BACE,YAAA,CACA,iBLwTN,CKpTI,6BACE,cLsTN,CKlTI,sCACE,YAAA,CACA,cAAA,CACA,sBLoTN,CKjTM,wCACE,aAAA,CACA,aLmTR,CK1SI,mCACE,YL4SN,CKzSM,yCAEE,UAAA,CACA,UAAA,CAFA,aL6SR,CKtSI,6CAEE,UL+SN,CKjTI,6CAEE,WL+SN,CKjTI,mCAOE,kBAAA,CANA,aAAA,CAGA,aAAA,CACA,YAAA,CACA,eAAA,CAEA,kBAAA,CACA,sCACE,CAPF,YL8SN,CKnSM,kFACE,oBLqSR,CKlSQ,0FACE,mBLoSV,CK/RM,4CAME,+CAAA,CALA,yCAAA,CAEA,eAAA,CADA,eAAA,CAEA,kBAAA,CACA,iBLkSR,CK7RM,uCACE,aAAA,CAGA,mCAAA,CADA,WAAA,CAEA,uBAAA,CAHA,ULkSR,CKzRE,oCACE,eL2RJ,CKvRE,sEAEE,eLyRJ","file":"custom.css"}

material/.overrides/assets/stylesheets/custom.f7ec4df2.min.css.map

@@ -1 +0,0 @@
-{"version":3,"sources":["src/.overrides/assets/stylesheets/custom/_typeset.scss","../../../../src/.overrides/assets/stylesheets/custom.scss","src/assets/stylesheets/utilities/_break.scss","src/.overrides/assets/stylesheets/custom/layout/_banner.scss","src/.overrides/assets/stylesheets/custom/layout/_hero.scss","src/.overrides/assets/stylesheets/custom/layout/_iconsearch.scss","src/.overrides/assets/stylesheets/custom/layout/_sponsorship.scss"],"names":[],"mappings":"AA2BA,iBACE,cAIE,kBC7BF,CDgCA,QAEE,qBC/BF,CACF,CD0CE,qBACE,aCxCJ,CD6CE,sBACE,aC3CJ,CD+CE,uBACE,UC7CJ,CDgDI,8BAGE,QAAA,CACA,sBAAA,CAHA,iBAAA,CACA,UC5CN,CDkDI,8BAOE,WAAA,CAFA,WAAA,CAFA,MAAA,CAGA,eAAA,CALA,iBAAA,CACA,KAAA,CAEA,UC7CN,CDqDE,uBACE,2BCnDJ,CDuDE,0BACE,aCrDJ,CDyDE,+BACE,cAAA,CACA,uBCvDJ,CD0DI,0EACE,WCxDN,CD4DI,oCAGE,2CAAA,CADA,gCAAA,CADA,aCxDN,CD+DE,4BACE,UAAA,CACA,uBC7DJ,CDgEI,2EACE,SC9DN,CDsEI,wDAEE,cAAA,CAAA,cCpEN,CCwJI,wCFtFA,wDAMI,oBAAA,CAAA,eCnEN,CACF,CDuEI,4BACE,8BAAA,CAAA,kBCrEN,CD0EE,uBACE,eCxEJ,CD2EI,0BACE,eCzEN,CD4EM,6BACE,iBC1ER,CD+EI,6BACE,YAAA,CACA,SC7EN,CDiFI,gCACE,YAAA,CACA,MAAA,CACA,qBC/EN,CDkFM,qCAEE,oBAAA,CADA,mBAAA,CAEA,6BChFR,CDoFM,kDACE,aClFR,CDsFM,qCACE,WCpFR,CD0FE,wBACE,YAAA,CACA,gBCxFJ,CD2FI,4BAEE,kBAAA,CADA,WCxFN,CDgGM,sCACE,aAAA,CACA,kBC9FR,CDkGM,+BACE,aChGR,CDsGE,wBAEE,sBAAA,CADA,iBCnGJ,CDuGI,iDACE,0BCrGN,CDyGI,+BAEE,eAAA,CADA,iBAAA,CAGA,2BAAA,CADA,uCCtGN,CD6GQ,wDACE,SC3GV,CD+GQ,wDACE,0BC7GV,CDiHQ,wDACE,SC/GV,CDqHI,+BACE,yCACE,CAGF,oDAAA,CADA,mBCpHN,CDwHM,mCACE,aCtHR,CD2HI,+BAKE,kDAAA,CADA,gCAAA,CAFA,aAAA,CAIA,SAAA,CAHA,mBAAA,CAFA,iBAAA,CAMA,mBCzHN,CD8HM,8DACE,2BC5HR,CD2HM,8DACE,2BCzHR,CDwHM,8DACE,2BCtHR,CDqHM,8DACE,uBCnHR,CDkHM,8DACE,0BChHR,CD+GM,6DACE,0BC7GR,CD4GM,8DACE,0BC1GR,CElJA,WACE,wCFqJF,CElJE,kBAEE,kBFoJJ,CEjJE,+BAJE,+BFwJJ,CEjJI,sCAEE,kBFkJN,CEhJM,wDACE,0CAAA,CACA,eFkJR,CE7IE,oBAME,kBAAA,CACA,0CAAA,CANA,oBAAA,CAEA,aAAA,CACA,cAAA,CAIA,mBAAA,CAHA,qBAAA,CAHA,YFqJJ,CE7II,wBACE,aAAA,CACA,eF+IN,CGlLA,eAEE,uYACE,CAFF,gBHsLF,CG3KE,4CACE,yYH6KJ,CGjKA,UAEE,gCAAA,CADA,cHqKF,CGjKE,aAEE,kBAAA,CACA,eAAA,CAFA,kBHqKJ,CCXI,wCE3JF,aAOI,gBHmKJ,CACF,CG/JE,mBACE,mBHiKJ,CCtCI,mCE7IJ,UAwBI,mBAAA,CADA,YHiKF,CG7JE,mBAEE,iBAAA,CADA,eAAA,CAEA,mBH+JJ,CG3JE,iBACE,OAAA,CAEA,0BAAA,CADA,WH8JJ,CACF,CCtDI,sCEhGA,iBACE,0BHyJJ,CACF,CGrJE,qBAGE,gCAAA,CADA,kBAAA,CADA,gBHyJJ,CGpJI,sDAEE,0CAAA,CACA,sCAAA,CAFA,+BHwJN,CGlJI,8BAEE,2CAAA,CACA,uCAAA,CAFA,aHsJN,CI7OE,4BAEE,2CAAA,CACA,mBAAA,CACA,8BAAA,CAHA,iBAAA,CAIA,2BJgPJ,CI7OI,2EACE,8BJ+ON,CI3OI,sCACE,qCAAA,CACA,eJ6ON,CI1OM,mEACE,kCJ4OR,CItOE,mCAIE,kCAAA,CAAA,0BAAA,CAHA,eAAA,CACA,eAAA,CAKA,yDAAA,CADA,oBAAA,CADA,kBJyOJ,CIpOI,+CACE,mBJsON,CIlOI,sDAEE,YAAA,CADA,WJqON,CIhOI,4DACE,oDJkON,CI/NM,kEACE,0CJiOR,CI5NI,yCAIE,yCAAA,CACA,gBAAA,CAJA,iBAAA,CAEA,WAAA,CADA,SJiON,CI1NI,mDAIE,aJ4NN,CIhOI,mDAIE,cJ4NN,CIhOI,yCAME,eAAA,CALA,QAAA,CAIA,SJ2NN,CItNI,mDAIE,aJwNN,CI5NI,mDAIE,cJwNN,CI5NI,yCAME,+DAAA,CALA,QAAA,CAIA,mBJuNN,CInNM,oDACE,kBJqNR,CIjNM,2CACE,kBJmNR,CI/MM,6CAEE,YAAA,CADA,WJkNR,CI9MQ,0FACE,gBJgNV,CKjTI,2BACE,YAAA,CACA,iBLoTN,CKhTI,6BACE,cLkTN,CK9SI,sCACE,YAAA,CACA,cAAA,CACA,sBLgTN,CK7SM,wCACE,aAAA,CACA,aL+SR,CKtSI,mCACE,YLwSN,CKrSM,yCAEE,UAAA,CACA,UAAA,CAFA,aLySR,CKlSI,6CAEE,UL2SN,CK7SI,6CAEE,WL2SN,CK7SI,mCAOE,kBAAA,CANA,aAAA,CAGA,aAAA,CACA,YAAA,CACA,eAAA,CAEA,kBAAA,CACA,sCACE,CAPF,YL0SN,CK/RM,kFACE,oBLiSR,CK9RQ,0FACE,mBLgSV,CK3RM,4CAME,+CAAA,CALA,yCAAA,CAEA,eAAA,CADA,eAAA,CAEA,kBAAA,CACA,iBL8RR,CKzRM,uCACE,aAAA,CAGA,mCAAA,CADA,WAAA,CAEA,uBAAA,CAHA,UL8RR,CKrRE,oCACE,eLuRJ,CKnRE,sEAEE,eLqRJ","file":"custom.css"}

material/.overrides/hooks/shortcodes.py

@@ -0,0 +1,256 @@
+# Copyright (c) 2016-2023 Martin Donath <martin.donath@squidfunk.com>
+
+# Permission is hereby granted, free of charge, to any person obtaining a copy
+# of this software and associated documentation files (the "Software"), to
+# deal in the Software without restriction, including without limitation the
+# rights to use, copy, modify, merge, publish, distribute, sublicense, and/or
+# sell copies of the Software, and to permit persons to whom the Software is
+# furnished to do so, subject to the following conditions:
+
+# The above copyright notice and this permission notice shall be included in
+# all copies or substantial portions of the Software.
+
+# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+# IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+# FITNESS FOR A PARTICULAR PURPOSE AND NON-INFRINGEMENT. IN NO EVENT SHALL THE
+# AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+# LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
+# FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS
+# IN THE SOFTWARE.
+
+from __future__ import annotations
+
+import posixpath
+import re
+
+from mkdocs.config.defaults import MkDocsConfig
+from mkdocs.structure.files import File, Files
+from mkdocs.structure.pages import Page
+from re import Match
+
+# -----------------------------------------------------------------------------
+# Hooks
+# -----------------------------------------------------------------------------
+
+# @todo
+def on_page_markdown(
+    markdown: str, *, page: Page, config: MkDocsConfig, files: Files
+):
+
+    # Replace callback
+    def replace(match: Match):
+        type, args = match.groups()
+        args = args.strip()
+        if type == "version":
+            if args.startswith("insiders-"):
+                return _badge_for_version_insiders(args, page, files)
+            else:
+                return _badge_for_version(args, page, files)
+        elif type == "sponsors":     return _badge_for_sponsors(page, files)
+        elif type == "flag":         return flag(args, page, files)
+        elif type == "option":       return option(args)
+        elif type == "setting":      return setting(args)
+        elif type == "feature":      return _badge_for_feature(args, page, files)
+        elif type == "plugin":       return _badge_for_plugin(args, page, files)
+        elif type == "extension":    return _badge_for_extension(args, page, files)
+        elif type == "utility":      return _badge_for_utility(args, page, files)
+        elif type == "default":
+            if   args == "none":     return _badge_for_default_none(page, files)
+            elif args == "computed": return _badge_for_default_computed(page, files)
+            else:                    return _badge_for_default(args, page, files)
+
+        # Otherwise, raise an error
+        raise RuntimeError(f"Unknown shortcode: {type}")
+
+    # Find and replace all external asset URLs in current page
+    return re.sub(
+        r"<!-- md:(\w+)(.*?) -->",
+        replace, markdown, flags = re.I | re.M
+    )
+
+# -----------------------------------------------------------------------------
+# Helper functions
+# -----------------------------------------------------------------------------
+
+# Create a flag of a specific type
+def flag(args: str, page: Page, files: Files):
+    type, *_ = args.split(" ", 1)
+    if   type == "experimental":  return _badge_for_experimental(page, files)
+    elif type == "required":      return _badge_for_required(page, files)
+    elif type == "customization": return _badge_for_customization(page, files)
+    elif type == "metadata":      return _badge_for_metadata(page, files)
+    elif type == "multiple":      return _badge_for_multiple(page, files)
+    raise RuntimeError(f"Unknown type: {type}")
+
+# Create a linkable option
+def option(type: str):
+    _, *_, name = re.split(r"[.:]", type)
+    return f"[`{name}`](#+{type}){{ #+{type} }}\n\n"
+
+# Create a linkable setting - @todo append them to the bottom of the page
+def setting(type: str):
+    _, *_, name = re.split(r"[.*]", type)
+    return f"`{name}` {{ #{type} }}\n\n[{type}]: #{type}\n\n"
+
+# -----------------------------------------------------------------------------
+
+# Resolve path of file relative to given page - the posixpath always includes
+# one additional level of `..` which we need to remove
+def _resolve_path(path: str, page: Page, files: Files):
+    path, anchor, *_ = f"{path}#".split("#")
+    path = _resolve(files.get_file_from_path(path), page)
+    return "#".join([path, anchor]) if anchor else path
+
+# Resolve path of file relative to given page - the posixpath always includes
+# one additional level of `..` which we need to remove
+def _resolve(file: File, page: Page):
+    path = posixpath.relpath(file.src_uri, page.file.src_uri)
+    return posixpath.sep.join(path.split(posixpath.sep)[1:])
+
+# -----------------------------------------------------------------------------
+
+# Create badge
+def _badge(icon: str, text: str = "", type: str = ""):
+    classes = f"mdx-badge mdx-badge--{type}" if type else "mdx-badge"
+    return "".join([
+        f"<span class=\"{classes}\">",
+        *([f"<span class=\"mdx-badge__icon\">{icon}</span>"] if icon else []),
+        *([f"<span class=\"mdx-badge__text\">{text}</span>"] if text else []),
+        f"</span>",
+    ])
+
+# Create sponsors badge
+def _badge_for_sponsors(page: Page, files: Files):
+    icon = "material-heart"
+    href = _resolve_path("insiders/index.md", page, files)
+    return _badge(
+        icon = f"[:{icon}:]({href} 'Sponsors only')",
+        type = "heart"
+    )
+
+# Create badge for version
+def _badge_for_version(text: str, page: Page, files: Files):
+    spec = text
+    path = f"changelog/index.md#{spec}"
+
+    # Return badge
+    icon = "material-tag-outline"
+    href = _resolve_path("conventions.md#version", page, files)
+    return _badge(
+        icon = f"[:{icon}:]({href} 'Minimum version')",
+        text = f"[{text}]({_resolve_path(path, page, files)})" if spec else ""
+    )
+
+# Create badge for version of Insiders
+def _badge_for_version_insiders(text: str, page: Page, files: Files):
+    spec = text.replace("insiders-", "")
+    path = f"insiders/changelog.md#{spec}"
+
+    # Return badge
+    icon = "material-tag-heart-outline"
+    href = _resolve_path("conventions.md#version-insiders", page, files)
+    return _badge(
+        icon = f"[:{icon}:]({href} 'Minimum version')",
+        text = f"[{text}]({_resolve_path(path, page, files)})" if spec else ""
+    )
+
+# Create badge for feature
+def _badge_for_feature(text: str, page: Page, files: Files):
+    icon = "material-toggle-switch"
+    href = _resolve_path("conventions.md#feature", page, files)
+    return _badge(
+        icon = f"[:{icon}:]({href} 'Optional feature')",
+        text = text
+    )
+
+# Create badge for plugin
+def _badge_for_plugin(text: str, page: Page, files: Files):
+    icon = "material-floppy"
+    href = _resolve_path("conventions.md#plugin", page, files)
+    return _badge(
+        icon = f"[:{icon}:]({href} 'Plugin')",
+        text = text
+    )
+
+# Create badge for extension
+def _badge_for_extension(text: str, page: Page, files: Files):
+    icon = "material-language-markdown"
+    href = _resolve_path("conventions.md#extension", page, files)
+    return _badge(
+        icon = f"[:{icon}:]({href} 'Markdown extension')",
+        text = text
+    )
+
+# Create badge for utility
+def _badge_for_utility(text: str, page: Page, files: Files):
+    icon = "material-package-variant"
+    href = _resolve_path("conventions.md#utility", page, files)
+    return _badge(
+        icon = f"[:{icon}:]({href} 'Third-party utility')",
+        text = text
+    )
+
+# Create badge for default value
+def _badge_for_default(text: str, page: Page, files: Files):
+    icon = "material-water"
+    href = _resolve_path("conventions.md#default", page, files)
+    return _badge(
+        icon = f"[:{icon}:]({href} 'Default value')",
+        text = text
+    )
+
+# Create badge for empty default value
+def _badge_for_default_none(page: Page, files: Files):
+    icon = "material-water-outline"
+    href = _resolve_path("conventions.md#default", page, files)
+    return _badge(
+        icon = f"[:{icon}:]({href} 'Default value is empty')"
+    )
+
+# Create badge for computed default value
+def _badge_for_default_computed(page: Page, files: Files):
+    icon = "material-water-check"
+    href = _resolve_path("conventions.md#default", page, files)
+    return _badge(
+        icon = f"[:{icon}:]({href} 'Default value is computed')"
+    )
+
+# Create badge for metadata property flag
+def _badge_for_metadata(page: Page, files: Files):
+    icon = "material-list-box-outline"
+    href = _resolve_path("conventions.md#metadata", page, files)
+    return _badge(
+        icon = f"[:{icon}:]({href} 'Metadata property')"
+    )
+
+# Create badge for required value flag
+def _badge_for_required(page: Page, files: Files):
+    icon = "material-alert"
+    href = _resolve_path("conventions.md#required", page, files)
+    return _badge(
+        icon = f"[:{icon}:]({href} 'Required value')"
+    )
+
+# Create badge for customization flag
+def _badge_for_customization(page: Page, files: Files):
+    icon = "material-brush-variant"
+    href = _resolve_path("conventions.md#customization", page, files)
+    return _badge(
+        icon = f"[:{icon}:]({href} 'Customization')"
+    )
+
+# Create badge for multiple instance flag
+def _badge_for_multiple(page: Page, files: Files):
+    icon = "material-inbox-multiple"
+    href = _resolve_path("conventions.md#multiple-instances", page, files)
+    return _badge(
+        icon = f"[:{icon}:]({href} 'Multiple instances')"
+    )
+
+# Create badge for experimental flag
+def _badge_for_experimental(page: Page, files: Files):
+    icon = "material-flask-outline"
+    href = _resolve_path("conventions.md#experimental", page, files)
+    return _badge(
+        icon = f"[:{icon}:]({href} 'Experimental')"
+    )

material/.overrides/main.html

@@ -3,7 +3,7 @@
 -#}
 {% extends "base.html" %}
 {% block extrahead %}
-  <link rel="stylesheet" href="{{ 'assets/stylesheets/custom.f7ec4df2.min.css' | url }}">
+  <link rel="stylesheet" href="{{ 'assets/stylesheets/custom.024fa163.min.css' | url }}">
 {% endblock %}
 {% block announce %}
   For updates follow <strong>@squidfunk</strong> on

material/base.html

@@ -44,7 +44,7 @@
       {% endif %}
     {% endblock %}
     {% block styles %}
-      <link rel="stylesheet" href="{{ 'assets/stylesheets/main.046329b4.min.css' | url }}">
+      <link rel="stylesheet" href="{{ 'assets/stylesheets/main.0efb648e.min.css' | url }}">
       {% if config.theme.palette %}
         {% set palette = config.theme.palette %}
         <link rel="stylesheet" href="{{ 'assets/stylesheets/palette.85d0ee34.min.css' | url }}">

material/plugins/info/plugin.py

@@ -80,6 +80,10 @@ class InfoPlugin(BasePlugin[InfoConfig]):
             log.error("Please upgrade to the latest version.")
             self._help_on_versions_and_exit(present, current)
 
+        # Exit if archive creation is disabled
+        if not self.config.archive:
+            sys.exit(1)
+
         # Print message that we're creating a bug report
         log.info("Started archive creation for bug report")
 

material/plugins/search/config.py

@@ -41,6 +41,9 @@ pipeline = ("stemmer", "stopWordFilter", "trimmer")
 
 # Search plugin configuration
 class SearchConfig(Config):
+    enabled = Type(bool, default = True)
+
+    # Settings for search
     lang = Optional(LangOption())
     separator = Optional(Type(str))
     pipeline = ListOfItems(Choice(pipeline), default = [])

material/plugins/search/plugin.py

@@ -58,6 +58,10 @@ class SearchPlugin(BasePlugin[SearchConfig]):
 
     # Initialize plugin
     def on_config(self, config):
+        if not self.config.enabled:
+            return
+
+        # Retrieve default value for language
         if not self.config.lang:
             self.config.lang = [self._translate(
                 config, "search.config.lang"
@@ -104,6 +108,10 @@ class SearchPlugin(BasePlugin[SearchConfig]):
 
     # Add page to search index
     def on_page_context(self, context, *, page, config, nav):
+        if not self.config.enabled:
+            return
+
+        # Index page
         self.search_index.add_entry_from_context(page)
         page.content = re.sub(
             r"\s?data-search-\w+=\"[^\"]+\"",
@@ -113,6 +121,10 @@ class SearchPlugin(BasePlugin[SearchConfig]):
 
     # Generate search index
     def on_post_build(self, *, config):
+        if not self.config.enabled:
+            return
+
+        # Write search index
         base = os.path.join(config.site_dir, "search")
         path = os.path.join(base, "search_index.json")
 

material/plugins/social/plugin.py

@@ -79,7 +79,7 @@ class SocialPlugin(BasePlugin[SocialConfig]):
         if "Image" not in globals():
             raise PluginError(
                 "Required dependencies of \"social\" plugin not found. "
-                "Install with: pip install pillow cairosvg"
+                "Install with: pip install \"mkdocs-material[imaging]\""
             )
 
         # Move color options

mkdocs.yml

@@ -86,12 +86,13 @@ theme:
 plugins:
   - blog
   - search:
-      separator: '[\s\-,:!=\[\]()"`/]+|\.(?!\d)|&[lg]t;|(?!\b)(?=[A-Z][a-z])'
+      separator: '[\s\u200b\-_,:!=\[\]()"`/]+|\.(?!\d)|&[lg]t;|(?!\b)(?=[A-Z][a-z])'
   - minify:
       minify_html: true
 
 # Hooks
 hooks:
+  - material/.overrides/hooks/shortcodes.py
   - material/.overrides/hooks/translations.py
 
 # Customization
@@ -141,11 +142,15 @@ markdown_extensions:
   - pymdownx.inlinehilite
   - pymdownx.keys
   - pymdownx.magiclink:
+      normalize_issue_symbols: true
       repo_url_shorthand: true
       user: squidfunk
       repo: mkdocs-material
   - pymdownx.mark
   - pymdownx.smartsymbols
+  - pymdownx.snippets:
+      auto_append:
+        - includes/mkdocs.md
   - pymdownx.superfences:
       custom_fences:
         - name: mermaid
@@ -153,6 +158,10 @@ markdown_extensions:
           format: !!python/name:pymdownx.superfences.fence_code_format
   - pymdownx.tabbed:
       alternate_style: true
+      combine_header_slug: true
+      slugify: !!python/object/apply:pymdownx.slugs.slugify
+        kwds:
+          case: lower
   - pymdownx.tasklist:
       custom_checkbox: true
   - pymdownx.tilde
@@ -165,6 +174,7 @@ nav:
     - Creating your site: creating-your-site.md
     - Publishing your site: publishing-your-site.md
     - Customization: customization.md
+    - Conventions: conventions.md
     - Browser support: browser-support.md
     - Enterprise feedback: enterprise-support.md
     - Philosophy: philosophy.md
@@ -207,8 +217,23 @@ nav:
       - setup/extensions/index.md
       - Python Markdown: setup/extensions/python-markdown.md
       - Python Markdown Extensions: setup/extensions/python-markdown-extensions.md
-    - Dependencies:
+  - Plugins:
-      - setup/dependencies/image-processing.md
+    - plugins/index.md
+    - Blog: plugins/blog.md
+    - Group: plugins/group.md
+    - Info: plugins/info.md
+    - Meta: plugins/meta.md
+    - Offline: plugins/offline.md
+    - Optimize: plugins/optimize.md
+    - Privacy: plugins/privacy.md
+    - Projects: plugins/projects.md
+    - Search: plugins/search.md
+    - Social: plugins/social.md
+    - Tags: plugins/tags.md
+    - Typeset: plugins/typeset.md
+    - Requirements:
+      - Image processing: plugins/requirements/image-processing.md
+      - Caching: plugins/requirements/caching.md
   - Reference:
     - reference/index.md
     - Admonitions: reference/admonitions.md

pyproject.toml

@@ -49,6 +49,17 @@ classifiers = [
   "Topic :: Text Processing :: Markup :: HTML",
 ]
 
+[project.optional-dependencies]
+recommended = [
+  "mkdocs-minify-plugin~=0.7",
+  "mkdocs-redirects~=1.2",
+  "mkdocs-rss-plugin~=1.6"
+]
+imaging = [
+  "pillow~=9.4",
+  "cairosvg~=2.6"
+]
+
 [project.urls]
 Documentation = "https://squidfunk.github.io/mkdocs-material/"
 Source = "https://github.com/squidfunk/mkdocs-material"

src/.overrides/assets/stylesheets/custom/_typeset.scss

@@ -86,11 +86,53 @@
     animation: heart 1000ms infinite;
   }
 
-  // Insiders color (for links, etc.)
+  // Insiders color (for links, etc.) // remove
   .mdx-insiders {
     color: $clr-pink-500;
   }
 
+  // BETA #####################################################################
+
+  // Badge
+  .mdx-badge {
+    font-size: .85em;
+
+    // Badge with heart
+    &--heart {
+      --md-typeset-a-color:              hsla(#{hex2hsl($clr-pink-500)}, 1);
+      --md-accent-fg-color:              hsla(#{hex2hsl($clr-pink-a200)}, 1);
+      --md-accent-fg-color--transparent: hsla(#{hex2hsl($clr-pink-500)}, 0.1);
+
+      // Animate icon
+      .twemoji {
+        animation: heart 1000ms infinite;
+      }
+    }
+
+    // Badge icon
+    &__icon {
+      padding: px2rem(4px);
+      background: var(--md-accent-fg-color--transparent);
+      border-start-start-radius: px2rem(2px);
+      border-end-start-radius: px2rem(2px);
+
+      // If icon is alone, round corners
+      &:last-child {
+        border-radius: px2rem(2px);
+      }
+    }
+
+    // Badge text
+    &__text {
+      padding: px2rem(4px) px2rem(6px);
+      border-start-end-radius: px2rem(2px);
+      border-end-end-radius: px2rem(2px);
+      box-shadow: 0 0 0 1px inset var(--md-accent-fg-color--transparent);
+    }
+  }
+
+  // BETA #####################################################################
+
   // Switch buttons
   .mdx-switch button {
     cursor: pointer;
@@ -109,17 +151,6 @@
     }
   }
 
-  // Deprecation
-  .mdx-deprecated {
-    opacity: 0.5;
-    transition: opacity 250ms;
-
-    // Deprecation on focus/hover
-    &:is(:focus-within, :hover) {
-      opacity: 1;
-    }
-  }
-
   // Two-column layout
   .mdx-columns {
 
@@ -185,33 +216,6 @@
     }
   }
 
-  // Blog author
-  .mdx-author {
-    display: flex;
-    font-size: px2rem(13.6px);
-
-    // Blog author image
-    img {
-      height: px2rem(40px);
-      border-radius: 100%;
-    }
-
-    // Blog author content
-    p {
-
-      // TODO: refactor, use dedicated classes
-      &:first-child {
-        flex-shrink: 0;
-        margin-right: px2rem(16px);
-      }
-
-      // Blog metadata
-      > span {
-        display: block;
-      }
-    }
-  }
-
   // Social card
   .mdx-social {
     position: relative;

src/.overrides/hooks/shortcodes.py

@@ -0,0 +1,256 @@
+# Copyright (c) 2016-2023 Martin Donath <martin.donath@squidfunk.com>
+
+# Permission is hereby granted, free of charge, to any person obtaining a copy
+# of this software and associated documentation files (the "Software"), to
+# deal in the Software without restriction, including without limitation the
+# rights to use, copy, modify, merge, publish, distribute, sublicense, and/or
+# sell copies of the Software, and to permit persons to whom the Software is
+# furnished to do so, subject to the following conditions:
+
+# The above copyright notice and this permission notice shall be included in
+# all copies or substantial portions of the Software.
+
+# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+# IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+# FITNESS FOR A PARTICULAR PURPOSE AND NON-INFRINGEMENT. IN NO EVENT SHALL THE
+# AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+# LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
+# FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS
+# IN THE SOFTWARE.
+
+from __future__ import annotations
+
+import posixpath
+import re
+
+from mkdocs.config.defaults import MkDocsConfig
+from mkdocs.structure.files import File, Files
+from mkdocs.structure.pages import Page
+from re import Match
+
+# -----------------------------------------------------------------------------
+# Hooks
+# -----------------------------------------------------------------------------
+
+# @todo
+def on_page_markdown(
+    markdown: str, *, page: Page, config: MkDocsConfig, files: Files
+):
+
+    # Replace callback
+    def replace(match: Match):
+        type, args = match.groups()
+        args = args.strip()
+        if type == "version":
+            if args.startswith("insiders-"):
+                return _badge_for_version_insiders(args, page, files)
+            else:
+                return _badge_for_version(args, page, files)
+        elif type == "sponsors":     return _badge_for_sponsors(page, files)
+        elif type == "flag":         return flag(args, page, files)
+        elif type == "option":       return option(args)
+        elif type == "setting":      return setting(args)
+        elif type == "feature":      return _badge_for_feature(args, page, files)
+        elif type == "plugin":       return _badge_for_plugin(args, page, files)
+        elif type == "extension":    return _badge_for_extension(args, page, files)
+        elif type == "utility":      return _badge_for_utility(args, page, files)
+        elif type == "default":
+            if   args == "none":     return _badge_for_default_none(page, files)
+            elif args == "computed": return _badge_for_default_computed(page, files)
+            else:                    return _badge_for_default(args, page, files)
+
+        # Otherwise, raise an error
+        raise RuntimeError(f"Unknown shortcode: {type}")
+
+    # Find and replace all external asset URLs in current page
+    return re.sub(
+        r"<!-- md:(\w+)(.*?) -->",
+        replace, markdown, flags = re.I | re.M
+    )
+
+# -----------------------------------------------------------------------------
+# Helper functions
+# -----------------------------------------------------------------------------
+
+# Create a flag of a specific type
+def flag(args: str, page: Page, files: Files):
+    type, *_ = args.split(" ", 1)
+    if   type == "experimental":  return _badge_for_experimental(page, files)
+    elif type == "required":      return _badge_for_required(page, files)
+    elif type == "customization": return _badge_for_customization(page, files)
+    elif type == "metadata":      return _badge_for_metadata(page, files)
+    elif type == "multiple":      return _badge_for_multiple(page, files)
+    raise RuntimeError(f"Unknown type: {type}")
+
+# Create a linkable option
+def option(type: str):
+    _, *_, name = re.split(r"[.:]", type)
+    return f"[`{name}`](#+{type}){{ #+{type} }}\n\n"
+
+# Create a linkable setting - @todo append them to the bottom of the page
+def setting(type: str):
+    _, *_, name = re.split(r"[.*]", type)
+    return f"`{name}` {{ #{type} }}\n\n[{type}]: #{type}\n\n"
+
+# -----------------------------------------------------------------------------
+
+# Resolve path of file relative to given page - the posixpath always includes
+# one additional level of `..` which we need to remove
+def _resolve_path(path: str, page: Page, files: Files):
+    path, anchor, *_ = f"{path}#".split("#")
+    path = _resolve(files.get_file_from_path(path), page)
+    return "#".join([path, anchor]) if anchor else path
+
+# Resolve path of file relative to given page - the posixpath always includes
+# one additional level of `..` which we need to remove
+def _resolve(file: File, page: Page):
+    path = posixpath.relpath(file.src_uri, page.file.src_uri)
+    return posixpath.sep.join(path.split(posixpath.sep)[1:])
+
+# -----------------------------------------------------------------------------
+
+# Create badge
+def _badge(icon: str, text: str = "", type: str = ""):
+    classes = f"mdx-badge mdx-badge--{type}" if type else "mdx-badge"
+    return "".join([
+        f"<span class=\"{classes}\">",
+        *([f"<span class=\"mdx-badge__icon\">{icon}</span>"] if icon else []),
+        *([f"<span class=\"mdx-badge__text\">{text}</span>"] if text else []),
+        f"</span>",
+    ])
+
+# Create sponsors badge
+def _badge_for_sponsors(page: Page, files: Files):
+    icon = "material-heart"
+    href = _resolve_path("insiders/index.md", page, files)
+    return _badge(
+        icon = f"[:{icon}:]({href} 'Sponsors only')",
+        type = "heart"
+    )
+
+# Create badge for version
+def _badge_for_version(text: str, page: Page, files: Files):
+    spec = text
+    path = f"changelog/index.md#{spec}"
+
+    # Return badge
+    icon = "material-tag-outline"
+    href = _resolve_path("conventions.md#version", page, files)
+    return _badge(
+        icon = f"[:{icon}:]({href} 'Minimum version')",
+        text = f"[{text}]({_resolve_path(path, page, files)})" if spec else ""
+    )
+
+# Create badge for version of Insiders
+def _badge_for_version_insiders(text: str, page: Page, files: Files):
+    spec = text.replace("insiders-", "")
+    path = f"insiders/changelog.md#{spec}"
+
+    # Return badge
+    icon = "material-tag-heart-outline"
+    href = _resolve_path("conventions.md#version-insiders", page, files)
+    return _badge(
+        icon = f"[:{icon}:]({href} 'Minimum version')",
+        text = f"[{text}]({_resolve_path(path, page, files)})" if spec else ""
+    )
+
+# Create badge for feature
+def _badge_for_feature(text: str, page: Page, files: Files):
+    icon = "material-toggle-switch"
+    href = _resolve_path("conventions.md#feature", page, files)
+    return _badge(
+        icon = f"[:{icon}:]({href} 'Optional feature')",
+        text = text
+    )
+
+# Create badge for plugin
+def _badge_for_plugin(text: str, page: Page, files: Files):
+    icon = "material-floppy"
+    href = _resolve_path("conventions.md#plugin", page, files)
+    return _badge(
+        icon = f"[:{icon}:]({href} 'Plugin')",
+        text = text
+    )
+
+# Create badge for extension
+def _badge_for_extension(text: str, page: Page, files: Files):
+    icon = "material-language-markdown"
+    href = _resolve_path("conventions.md#extension", page, files)
+    return _badge(
+        icon = f"[:{icon}:]({href} 'Markdown extension')",
+        text = text
+    )
+
+# Create badge for utility
+def _badge_for_utility(text: str, page: Page, files: Files):
+    icon = "material-package-variant"
+    href = _resolve_path("conventions.md#utility", page, files)
+    return _badge(
+        icon = f"[:{icon}:]({href} 'Third-party utility')",
+        text = text
+    )
+
+# Create badge for default value
+def _badge_for_default(text: str, page: Page, files: Files):
+    icon = "material-water"
+    href = _resolve_path("conventions.md#default", page, files)
+    return _badge(
+        icon = f"[:{icon}:]({href} 'Default value')",
+        text = text
+    )
+
+# Create badge for empty default value
+def _badge_for_default_none(page: Page, files: Files):
+    icon = "material-water-outline"
+    href = _resolve_path("conventions.md#default", page, files)
+    return _badge(
+        icon = f"[:{icon}:]({href} 'Default value is empty')"
+    )
+
+# Create badge for computed default value
+def _badge_for_default_computed(page: Page, files: Files):
+    icon = "material-water-check"
+    href = _resolve_path("conventions.md#default", page, files)
+    return _badge(
+        icon = f"[:{icon}:]({href} 'Default value is computed')"
+    )
+
+# Create badge for metadata property flag
+def _badge_for_metadata(page: Page, files: Files):
+    icon = "material-list-box-outline"
+    href = _resolve_path("conventions.md#metadata", page, files)
+    return _badge(
+        icon = f"[:{icon}:]({href} 'Metadata property')"
+    )
+
+# Create badge for required value flag
+def _badge_for_required(page: Page, files: Files):
+    icon = "material-alert"
+    href = _resolve_path("conventions.md#required", page, files)
+    return _badge(
+        icon = f"[:{icon}:]({href} 'Required value')"
+    )
+
+# Create badge for customization flag
+def _badge_for_customization(page: Page, files: Files):
+    icon = "material-brush-variant"
+    href = _resolve_path("conventions.md#customization", page, files)
+    return _badge(
+        icon = f"[:{icon}:]({href} 'Customization')"
+    )
+
+# Create badge for multiple instance flag
+def _badge_for_multiple(page: Page, files: Files):
+    icon = "material-inbox-multiple"
+    href = _resolve_path("conventions.md#multiple-instances", page, files)
+    return _badge(
+        icon = f"[:{icon}:]({href} 'Multiple instances')"
+    )
+
+# Create badge for experimental flag
+def _badge_for_experimental(page: Page, files: Files):
+    icon = "material-flask-outline"
+    href = _resolve_path("conventions.md#experimental", page, files)
+    return _badge(
+        icon = f"[:{icon}:]({href} 'Experimental')"
+    )

src/assets/stylesheets/main/components/_tag.scss

@@ -50,7 +50,6 @@
     font-weight: 700;
     line-height: 1.6;
     letter-spacing: initial;
-    vertical-align: middle;
     background: var(--md-default-fg-color--lightest);
     border-radius: px2rem(48px);
 

src/plugins/info/plugin.py

@@ -80,6 +80,10 @@ class InfoPlugin(BasePlugin[InfoConfig]):
             log.error("Please upgrade to the latest version.")
             self._help_on_versions_and_exit(present, current)
 
+        # Exit if archive creation is disabled
+        if not self.config.archive:
+            sys.exit(1)
+
         # Print message that we're creating a bug report
         log.info("Started archive creation for bug report")
 

src/plugins/search/config.py

@@ -41,6 +41,9 @@ pipeline = ("stemmer", "stopWordFilter", "trimmer")
 
 # Search plugin configuration
 class SearchConfig(Config):
+    enabled = Type(bool, default = True)
+
+    # Settings for search
     lang = Optional(LangOption())
     separator = Optional(Type(str))
     pipeline = ListOfItems(Choice(pipeline), default = [])

src/plugins/search/plugin.py

@@ -58,6 +58,10 @@ class SearchPlugin(BasePlugin[SearchConfig]):
 
     # Initialize plugin
     def on_config(self, config):
+        if not self.config.enabled:
+            return
+
+        # Retrieve default value for language
         if not self.config.lang:
             self.config.lang = [self._translate(
                 config, "search.config.lang"
@@ -104,6 +108,10 @@ class SearchPlugin(BasePlugin[SearchConfig]):
 
     # Add page to search index
     def on_page_context(self, context, *, page, config, nav):
+        if not self.config.enabled:
+            return
+
+        # Index page
         self.search_index.add_entry_from_context(page)
         page.content = re.sub(
             r"\s?data-search-\w+=\"[^\"]+\"",
@@ -113,6 +121,10 @@ class SearchPlugin(BasePlugin[SearchConfig]):
 
     # Generate search index
     def on_post_build(self, *, config):
+        if not self.config.enabled:
+            return
+
+        # Write search index
         base = os.path.join(config.site_dir, "search")
         path = os.path.join(base, "search_index.json")
 

src/plugins/social/plugin.py

@@ -79,7 +79,7 @@ class SocialPlugin(BasePlugin[SocialConfig]):
         if "Image" not in globals():
             raise PluginError(
                 "Required dependencies of \"social\" plugin not found. "
-                "Install with: pip install pillow cairosvg"
+                "Install with: pip install \"mkdocs-material[imaging]\""
             )
 
         # Move color options