Merge branch 'master' into fix/instant-loading

.dockerignore

@@ -22,6 +22,6 @@
 .git
 .github
 docs
-material/.overrides
+material/overrides
 node_modules
 src

.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

.github/ISSUE_TEMPLATE/01-report-a-bug.yml

@@ -10,7 +10,8 @@ body:
         This field is optional. You may provide additional context for the bug
         you want to report, helping us to understand what you are working on and
         what you are trying to achieve. If the context is not relevant, you can
-        leave this field empty. [More](https://squidfunk.github.io/mkdocs-material/contributing/reporting-a-bug/#context)
+        leave this field empty.
+        [More](https://squidfunk.github.io/mkdocs-material/contributing/reporting-a-bug/#context)
 
   - type: textarea
     id: description
@@ -20,7 +21,8 @@ body:
         Please give a detailed description of the bug. Explain where Material
         for MkDocs does not behave as you would expect it to. Be as specific as
         possible. If you have found a workaround or a fix for the problem,
-        please let us maintainers (and all other users) know. [More](https://squidfunk.github.io/mkdocs-material/contributing/reporting-a-bug/#description)
+        please let us maintainers (and all other users) know.
+        [More](https://squidfunk.github.io/mkdocs-material/contributing/reporting-a-bug/#bug-description)
     validations:
       required: true
 
@@ -30,7 +32,7 @@ body:
       label: Related links
       description: >-
         Please list all links to the sections of
-        [our documentation](https://squidfunk.github.io/mkdocs-material) that
+        [our documentation](https://squidfunk.github.io/mkdocs-material/) that
         are relevant to the bug in order to show that you have consulted and
         thoroughly read it. Additionally, list links to possibly related open
         and closed [issues](https://github.com/squidfunk/mkdocs-material/issues)
@@ -50,11 +52,12 @@ body:
       description: >-
         Please create a __.zip file__ with a __minimal reproduction__ for the
         bug. First, read our [reproduction guide](https://squidfunk.github.io/mkdocs-material/guides/creating-a-reproduction/)
-        that explains the necessary steps, then use the [built-in info plugin](https://squidfunk.github.io/mkdocs-material/guides/creating-a-reproduction/#creating-a-zip-file) (mandatory) to create a self-contained
+        that explains the necessary steps, then use the [built-in info plugin](https://squidfunk.github.io/mkdocs-material/plugins/info/) (mandatory) to create a self-contained
         .zip file with the reproduction. We reserve the right to close issues
-        without .zip files. [More](https://squidfunk.github.io/mkdocs-material/contributing/reporting-a-bug/#reproduction)
+        without .zip files.
+        [More](https://squidfunk.github.io/mkdocs-material/contributing/reporting-a-bug/#reproduction)
       placeholder: |-
-        Drag and drop the .zip file with minimal reproduction here.
+        Drag and drop the .zip file with the minimal reproduction here.
     validations:
       required: true
 
@@ -66,7 +69,8 @@ body:
         Please provide a detailed list of instructions, guiding us maintainers
         through the required steps, helping us to recreate the problem using the
         minimal reproduction you provided. Be as specific as possible and as
-        verbose as necessary – try not to leave anything out. [More](https://squidfunk.github.io/mkdocs-material/contributing/reporting-a-bug/#steps-to-reproduce)
+        verbose as necessary – try not to leave anything out.
+        [More](https://squidfunk.github.io/mkdocs-material/contributing/reporting-a-bug/#steps-to-reproduce)
       placeholder: |-
         1. ...
         2. ...
@@ -79,10 +83,11 @@ body:
     attributes:
       label: Browser
       description: >-
-        If the bug only happens in __specific browsers__, please select them
+        This field is optional. If the bug only happens in __specific browsers__,
-        from the dropdown below. If your browser is not listed or the version
+        please select them from the dropdown below. If your browser is not
-        is relevant, you may select _Other_ and provide more details in the
+        listed or the version is relevant, you may select _Other_ and provide
-        field above. [More](https://squidfunk.github.io/mkdocs-material/contributing/reporting-a-bug/#browser)
+        more details in the field above.
+        [More](https://squidfunk.github.io/mkdocs-material/contributing/reporting-a-bug/#browser)
       multiple: true
       options:
         - Chrome
@@ -106,7 +111,7 @@ body:
             I have read and followed the [bug reporting guidelines](https://squidfunk.github.io/mkdocs-material/contributing/reporting-a-bug/).
           required: true
         - label: >-
-            I have attached links to [the documentation](https://squidfunk.github.io/mkdocs-material),
+            I have attached links to [the documentation](https://squidfunk.github.io/mkdocs-material/),
             and possibly related [issues](https://github.com/squidfunk/mkdocs-material/issues)
             and [discussions](https://github.com/squidfunk/mkdocs-material/discussions).
           required: true

.github/ISSUE_TEMPLATE/02-report-a-docs-issue.yml

@@ -1,4 +1,4 @@
-name: Report a docs issue
+name: Report a documentation issue
 description: Missing information in our docs? Report a documentation issue
 labels:
   - documentation
@@ -10,7 +10,7 @@ body:
       label: Description
       description: >-
         Please describe the inconsistency or issue you have found in
-        [our documentation](https://squidfunk.github.io/mkdocs-material)
+        [our documentation](https://squidfunk.github.io/mkdocs-material/)
         or indicate where you feel there is a need for improvement. Furthermore,
         explain the severity of the issue, i.e., its impact on you and potentially
         other users.
@@ -23,7 +23,7 @@ body:
     attributes:
       label: Related links
       description: >-
-        Please list all links to the sections of [our documentation](https://squidfunk.github.io/mkdocs-material)
+        Please list all links to the sections of [our documentation](https://squidfunk.github.io/mkdocs-material/)
         that are impacted by the issue you described above. If applicable,
         add screenshots. Additionally, list links to possibly related open
         and closed [issues](https://github.com/squidfunk/mkdocs-material/issues)
@@ -58,8 +58,8 @@ body:
         valuable time.
       options:
         - label: >-
-            I have read and followed the [documentation issue reporting guidelines](https://squidfunk.github.io/mkdocs-material/contributing/reporting-a-docs-issue/).
+            I have read and followed the [documentation issue guidelines](https://squidfunk.github.io/mkdocs-material/contributing/reporting-a-docs-issue/).
           required: true
         - label: >-
-            I have attached the links to the described sections of [the documentation](https://squidfunk.github.io/mkdocs-material/contributing/reporting-a-docs-issue/#related-links)
+            I have attached the links to the affected sections of [the documentation](https://squidfunk.github.io/mkdocs-material/contributing/reporting-a-docs-issue/#related-links)
           required: true

.github/ISSUE_TEMPLATE/03-request-a-change.yml

@@ -10,7 +10,8 @@ body:
         This field is optional. You may provide additional context for the idea
         you want to propose, helping us to understand what you are working on
         and what you are trying to achieve. If the context is not relevant, you
-        can leave this field empty. [More](https://squidfunk.github.io/mkdocs-material/contributing/requesting-a-change/#context)
+        can leave this field empty.
+        [More](https://squidfunk.github.io/mkdocs-material/contributing/requesting-a-change/#context)
 
   - type: textarea
     id: description
@@ -32,10 +33,9 @@ body:
       description: >-
         Please list all links to open and closed [issues](https://github.com/squidfunk/mkdocs-material/issues),
         [discussions](https://github.com/squidfunk/mkdocs-material/discussions),
-        or to [documentation sections](https://squidfunk.github.io/mkdocs-material)
+        or to [documentation sections](https://squidfunk.github.io/mkdocs-material/)
-        that are relevant to your idea.
+        that are relevant to your idea. If you discussed your idea with the
-        If you discussed your idea with the community on our
+        community on our [discussion board](https://github.com/squidfunk/mkdocs-material/discussions)
-        [discussion board](https://github.com/squidfunk/mkdocs-material/discussions)
         prior to creating this change request, please link the discussion here as well.
         [More](https://squidfunk.github.io/mkdocs-material/contributing/requesting-a-change/#related-links)
       value: |-
@@ -51,7 +51,7 @@ body:
       description: >-
         Please explain how your idea will work from an author's and user's
         perspective. Elaborate on how the change would positively impact not only
-        you but the community and how it aligns with the goals and [philosophy](https://squidfunk.github.io/mkdocs-material/philosophy/)
+        you but our community and how it aligns with the goals and [philosophy](https://squidfunk.github.io/mkdocs-material/philosophy/)
         of the project.
         [More](https://squidfunk.github.io/mkdocs-material/contributing/requesting-a-change/#use-cases)
     validations:
@@ -90,6 +90,6 @@ body:
             I have ensured that, to the best of my knowledge, [my idea will benefit the entire community](https://squidfunk.github.io/mkdocs-material/contributing/requesting-a-change/#benefit-for-the-community).
         required: true
       - label: >-
-            I have included relevant links to [the documentation](https://squidfunk.github.io/mkdocs-material), related [issues](https://github.com/squidfunk/mkdocs-material/issues),
+            I have included relevant links to [the documentation](https://squidfunk.github.io/mkdocs-material/), related [issues](https://github.com/squidfunk/mkdocs-material/issues),
             and [discussions](https://github.com/squidfunk/mkdocs-material/discussions) to underline the need for my idea.
         required: true

.github/ISSUE_TEMPLATE/04-add-a-translation.yml

@@ -1,94 +0,0 @@
-name: Add a translation
-description: Missing support for your language? Add a translation
-title: Add translations for ...
-labels:
-  - change request
-body:
-
-  - type: markdown
-    attributes:
-      value: >-
-        **Important**: Before creating a new translation, please make sure that
-        Material for MkDocs does not already include support for your language.
-        Please check the list of all [available languages](https://squidfunk.github.io/mkdocs-material/setup/changing-the-language/#site-language)
-        and help us by adding missing translations.
-
-  - type: textarea
-    id: translations
-    attributes:
-      label: Translations
-      description: Please translate the labels on the right, e.g., "Copy to clipboard", etc.
-      value: |-
-        {% macro t(key) %}{{ {
-          "language": "en",
-          "direction": "ltr",
-          "action.edit": "Edit this page",
-          "action.skip": "Skip to content",
-          "action.view": "View source of this page",
-          "announce.dismiss": "Don't show this again",
-          "blog.archive": "Archive",
-          "blog.categories": "Categories",
-          "blog.categories.in": "in",
-          "blog.continue": "Continue reading",
-          "blog.draft": "Draft",
-          "blog.index": "Back to index",
-          "blog.meta": "Metadata",
-          "blog.references": "Related links",
-          "clipboard.copy": "Copy to clipboard",
-          "clipboard.copied": "Copied to clipboard",
-          "consent.accept": "Accept",
-          "consent.manage": "Manage settings",
-          "consent.reject": "Reject",
-          "footer": "Footer",
-          "footer.next": "Next",
-          "footer.previous": "Previous",
-          "header": "Header",
-          "meta.comments": "Comments",
-          "meta.source": "Source",
-          "nav": "Navigation",
-          "readtime.one": "1 min read",
-          "readtime.other": "# min read",
-          "rss.created": "RSS feed",
-          "rss.updated": "RSS feed of updated content",
-          "search": "Search",
-          "search.placeholder": "Search",
-          "search.share": "Share",
-          "search.reset": "Clear",
-          "search.result.initializer": "Initializing search",
-          "search.result.placeholder": "Type to start searching",
-          "search.result.none": "No matching documents",
-          "search.result.one": "1 matching document",
-          "search.result.other": "# matching documents",
-          "search.result.more.one": "1 more on this page",
-          "search.result.more.other": "# more on this page",
-          "search.result.term.missing": "Missing",
-          "select.language": "Select language",
-          "select.version": "Select version",
-          "source": "Go to repository",
-          "source.file.contributors": "Contributors",
-          "source.file.date.created": "Created",
-          "source.file.date.updated": "Last update",
-          "tabs": "Tabs",
-          "toc": "Table of contents",
-          "top": "Back to top"
-        }[key] }}{% endmacro %}
-      render: Jinja
-    validations:
-      required: true
-
-  - type: checkboxes
-    id: checklist
-    attributes:
-      label: Before submitting
-      description: >-
-        Please ensure that your translation fulfills the following
-        requirements.
-      options:
-        - label: I've checked the list of [available languages](https://squidfunk.github.io/mkdocs-material/setup/changing-the-language/#site-language) for existing translations.
-          required: true
-        - label: I assure that the translations are accurate to the best of my knowledge.
-          required: true
-        - label: >-
-            __Optional__: I want to integrate this translation myself and create a
-            pull request following the [contribution guide](https://github.com/squidfunk/mkdocs-material/blob/master/CONTRIBUTING.md).
-

.github/ISSUE_TEMPLATE/04-add-translations.yml

@@ -0,0 +1,111 @@
+name: Add a translation
+description: Missing support for your language? Add a translation
+title: Add translations for ...
+labels:
+  - change request
+body:
+
+  - type: markdown
+    attributes:
+      value: >-
+        **Important**: Before creating a new translation, please check if
+        Material for MkDocs already supports your language. Review the list of
+        [available languages](https://squidfunk.github.io/mkdocs-material/setup/changing-the-language/#site-language),
+        pick your language to add new or improve existing translations.
+
+  - type: textarea
+    id: translations
+    attributes:
+      label: Translations
+      description: >-
+        Please translate the labels on the right. For new languages, translate
+        each line. For existing languages, only translate lines containing the
+        :arrow_left: icon and remove the icon before submitting.
+        [More](https://squidfunk.github.io/mkdocs-material/contributing/adding-translations/#translations_1)
+      value: |-
+        {% macro t(key) %}{{ {
+          "language": "en ⬅️",
+          "direction": "ltr ⬅️",
+          "action.edit": "Edit this page ⬅️",
+          "action.skip": "Skip to content ⬅️",
+          "action.view": "View source of this page ⬅️",
+          "announce.dismiss": "Don't show this again ⬅️",
+          "blog.archive": "Archive ⬅️",
+          "blog.categories": "Categories ⬅️",
+          "blog.categories.in": "in ⬅️",
+          "blog.continue": "Continue reading ⬅️",
+          "blog.draft": "Draft ⬅️",
+          "blog.index": "Back to index ⬅️",
+          "blog.meta": "Metadata ⬅️",
+          "blog.references": "Related links ⬅️",
+          "clipboard.copy": "Copy to clipboard ⬅️",
+          "clipboard.copied": "Copied to clipboard ⬅️",
+          "consent.accept": "Accept ⬅️",
+          "consent.manage": "Manage settings ⬅️",
+          "consent.reject": "Reject ⬅️",
+          "footer": "Footer ⬅️",
+          "footer.next": "Next ⬅️",
+          "footer.previous": "Previous ⬅️",
+          "header": "Header ⬅️",
+          "meta.comments": "Comments ⬅️",
+          "meta.source": "Source ⬅️",
+          "nav": "Navigation ⬅️",
+          "readtime.one": "1 min read ⬅️",
+          "readtime.other": "# min read ⬅️",
+          "rss.created": "RSS feed ⬅️",
+          "rss.updated": "RSS feed of updated content ⬅️",
+          "search": "Search ⬅️",
+          "search.placeholder": "Search ⬅️",
+          "search.share": "Share ⬅️",
+          "search.reset": "Clear ⬅️",
+          "search.result.initializer": "Initializing search ⬅️",
+          "search.result.placeholder": "Type to start searching ⬅️",
+          "search.result.none": "No matching documents ⬅️",
+          "search.result.one": "1 matching document ⬅️",
+          "search.result.other": "# matching documents ⬅️",
+          "search.result.more.one": "1 more on this page ⬅️",
+          "search.result.more.other": "# more on this page ⬅️",
+          "search.result.term.missing": "Missing ⬅️",
+          "select.language": "Select language ⬅️",
+          "select.version": "Select version ⬅️",
+          "source": "Go to repository ⬅️",
+          "source.file.contributors": "Contributors ⬅️",
+          "source.file.date.created": "Created ⬅️",
+          "source.file.date.updated": "Last update ⬅️",
+          "tabs": "Tabs ⬅️",
+          "toc": "Table of contents ⬅️",
+          "top": "Back to top ⬅️"
+        }[key] }}{% endmacro %}
+      render: Jinja
+    validations:
+      required: true
+
+  - type: input
+    id: country-flag
+    attributes:
+      label: Country flag
+      description: >-
+        This field is optional. Please add the flag of the country when adding a
+        new language. Go to our [emoji search](https://squidfunk.github.io/mkdocs-material/reference/icons-emojis/#search)
+        and enter `flag` to find all available shortcodes. If your flag is not
+        included, please choose the most appropriate available flag.
+        [More](https://squidfunk.github.io/mkdocs-material/contributing/adding-translations/#country-flag)
+      placeholder: |-
+        Country flag shortcode, e.g. :flag_en:
+
+  - type: checkboxes
+    id: checklist
+    attributes:
+      label: Before submitting
+      description: >-
+        Please ensure that your translation fulfills the following requirements.
+      options:
+        - label: >-
+            I've checked the list of [available languages](https://squidfunk.github.io/mkdocs-material/setup/changing-the-language/#site-language) for existing translations.
+          required: true
+        - label: >-
+            I assure that the translations are accurate to the best of my knowledge.
+          required: true
+        - label: >-
+            __Optional__: I want to integrate this translation myself and create a
+            pull request following the [contribution guide](https://github.com/squidfunk/mkdocs-material/blob/master/CONTRIBUTING.md).

.github/ISSUE_TEMPLATE/config.yml

@@ -22,4 +22,6 @@ blank_issues_enabled: false
 contact_links:
   - name: Ask a question
     url: https://github.com/squidfunk/mkdocs-material/discussions
-    about: Have a question or need help? Connect with the community on our discussion board
+    about: >
+      Have a question or need help? Connect with our community on the
+      discussion board

.github/dependabot.yml

@@ -28,7 +28,9 @@ updates:
     interval: weekly
     time: "04:00"
 - package-ecosystem: pip
-  open-pull-requests-limit: 10
+  # We only want to bump versions of packages in case of security updates, as
+  # we want to keep maximum compatibility - see https://t.ly/INSR_
+  open-pull-requests-limit: 0
   directory: "/"
   labels: []
   schedule:

.github/workflows/build.yml

@@ -41,7 +41,7 @@ jobs:
     steps:
 
       - name: Checkout repository
-        uses: actions/checkout@v3
+        uses: actions/checkout@v4
 
       - name: Set up Node.js runtime
         uses: actions/setup-node@v3
@@ -72,7 +72,7 @@ jobs:
     steps:
 
       - name: Checkout repository
-        uses: actions/checkout@v3
+        uses: actions/checkout@v4
 
       - name: Set up Python runtime
         uses: actions/setup-python@v4
@@ -97,24 +97,24 @@ jobs:
     steps:
 
       - name: Checkout repository
-        uses: actions/checkout@v3
+        uses: actions/checkout@v4
 
       - name: Set up QEMU
-        uses: docker/setup-qemu-action@v2
+        uses: docker/setup-qemu-action@v3
 
       - name: Set up Docker Buildx
-        uses: docker/setup-buildx-action@v2
+        uses: docker/setup-buildx-action@v3
 
       - name: Login to DockerHub
         if: github.event_name == 'release'
-        uses: docker/login-action@v2
+        uses: docker/login-action@v3
         with:
           username: ${{ secrets.DOCKER_USERNAME }}
           password: ${{ secrets.DOCKER_PASSWORD }}
 
       - name: Login to GitHub Container Registry
         if: github.event_name == 'release'
-        uses: docker/login-action@v2
+        uses: docker/login-action@v3
         with:
           registry: ghcr.io
           username: ${{ github.repository_owner }}
@@ -122,7 +122,7 @@ jobs:
 
       - name: Generate Docker tags and labels
         id: meta
-        uses: docker/metadata-action@v4
+        uses: docker/metadata-action@v5
         with:
           images: |
             ${{ github.event.repository.full_name }}
@@ -137,7 +137,7 @@ jobs:
             latest=${{ github.event.release.prerelease == false }}
 
       - name: Build Docker image
-        uses: docker/build-push-action@v4
+        uses: docker/build-push-action@v5
         with:
           context: .
           load: true
@@ -158,7 +158,7 @@ jobs:
           echo "PLATFORMS=linux/amd64,linux/arm64,linux/arm/v7" >> $GITHUB_ENV
 
       - name: Publish Docker image
-        uses: docker/build-push-action@v4
+        uses: docker/build-push-action@v5
         with:
           context: .
           platforms: ${{ env.PLATFORMS }}

.github/workflows/documentation.yml

@@ -37,7 +37,7 @@ jobs:
     steps:
 
       - name: Checkout repository
-        uses: actions/checkout@v3
+        uses: actions/checkout@v4
         with:
           fetch-depth: 0
 
@@ -70,6 +70,7 @@ jobs:
             "mkdocs-minify-plugin>=0.3" \
             "mkdocs-rss-plugin>=1.2" \
             "mkdocs-redirects>=1.0" \
+            "lxml" \
             "pillow<10"
 
       - name: Install Insiders build

.gitignore

@@ -55,10 +55,6 @@ example.zip
 # Never ignore .gitkeep files
 !**/.gitkeep
 
-# Husky hooks
-.husky/.gitignore
-.husky/_
-
 # macOS internals
 .DS_Store
 

.vscode/settings.json

@@ -14,8 +14,8 @@
   "yaml.customTags": [
     "!ENV scalar",
     "!ENV sequence",
-    "tag:yaml.org,2002:python/name:materialx.emoji.to_svg",
+    "tag:yaml.org,2002:python/name:material.extensions.emoji.to_svg",
-    "tag:yaml.org,2002:python/name:materialx.emoji.twemoji",
+    "tag:yaml.org,2002:python/name:material.extensions.emoji.twemoji",
     "tag:yaml.org,2002:python/name:pymdownx.superfences.fence_code_format"
   ]
 }

CHANGELOG

@@ -1,3 +1,202 @@
+mkdocs-material-9.4.1 (2023-09-22)
+
+  * Improved colors and contrast in dark mode
+  * Improved admonition borders to match font weight
+  * Switched content tabs to neutral color
+
+mkdocs-material-9.4.0 (2023-09-21)
+
+  * Added Belarusian translations
+  * Added version info to entrypoint of package
+  * Added emoji extension as a replacement for materialx
+  * Improved slate color scheme (dark mode) - now even darker
+  * Restructured project to improve development experience
+  * Updated MkDocs to 1.5.3
+  * Fixed #3890: Development mode crashes on Linux
+
+mkdocs-material-9.3.2+insiders-4.42.0 (2023-09-19)
+
+  * Added support for using git submodules in projects plugin
+  * Added support for transforming project configurations
+  * Improved resilience of optimize and blog plugin
+  * Fixed optimize plugin crashing on .jpeg extension
+  * Fixed project URLs not using site URLs in projects plugin
+
+mkdocs-material-9.3.2 (2023-09-19)
+
+  * Updated Slovenian translations
+  * Updated Python dependencies in requirements to use minimum versions
+  * Fixed #6017: Code highlighting inconsistent in Community and Insiders edition
+  * Fixed #6001: Contributor avatars display incorrectly in Firefox
+  * Fixed #6000: Blog post drafts are included in navigation
+
+mkdocs-material-9.3.1+insiders-4.41.0 (2023-09-11)
+
+  * Improved multi-instance support for optimize plugin
+  * Added inclusion and exclusion patterns for optimize plugin
+  * Added transparent keyword for color handling in social plugin
+  * Changed default quality of PNGs to 3 in optimize plugin
+  * Fixed #5979: meta file not detected in root of docs directory
+
+mkdocs-material-9.3.1 (2023-09-11)
+
+  * Fixed crash of group plugin when used together with hooks
+
+mkdocs-material-9.3.0 (2023-09-11)
+
+  * Improved configuration sharing between Community and Insiders edition
+  * Added experimental built-in group plugin for enabling plugins conditionally
+  * Added new settings in tags plugin for enabling/disabling
+  * Dropped support for Python 3.7 (EOL)
+
+mkdocs-material-9.2.8+insiders-4.40.4 (2023-09-04)
+
+  * Fixed privacy plugin choking on boolean HTML5 attributes
+  * Fixed wrapping of inline code blocks in typeset table of contents
+  * Fixed blog plugin error when running under dirty reload
+
+mkdocs-material-9.2.8 (2023-09-04)
+
+  * Updated Italian and Russian translations
+  * Fixed #5952: Combining blog and tags plugin leads to wrong links
+  * Fixed #5951: Blog plugin ignores post title in metadata
+  * Fixed #5949: Blog plugin ignores post linked in nav
+
+mkdocs-material-9-2.7+insiders-4.40.3 (2023-09-02)
+
+  * Fixed #5946: Docker image missing pngquant for optimize plugin
+
+mkdocs-material-9.2.7 (2023-09-02)
+
+  * Switched dependencies to compatible release clauses
+  * Removed readtime and lxml dependencies for blog plugin
+  * Reduced size of Docker image to improve CI build performance
+  * Fixed #5945: Incorrect footer navigation for sibling pages of blog
+  * Fixed #5939: Page jumps when changing color palette (Firefox 117)
+  * Fixed #5901: Announcement bar reappears when using instant loading
+  * Fixed #5824: Allow to customize styles of sequence diagrams
+
+mkdocs-material-9-2.6+insiders-4.40.2 (2023-08-31)
+
+  * Added configurable error handling capabilities for social plugin
+  * Fixed #5922: Blog plugin shows no posts when building a standalone blog
+  * Fixed #5914: Tags plugin tags_extra_files errors (4.39.3 regression)
+  * Fixed #5904: Blog plugin sometimes excludes files (4.40.1 regression)
+
+mkdocs-material-9-2.6 (2023-08-31)
+
+  * Added Basque translations
+  * Added template for simple redirects
+  * Improved blog plugin interop by moving view generation to on_files
+  * Fixed #5924: Social plugin still checks dependencies when disabled
+  * Fixed #5916: Blog plugin crashes on Python 3.8 (9.2.0 regression)
+
+mkdocs-material-9-2.5+insiders-4.40.1 (2023-08-27)
+
+  * Fixed #5902: ResizeObserver polyfill not detected by privacy plugin
+  * Fixed empty category pages in blog plugin (4.40.0 regression)
+
+mkdocs-material-9-2.5 (2023-08-27)
+
+  * Fixed error in dirty serve mode when using blog plugin
+  * Fixed page title not being consistent in blog plugin pagination
+  * Fixed #5899: Blog plugin pagination breaks when disabling directory URLs
+
+mkdocs-material-9.2.4+insiders-4.40.0 (2023-08-26)
+
+  * Added logo, title and description options to social plugin default layouts
+  * Fixed privacy plugin compatibility issue with Python < 3.10
+  * Fixed #5896: Blog plugin errors when using custom index pages
+
+mkdocs-material-9.2.4 (2023-08-26)
+
+  * Added version to bug report name in info plugin
+  * Updated Afrikaans translations
+
+mkdocs-material-9.2.3+insiders-4.39.3 (2023-08-24)
+
+  * Fixed lxml dependency missing in Docker image (4.39.2 regression)
+
+mkdocs-material-9.2.3+insiders-4.39.2 (2023-08-23)
+
+  * Fixed color palette toggle being reversed (9.2.0 regression)
+
+mkdocs-material-9.2.3 (2023-08-22)
+
+  * Fixed blog plugin rendering wrongly with markdown.extensions.toc
+  * Fixed blog plugin entrypoint generation
+
+mkdocs-material-9.2.2 (2023-08-22)
+
+  * Fixed #5880: Blog plugin failing when building a standalone blog
+  * Fixed #5881: Blog plugin not compatible with Python < 3.10
+
+mkdocs-material-9.2.1 (2023-08-21)
+
+  * Fixed #5879: Blog plugin failing when building a standalone blog
+  * Fixed error in blog plugin when using draft tagging on future date
+  * Fixed error in blog plugin when toc extension is not enabled
+
+mkdocs-material-9.2.0+insiders-4.39.1 (2023-08-21)
+
+  * Fixed git diff in tags plugin after merging back 9.2.0 changes
+
+mkdocs-material-9.2.0 (2023-08-21)
+
+  Additions and improvements
+
+  * Added blogging support via built-in blog plugin
+  * Added support for Chinese language segmentaiton in search plugin
+  * Added support for adding custom dates to blog posts
+  * Added support for paginating archive and category pages
+  * Added support for annotations (outside of code blocks)
+  * Added support for navigation icons
+  * Added support for navigation pruning
+  * Added support for navigation status
+  * Added support for customizing site icons
+  * Added support for customizing (code) annotation icons
+  * Added focus outline to admonitions and details
+  * Added prompt for bug report name to info plugin
+  * Added Luxembourgish translations
+  * Improved rendering of (code) annotation markers
+  * Improved print styles for (code) annotations
+  * Improved customizability of navigation tabs
+  * Improved interop of plugins with external tools like mike
+  * Improved interop of blog plugin with awesome pages plugin
+  * Improved header partial by moving buttons into separate partials
+  * Improved clarity of site_url warning in social plugin
+  * Improved blog plugin to automatically setup directory structure
+  * Switched info plugin to importlib to mitigate deprecations
+  * Automatically download ResizeObserver polyfill when necessary
+  * Automatically add iframe-worker polyfill when necessary in offline plugin
+  * Automatically focus and bring up keyboard on touch devices
+  * Updated Serbo-Croatian translations
+  * Updated MkDocs to 1.5.2
+
+  Removals
+
+  * Removed Universal Analytics integration
+  * Removed ancient polyfills to reduce size of bundled JavaScript by 20%
+  * Removed necessity for Array.flat and Array.flatMap polyfill
+  * Removed announcement bar button when JavaScript is not available
+
+  Fixes
+
+  * Fixed rendering of tags when announcement bar is present
+  * Fixed tags plugin rendering pages excluded by other plugins
+  * Fixed #5132: Blog plugin requires nav entry in mkdocs.yml
+  * Fixed #5599: Insufficient contrast for default link color
+  * Fixed #5715: Blog plugin missing integrated table of contents in pagination
+  * Fixed #5806: Version selector not hoverable on some Android devices
+  * Fixed #5826: Blog post drafts with tags show up in tags index
+
+mkdocs-material-9.1.21+insiders-4.39.0 (2023-08-01)
+
+  * Added support for hoisting theme media files when building projects
+  * Added support for sorting pages on tags index for tags plugin
+  * Added support for adding date of last update to blog posts
+  * Fixed #5797: Parse error in typeset plugin (4.38.1 regression)
+
 mkdocs-material-9.1.21+insiders-4.38.1 (2023-08-01)
 
   * Improved nested serve mode for projects plugin
@@ -330,7 +529,7 @@ mkdocs-material-9.0.8 (2023-01-29)
 mkdocs-material-9.0.7 (2023-01-28)
 
   * Improved accessibility of sidebar navigation
-  * Moved all translations into community edition
+  * Moved all translations into Community edition
   * Updated Polish and Portuguese (Brasilian) translations
   * Fixed info plugin terminating on subsequent reload when serving
   * Fixed #4910: Sidebar navigation labels have invalid ARIA roles

CODE_OF_CONDUCT.md

@@ -16,7 +16,7 @@ Examples of behavior that contributes to creating a positive environment include
 * Using welcoming and inclusive language
 * Being respectful of differing viewpoints and experiences
 * Gracefully accepting constructive criticism
-* Focusing on what is best for the community
+* Focusing on what is best for our community
 * Showing empathy towards other community members
 
 Examples of unacceptable behavior by participants include:
@@ -54,12 +54,12 @@ further defined and clarified by project maintainers.
 ## Enforcement
 
 Instances of abusive, harassing, or otherwise unacceptable behavior may be
-reported by contacting the project team at
+reported by contacting the project team privately at hello@squidfunk.com. The
-https://gitter.im/squidfunk/mkdocs-material. The project team will review and 
+project team will review and investigate all complaints, and will respond in a
-investigate all complaints, and will respond in a way that it deems appropriate
+way that it deems appropriate to the circumstances. The project team is
-to the circumstances. The project team is obligated to maintain confidentiality
+obligated to maintain confidentiality with regard to the reporter of an
-with regard to the reporter of an incident. Further details of specific
+incident. Further details of specific enforcement policies may be posted
-enforcement policies may be posted separately.
+separately.
 
 Project maintainers who do not follow or enforce the Code of Conduct in good
 faith may face temporary or permanent repercussions as determined by other

CONTRIBUTING.md

@@ -1,112 +1,61 @@
 # Contributing
 
-Interested in contributing to the Material for MkDocs? Have a question? Want to 
+Material for MkDocs is an actively maintained and constantly improved project
-report a bug? Before you do, please read the following guidelines.
+that serves a diverse user base with varying backgrounds and needs. In order to
+effectively address the needs of all our users, evaluate change requests, and
+fix bugs, we maintainers need to put in a lot of work. We have devoted
+significant effort to creating better templates for our issue tracker,
+optimizing the processes for our users to report bugs, request features or
+changes, contribute to the project, or exchange with our community.
 
-## Submission context
+Given the wealth of valuable knowledge contained in numerous issues and
-
+discussions, we consider our [issue tracker] and [discussion board] to serve as
-### Got a question or problem?
+a crucial __knowledge base__ that is an important addition to our [documentation]
-
+and brings value to both new and experienced users of Material for MkDocs.
-For quick questions there's no need to open an issue as you can reach us on
-[gitter.im].
-
-  [gitter.im]: https://gitter.im/squidfunk/mkdocs-material
-
-### Found a bug?
-
-If you found a bug in the source code, you can help us by submitting an issue
-to the [issue tracker] in our GitHub repository. Even better, you can submit
-a Pull Request with a fix. However, before doing so, please read the
-[submission guidelines].
 
+  [discussion board]: https://github.com/squidfunk/mkdocs-material/discussions
   [issue tracker]: https://github.com/squidfunk/mkdocs-material/issues
-  [submission guidelines]: #submission-guidelines
+  [documentation]: https://squidfunk.github.io/mkdocs-material/
 
-### Missing a feature?
+## How to contribute
 
-You can request a new feature by submitting an issue to our GitHub Repository.
+### Creating an issue
-If you would like to implement a new feature, please submit an issue with a
-proposal for your work first to be sure that it is of use to everyone, as
-Material for MkDocs is highly opinionated. Please consider what kind of change
-it is:
 
-* For a **major feature**, first open an issue and outline your proposal so
+-   #### [Report a bug]
-  that it can be discussed. This will also allow us to better coordinate our
-  efforts, prevent duplication of work, and help you to craft the change so
-  that it is successfully accepted into the project.
 
-* **Small features and bugs** can be crafted and directly submitted as a Pull
+    __Something is not working?__ Report a bug in Material for MkDocs by
-  Request. However, there is no guarantee that your feature will make it into
+    creating an issue with a reproduction
-  the `master`, as it's always a matter of opinion whether if benefits the
-  overall functionality of the project.
 
-### Missing translations?
+-   #### [Report a docs issue]
 
-Material for MkDocs supports 60+ languages with the help of community
+    __Missing information in our docs?__ Report missing information or
-contributions. When new features are added, sometimes, new translations are
+    potential inconsistencies in our documentation
-necessary as well. It's impossible for the maintainers of the project to update
-all translations (we just don't speak 60+ languages), so we have to rely on
-our contributors to update translations incrementally. This process is pretty
-simple, so if you find a translation missing in your language, follow these
-guidelines:
 
-1.  Fork the repository.
+-   #### [Request a change]
 
-2.  Open up the [translation file for your language] as well as the
+    __Want to submit an idea?__ Propose a change, feature request, or
-    [English translations], as they are always up-to-date. Compare them
+    suggest an improvement
-    side-by-side and add the missing translations. __Important__: only add the
-    translations that are different from the defaults, e.g. if your language
-    is left-to-right, don't add the `direction` translation, as English is
-    left-to-right as well. The following translations are for technical
-    purposes and should not be updated, so if they're missing from your
-    language, it's for good reason:
 
-    - `search.config.lang`
+-   #### [Ask a question]
-    - `search.config.pipeline`
-    - `search.config.separator`
 
-3.  Create a PR (see below) with your changes.
+    __Have a question or need help?__ Ask a question on our [discussion board]
+    and get in touch with our community
 
-  [translation file for your language]: https://github.com/squidfunk/mkdocs-material/tree/master/src/partials/languages
+### Contributing
-  [English translations]: https://github.com/squidfunk/mkdocs-material/tree/master/src/partials/languages/en.html
 
-## Submission guidelines
+-   #### [Add a translation]
 
-### Submitting an issue
+    __Missing support for your language?__ Add missing translations for a new
+    or already supported language
 
-Before you submit an issue, please search the issue tracker, maybe an issue for
+-   #### [Create a pull request]
-your problem already exists, and the discussion might inform you of workarounds
-readily available.
 
-We want to fix all the issues as soon as possible, but before fixing a bug, we
+    __Want to create a pull request?__ Learn how to create a comprehensive
-need to reproduce and confirm it. In order to reproduce bugs, we will
+    and useful pull request (PR)s
-systematically ask you to provide a minimal reproduction scenario using the
-custom issue template. Please stick to the issue template.
 
-Unfortunately, we are not able to investigate / fix bugs without a minimal
+  [Report a bug]: reporting-a-bug.md
-reproduction scenario, so if we don't hear back from you, we may close the issue.
+  [Report a docs issue]: reporting-a-docs-issue.md
-
+  [Request a change]: requesting-a-change.md
-### Submitting a Pull Request (PR)
+  [Ask a question]: https://github.com/squidfunk/mkdocs-material/discussions
-
+  [Add translations]: https://github.com/squidfunk/mkdocs-material/adding-translations
-Search GitHub for an open or closed PR that relates to your submission. You
+  [Create a pull request]: https://github.com/squidfunk/mkdocs-material/pulls
-don't want to duplicate effort. If you do not find a related issue or PR,
-go ahead.
-
-1.  **Development**: Fork the project, set up the [development environment],
-    make your changes in a separate git branch and add descriptive messages to
-    your commits.
-
-2.  **Build**: Before submitting a pull request, [build the theme]. This is
-    a mandatory requirement for your PR to get accepted, as the theme should be 
-    installable through GitHub at all times.
-
-3.  **Pull Request**: After building the theme, commit the compiled output,
-    push your branch to GitHub and send a PR to `mkdocs-material:master`. If we
-    suggest changes, make the required updates, rebase your branch and push the
-    changes to your GitHub repository, which will automatically update your PR.
-
-After your PR is merged, you can safely delete your branch and pull the changes
-from the main (upstream) repository.
-
-  [development environment]: https://squidfunk.github.io/mkdocs-material/customization/#environment-setup
-  [build the theme]: https://squidfunk.github.io/mkdocs-material/customization/#building-the-theme

Dockerfile

@@ -61,10 +61,8 @@ RUN \
 && \
   if [ "${WITH_PLUGINS}" = "true" ]; then \
     pip install --no-cache-dir \
-      "mkdocs-minify-plugin>=0.3" \
+      mkdocs-material[recommended] \
-      "mkdocs-redirects>=1.0" \
+      mkdocs-material[imaging]; \
-      "pillow>=9.0" \
-      "cairosvg>=2.5"; \
   fi \
 && \
   if [ -e user-requirements.txt ]; then \
@@ -76,7 +74,7 @@ RUN \
   for theme in mkdocs readthedocs; do \
     rm -rf ${PACKAGES}/mkdocs/themes/$theme; \
     ln -s \
-      ${PACKAGES}/material \
+      ${PACKAGES}/material/templates \
       ${PACKAGES}/mkdocs/themes/$theme; \
   done \
 && \

README.md

@@ -20,10 +20,6 @@
     src="https://img.shields.io/pypi/dm/mkdocs-material.svg"
     alt="Downloads"
   /></a>
-  <a href="https://gitter.im/squidfunk/mkdocs-material"><img 
-    src="https://badges.gitter.im/squidfunk/mkdocs-material.svg" 
-    alt="Chat on Gitter"
-  /></a>
   <a href="https://pypi.org/project/mkdocs-material"><img
     src="https://img.shields.io/pypi/v/mkdocs-material.svg"
     alt="Python Package Index"
@@ -123,9 +119,9 @@
   <a href="https://neptune.ai/" target=_blank><img
     src="https://raw.githubusercontent.com/squidfunk/mkdocs-material/master/.github/assets/sponsors/sponsor-neptune-ai.png" height="58"
   /></a>
-  <a href="https://cash.app/" target=_blank><img
+  <!-- <a href="https://cash.app/" target=_blank><img
     src="https://raw.githubusercontent.com/squidfunk/mkdocs-material/master/.github/assets/sponsors/sponsor-cashapp.png" height="58"
-  /></a>
+  /></a> -->
   <a href="https://rackn.com/" target=_blank><img
     src="https://raw.githubusercontent.com/squidfunk/mkdocs-material/master/.github/assets/sponsors/sponsor-rackn.png" height="58"
   /></a>
@@ -159,6 +155,12 @@
   <a href="https://oikolab.com/" target=_blank><img
     src="https://raw.githubusercontent.com/squidfunk/mkdocs-material/master/.github/assets/sponsors/sponsor-oikolab.png" height="58"
   /></a>
+  <a href="https://www.buhlergroup.com/" target=_blank><img
+    src="https://raw.githubusercontent.com/squidfunk/mkdocs-material/master/.github/assets/sponsors/sponsor-buhler.png" height="58"
+  /></a>
+  <a href="https://transformationflow.io/" target=_blank><img
+    src="https://raw.githubusercontent.com/squidfunk/mkdocs-material/master/.github/assets/sponsors/sponsor-transformationflow.png" height="58"
+  /></a>
 </p>
 <p>&nbsp;</p>
 
@@ -224,10 +226,12 @@ For detailed installation instructions, configuration options, and a demo, visit
 
 ### ... industry leaders
 
+[ArXiv](https://info.arxiv.org),
 [Atlassian](https://atlassian.github.io/data-center-helm-charts/),
 [AWS](https://aws.github.io/copilot-cli/),
 [Bloomberg](https://bloomberg.github.io/selekt/),
 [CERN](http://abpcomputing.web.cern.ch/),
+[CloudFlare](https://cloudflare.github.io/itty-router-openapi/),
 [Datadog](https://datadoghq.dev/integrations-core/),
 [Google](https://google.github.io/accompanist/),
 [Hewlett Packard](https://hewlettpackard.github.io/squest/),
@@ -238,14 +242,16 @@ For detailed installation instructions, configuration options, and a demo, visit
 [Microsoft](https://microsoft.github.io/code-with-engineering-playbook/),
 [Mozilla](https://mozillafoundation.github.io/engineering-handbook/),
 [Netflix](https://netflix.github.io/titus/),
+[Red Hat](https://ansible.readthedocs.io/projects/lint/),
 [Salesforce](https://policy-sentry.readthedocs.io/en/latest/),
-[SoundCloud](https://intervene.dev/),
+[Slack](https://slackhq.github.io/circuit/),
 [Square](https://square.github.io/okhttp/),
 [Zalando](https://opensource.zalando.com/skipper/)
 
 ### ... and successful Open Source projects
 
 [Arduino](https://arduino.github.io/arduino-cli/),
+[Auto-GPT](https://docs.agpt.co/),
 [AutoKeras](https://autokeras.com/),
 [BFE](https://www.bfe-networks.net/),
 [CentOS](https://docs.infra.centos.org/),
@@ -256,15 +262,15 @@ For detailed installation instructions, configuration options, and a demo, visit
 [Knative](https://knative.dev/docs/),
 [Kubernetes](https://kops.sigs.k8s.io/),
 [kSQL](https://docs.ksqldb.io/),
-[MindsDB](https://docs.mindsdb.com/),
 [Nokogiri](https://nokogiri.org/),
 [OpenFaaS](https://docs.openfaas.com/),
 [Percona](https://docs.percona.com/percona-monitoring-and-management/),
 [Pi-Hole](https://docs.pi-hole.net/),
 [Pydantic](https://pydantic-docs.helpmanual.io/),
+[PyPI](https://docs.pypi.org/),
 [Renovate](https://docs.renovatebot.com/),
 [Traefik](https://docs.traefik.io/),
-[Trivy](https://github.com/aquasecurity/trivy)
+[Trivy](https://aquasecurity.github.io/trivy/),
 [Vapor](https://docs.vapor.codes/),
 [ZeroNet](https://zeronet.io/docs/),
 [WebKit](https://docs.webkit.org/),

docs/blog/.authors.yml

@@ -1,4 +1,5 @@
-squidfunk:
+authors:
-  name: Martin Donath
+  squidfunk:
-  description: Creator
+    name: Martin Donath
-  avatar: https://avatars.githubusercontent.com/u/932156
+    description: Creator
+    avatar: https://avatars.githubusercontent.com/u/932156

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

@@ -8,7 +8,7 @@ categories:
   - Blog
 links:
   - Getting started with Insiders: insiders/getting-started.md#requirements
-  - setup/setting-up-a-blog.md#built-in-blog-plugin
+  - plugins/blog.md
 ---
 
 # Blog support just landed
@@ -31,7 +31,7 @@ _This article explains how to build a standalone blog with Material for MkDocs.
 If you want to build a blog alongside your documentation, please refer to
 [the plugin's documentation][built-in blog plugin]._
 
-  [built-in blog plugin]: ../../setup/setting-up-a-blog.md#built-in-blog-plugin
+  [built-in blog plugin]: ../../plugins/blog.md
   [Jekyll]: https://jekyllrb.com/
 
 ## Quick start

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

@@ -9,7 +9,7 @@ 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
 ---
 
@@ -35,7 +35,7 @@ _This article explains how to set up Chinese language support for the built-in
 search plugin in a few minutes._
 { style="display: inline" }
 
-  [built-in search plugin]: ../../setup/setting-up-site-search.md#built-in-search-plugin
+  [built-in search plugin]: ../../plugins/search.md
   [lunr-languages]: https://github.com/MihaiValentin/lunr-languages
 
 ## Configuration

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

@@ -9,7 +9,7 @@ categories:
   - Search
   - Performance
 links:
-  - setup/setting-up-site-search.md#built-in-search-plugin
+  - plugins/search.md
   - insiders/index.md#how-to-become-a-sponsor
 ---
 
@@ -58,7 +58,7 @@ const index$ = document.forms.namedItem("search")
 
   [lunr]: https://lunrjs.com
   [lunr-languages]: https://github.com/MihaiValentin/lunr-languages
-  [built-in search plugin]: ../../setup/setting-up-site-search.md#built-in-search-plugin
+  [built-in search plugin]: ../../plugins/search.md
 
 ### Search index
 
@@ -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.
@@ -262,7 +262,7 @@ carefully considered:
     China and Japan are both within the top 5 countries of origin of users of
     Material for MkDocs.
 
-  [truncated]: https://github.com/squidfunk/mkdocs-material/blob/master/src/assets/javascripts/templates/search/index.tsx#L90
+  [truncated]: https://github.com/squidfunk/mkdocs-material/blob/master/src/templates/assets/javascripts/templates/search/index.tsx#L90
   [search preview]: search-better-faster-smaller/search-preview.png
   [Just the Docs]: https://pmarsceill.github.io/just-the-docs/
   [Docusaurus]: https://github.com/lelouch77/docusaurus-lunr-search

docs/browser-support.md

@@ -47,6 +47,8 @@ check the distribution of browser types and versions among your users.
   [open an issue]: https://github.com/squidfunk/mkdocs-material/issues/new/choose
   [caniuse.com]: https://caniuse.com/
   [:is pseudo selector]: https://caniuse.com/css-matches-pseudo
+  [browser support]: #supported-browsers
+  [built-in privacy plugin]: plugins/privacy.md
 
 ## Other browsers
 
@@ -62,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/changelog/index.md

@@ -2,7 +2,143 @@
 
 ## Material for MkDocs
 
-### 9.1.21 <small>July 27, 2023</small> { id="9.1.20" }
+### 9.4.1 <small>September 22, 2023</small> { id="9.4.1" }
+
+- Improved colors and contrast in dark mode
+- Improved admonition borders to match font weight
+- Switched content tabs to neutral color
+
+### 9.4.0 <small>September 21, 2023</small> { id="9.4.0" }
+
+- Added Belarusian translations
+- Added version info to entrypoint of package
+- Added emoji extension as a replacement for `materialx`
+- Improved slate color scheme (dark mode) - now even darker
+- Restructured project to improve development experience
+- Updated MkDocs to 1.5.3
+- Fixed #3890: Development mode crash on Linux
+
+### 9.3.2 <small>September 19, 2023</small> { id="9.3.2" }
+
+- Updated Slovenian translations
+- Updated Python dependencies in requirements to use minimum versions
+- Fixed #6017: Code highlighting inconsistent in Community and Insiders edition
+- Fixed #6001: Contributor avatars display incorrectly in Firefox
+- Fixed #6000: Blog post drafts are included in navigation
+
+### 9.3.1 <small>September 11, 2023</small> { id="9.3.1" }
+
+- Fixed crash of group plugin when used together with hooks
+
+### 9.3.0 <small>September 11, 2023</small> { id="9.3.0" }
+
+- Improved configuration sharing between Community and Insiders edition
+- Added experimental built-in group plugin for enabling plugins conditionally
+- Added new settings in tags plugin for enabling/disabling
+- Dropped support for Python 3.7 (EOL)
+
+### 9.2.8 <small>September 4, 2023</small> { id="9.2.8" }
+
+- Updated Italian and Russian translations
+- Fixed #5952: Combining blog and tags plugin leads to wrong links
+- Fixed #5951: Blog plugin ignores post title in metadata
+- Fixed #5949: Blog plugin ignores post linked in nav
+
+### 9.2.7 <small>September 2, 2023</small> { id="9.2.7" }
+
+- Switched dependencies to compatible release clauses
+- Removed `readtime` and `lxml` dependencies for blog plugin
+- Reduced size of Docker image to improve CI build performance
+- Fixed #5945: Incorrect footer navigation for sibling pages of blog
+- Fixed #5939: Page jumps when changing color palette (Firefox 117)
+- Fixed #5901: Announcement bar reappears when using instant loading
+- Fixed #5824: Allow to customize styles of sequence diagrams
+
+### 9.2.6 <small>August 31, 2023</small> { id="9.2.6" }
+
+- Added Basque translations
+- Added template for simple redirects
+- Improved blog plugin interop by moving view generation to `on_files`
+- Fixed #5924: Social plugin still checks dependencies when disabled
+- Fixed #5916: Blog plugin crashes on Python 3.8 (9.2.0 regression)
+
+### 9.2.5 <small>August 27, 2023</small> { id="9.2.5" }
+
+- Fixed error in dirty serve mode when using blog plugin
+- Fixed page title not being consistent in blog plugin pagination
+- Fixed #5899: Blog plugin pagination breaks when disabling directory URLs
+
+### 9.2.4 <small>August 26, 2023</small> { id="9.2.4" }
+
+- Added version to bug report name in info plugin
+- Updated Afrikaans translations
+
+### 9.2.3 <small>August 22, 2023</small> { id="9.2.3" }
+
+- Fixed blog plugin rendering wrongly with `markdown.extensions.toc`
+- Fixed blog plugin entrypoint generation
+
+### 9.2.2 <small>August 22, 2023</small> { id="9.2.2" }
+
+- Fixed #5880: Blog plugin failing when building a standalone blog
+- Fixed #5881: Blog plugin not compatible with Python < 3.10
+
+### 9.2.1 <small>August 21, 2023</small> { id="9.2.1" }
+
+- Fixed #5879: Blog plugin failing when building a standalone blog
+- Fixed error in blog plugin when using draft tagging on future date
+- Fixed error in blog plugin when toc extension is not enabled
+
+### 9.2.0 <small>August 21, 2023</small> { id="9.2.0" }
+
+__Additions and improvements__
+
+- Added blogging support via built-in blog plugin
+- Added support for Chinese language segmentaiton in search plugin
+- Added support for adding custom dates to blog posts
+- Added support for paginating archive and category pages
+- Added support for annotations (outside of code blocks)
+- Added support for navigation icons
+- Added support for navigation pruning
+- Added support for navigation status
+- Added support for customizing site icons
+- Added support for customizing (code) annotation icons
+- Added focus outline to admonitions and details
+- Added prompt for bug report name to info plugin
+- Added Luxembourgish translations
+- Improved rendering of (code) annotation markers
+- Improved print styles for (code) annotations
+- Improved customizability of navigation tabs
+- Improved interop of plugins with external tools like mike
+- Improved interop of blog plugin with awesome pages plugin
+- Improved header partial by moving buttons into separate partials
+- Improved clarity of `site_url` warning in social plugin
+- Improved blog plugin to automatically setup directory structure
+- Switched info plugin to `importlib` to mitigate deprecations
+- Automatically download ResizeObserver polyfill when necessary
+- Automatically add iframe-worker polyfill when necessary in offline plugin
+- Automatically focus and bring up keyboard on touch devices
+- Updated Serbo-Croatian translations
+- Updated MkDocs to 1.5.2
+
+__Removals__
+
+- Removed Universal Analytics integration
+- Removed ancient polyfills to reduce size of bundled JavaScript by 20%
+- Removed necessity for `Array.flat` and `Array.flatMap` polyfill
+- Removed announcement bar button when JavaScript is not available
+
+__Fixes__
+
+- Fixed rendering of tags when announcement bar is present
+- Fixed tags plugin rendering pages excluded by other plugins
+- Fixed #5132: Blog plugin requires `nav` entry in `mkdocs.yml`
+- Fixed #5599: Insufficient contrast for default link color
+- Fixed #5715: Blog plugin missing integrated table of contents in pagination
+- Fixed #5806: Version selector not hoverable on some Android devices
+- Fixed #5826: Blog post drafts with tags show up in tags index
+
+### 9.1.21 <small>July 27, 2023</small> { id="9.1.21" }
 
 - Fixed MkDocs 1.4 compat issue in social plugin (9.1.20 regression)
 
@@ -188,7 +324,7 @@
 ### 9.0.7 <small>January 28, 2023</small> { id="9.0.7" }
 
 - Improved accessibility of sidebar navigation
-- Moved all translations into community edition
+- Moved all translations into Community edition
 - Updated Polish and Portuguese (Brasilian) translations
 - Fixed info plugin terminating on subsequent reload when serving
 - Fixed #4910: Sidebar navigation labels have invalid ARIA roles

docs/contributing/adding-translations.md

@@ -0,0 +1,125 @@
+# Translations
+
+It's unbelievable – with the help of international community contributions,
+Material for MkDocs has been translated into 60+ languages. As you can imagine,
+it's impossible for us maintainers to keep all languages up-to-date, and new
+features sometimes require new translations.
+
+If you would like to help us to make Material for MkDocs even more globally
+accessible and have noticed a missing translation in your language, or would
+like to add a new language, you can help us by following the steps of the guide
+below.
+
+## Before creating an issue
+
+Translations change frequently, which is why we want to make sure that you don't
+invest your time in duplicating work. Before adding translations, please check
+the following things:
+
+### Check language availability
+
+With more than 60 languages, the chances are good that your language is already
+supported by Material for MkDocs. You can check if your language is available,
+or needs improvements or additional translations by inspecting the list of
+[supported languages]:
+
+- __Your language is already supported__ – in this case, you can check if there
+  are translations missing, and click the link underneath your language to add them, which takes 5 minutes.
+
+- __Your language is missing__ – in that case, you can help us add support
+  for your language to Material for MkDocs! Read on, to learn how to do this.
+
+  [supported languages]: ../setup/changing-the-language.md#site-language
+
+### Search our issue tracker
+
+Another user might have already created an issue supplying the missing
+translations for your language that still needs to be integrated by us
+maintainers. To avoid investing your time in duplicated work, please search the
+[issue tracker] beforehand.
+
+  [issue tracker]: https://github.com/squidfunk/mkdocs-material/issues
+
+---
+
+At this point, when you have made sure that Material for MkDocs doesn't already
+support your language, you can add new translations for it by following the
+issue template.
+
+## Issue template
+
+We have created an issue template that makes contributing translations as simple
+as possible. It is the result of our experience with 60+ language contributions
+and updates over the last couple of years, and consists of the following parts:
+
+- [Title]
+- [Translations]
+- [Country flag] <small>optional</small>
+- [Checklist]
+
+  [Title]: #title
+  [Translations]: #translations
+  [Country flag]: #country-flag
+  [Checklist]: #checklist
+
+### Title
+
+When you update an already existing language, you can just leave the title as it
+is. Adding support for a new language, replace the `...` in the pre-filled title
+with the name of your language.
+
+| <!-- --> | Example  |
+| -------- | -------- |
+| :material-check:{ style="color: #4DB6AC" } __Clear__ | Add translations for German
+| :material-close:{ style="color: #EF5350" } __Unclear__ | Add translations ...
+| :material-close:{ style="color: #EF5350" } __Useless__ | Help
+
+### Translations
+
+If a translation contains an :arrow_left: icon on the right side, it is missing.
+You can translate this line and remove the :arrow_left: icon. If you don't know
+how to translate specific lines, simply leave them for other contributors to
+complete. To ensure the accuracy of your translation, consider double-checking the
+context of the words by looking at our [English translations].
+
+[English translations]: https://github.com/squidfunk/mkdocs-material/tree/master/src/partials/languages/en.html
+
+### Country flag <small>optional</small> { #country-flag }
+
+For a better overview, our list of [supported languages] includes country flags
+next to the language names. You can help us select a flag for your language by
+adding the shortcode for the country flag to this field. Go to our
+[emoji search] and enter `flag` to find all available shortcodes.
+
+!!! question "What if my flag is not available?"
+
+    [Twemoji] provides flag emojis for 260 countries – subdivisions of countries,
+    such as states, provinces, or regions, are not supported. If you're adding
+    translations for a subdivision, please choose the most appropriate available
+    flag.
+
+  [Twemoji]: https://twemoji.twitter.com/
+  [emoji search]: ../reference/icons-emojis.md#search
+
+> __Why this might be helpful__: adding a country flag next to the country name
+> can be helpful for you and for others to find the language in the list of
+> supported languages faster and easier. If your country's flag is not supported
+> by [Twemoji], you can help us choose an alternative.
+
+### Checklist
+
+Thanks for following the guide and helping us to add new translations to Material
+for MkDocs – you are almost done. The checklist ensures that you have read this
+guide and have worked to your best knowledge to provide us with everything we need
+to integrate your contribution.
+
+__We'll take it from here.__
+
+---
+
+## Attribution
+
+If you submit a translation using the template above, you will be __credited as
+a co-author__ in the commit, so you don't need to open a pull request. You have
+done a significant contribution to the project, making Material for MkDocs
+accessible to more people around the world. Thank you!

docs/contributing/index.md

@@ -1,58 +1,202 @@
 # Contributing
 
-Material for MkDocs is an actively maintained and constantly improved project 
+Material for MkDocs is an actively maintained and constantly evolving project
-that caters to a diverse user base with varying backgrounds and needs. In order
+serving a diverse user base with versatile backgrounds and needs. In order to
-to effectively address the needs of all our users, evaluate requests, and fix 
+efficiently address the requirements of all our users, evaluate change requests,
-bugs, a lot of work from us maintainers is required.
+and fix bugs, we put in a lot of work.
 
-## How to contribute
+Our ever-growing community includes many active users, who open new
-
+issues and discussions several times a day, evolving our [issue tracker] and
-We have invested quite a lot of time in creating better templates for our
+[discussion board] into a knowledge base – an important addition to
-[issue tracker], optimizing the processes for our users to report bugs, request
+our [documentation] – yielding value to both new and experienced users.
-features or changes, contribute to the project, or exchange with our community. 
-This section of the documentation explains each process.
 
+  [discussion board]: https://github.com/squidfunk/mkdocs-material/discussions
   [issue tracker]: https://github.com/squidfunk/mkdocs-material/issues
+  [documentation]: https://squidfunk.github.io/mkdocs-material/
+
+## How you can contribute
+
+We understand that reporting bugs, raising change requests, as well as engaging
+in discussions can be time-consuming, which is why we've carefully optimized our
+issue templates and defined guidelines to improve the overall interaction
+within the project. We've invested a lot of time and effort into making our
+[issue tracker] and [discussion board] as efficient as possible.
+
+Our goal is to ensure that our documentation, as well as issue tracker and
+discussion board, are __well-structured__, __easy to navigate__, and
+__searchable__, so you can find what you need quickly and efficiently. Thus,
+when you follow our guidelines, we can help you much faster.
+
+In this section, we guide your through our processes.
 
 ### Creating an issue
 
 <div class="grid cards" markdown>
 
--   :material-bug:{ .lg .middle } __Something is not working?__
+-   :material-bug-outline: &nbsp;
+    __Something is not working?__
 
     ---
 
-    Report a bug in Material for MkDocs by creating an issue and a reproduction
+    Report a bug in Material for MkDocs by creating an issue with a
+    reproduction
+
+    ---
 
     [:octicons-arrow-right-24: Report a bug][report a bug]
 
--   :material-file-document:{ .lg .middle } __Missing information in our docs?__
+-   :material-file-document-remove-outline: &nbsp;
+    __Missing information in our docs?__
 
     ---
 
-    Report missing information or potential inconsistencies in our documentation
+    Report missing information or potential inconsistencies in our
+    documentation
+
+    ---
 
     [:octicons-arrow-right-24: Report a docs issue][report a docs issue]
 
--   :material-lightbulb-on:{ .lg .middle } __Want to submit an idea?__
+-   :material-lightbulb-on-20: &nbsp;
+    __Want to submit an idea?__
 
     ---
 
-    Propose a change or feature request or suggest an improvement
+    Propose a change, feature request, or suggest an improvement
+
+    ---
 
     [:octicons-arrow-right-24: Request a change][request a change]
 
--   :material-chat-question:{ .lg .middle } __Have a question or need help?__
+-   :material-account-question-outline: &nbsp;
+    __Have a question or need help?__
 
     ---
 
-    Ask questions on our discussion board and get in touch with our community
+    Ask a question on our [discussion board] and get in touch with our
+    community
 
-    [:octicons-arrow-right-24: Ask a question][ask a question]
+    ---
+
+    [:octicons-arrow-right-24: Ask a question][discussion board]
+
+</div>
+
+### Contributing
+
+<div class="grid cards" markdown>
+
+-   :material-translate: &nbsp;
+    __Missing support for your language?__
+
+    ---
+
+    Add or improve translations for a new or already supported language
+
+    ---
+
+    [:octicons-arrow-right-24: Add translations][add translations]
+
+-   :material-source-pull: &nbsp;
+    __Want to create a pull request?__
+
+    ---
+
+    Learn how to create a comprehensive and useful pull request (PR)
+
+    ---
+
+    [:octicons-arrow-right-24: Create a pull request][create a pull request]
 
 </div>
 
   [report a bug]: reporting-a-bug.md
   [report a docs issue]: reporting-a-docs-issue.md
   [request a change]: requesting-a-change.md
-  [ask a question]: https://github.com/squidfunk/mkdocs-material/discussions
+  [add translations]: https://github.com/squidfunk/mkdocs-material/adding-translations
+  [create a pull request]: https://github.com/squidfunk/mkdocs-material/pulls
+
+## Checklist
+
+Before interacting within the project, please take a moment to consider the
+following questions. By doing so, you can ensure that you are using the correct
+issue template and that you provide all necessary information when interacting
+with our community.
+
+!!! warning "Issues, discussions, and comments are forever"
+
+    Please note that everything you write is permanent and will remain
+    for everyone to read – forever. Therefore, please always be nice and
+    constructive, follow our contribution guidelines, and comply with our
+    [Code of Conduct].
+
+### Before creating an issue
+
+- Are you using the appropriate issue template, or is there another issue
+  template that better fits the context of your request?
+
+- Have you checked if a similar bug report or change request has already been
+  created, or have you stumbled upon something that might be related?
+
+- Did your fill out every field as requested and did you provide all additional
+  information we maintainers need to comprehend your request?
+
+### Before asking a question
+
+- Is the topic a question for our [discussion board], or is it a bug report or
+  change request that should better be raised on our [issue tracker]?
+
+- Is there an open discussion on the topic of your request? If the answer is yes,
+  does your question match the direction of the discussion, or should you open a
+  new discussion?
+
+- Did your provide our community with all the necessary information to
+  understand your question and help you quickly, or can you make it easier to
+  help you?
+
+### Before commenting
+
+- Is your comment relevant to the topic of the current page, post, issue, or
+  discussion, or is it a better idea to create a new issue or discussion?
+
+- Does your comment add value to the conversation? Is it constructive and
+  respectful to our community and us maintainers? Could you just use a
+  [:octicons-smiley-16: reaction][reaction] instead?
+
+  [Code of Conduct]: https://github.com/squidfunk/mkdocs-material/blob/master/CODE_OF_CONDUCT.md
+  [reaction]: https://github.blog/2016-03-10-add-reactions-to-pull-requests-issues-and-comments/
+
+## Rights and responsibilities
+
+As maintainers, we reserve the right and have the responsibility to close,
+remove, reject, or edit contributions, such as issues, discussions, comments,
+or commits, that do not align with our contribution guidelines and our
+[Code of Conduct].
+
+### Incomplete issues
+
+We have invested significant time in reviewing our contribution process and
+carefully assessed the essential requirements when reviewing and responding to
+issues. Each field in our issue templates has been thoughtfully curated, helping
+us to understand your matter.
+
+__Therefore, it is mandatory to fill out every field as requested__ to the best
+of your knowledge. We need all of this information because it ensures that every
+user and maintainer, regardless of their experience, can understand the content
+and severity of your bug report or change request.
+
+__We reserve the right to close issues missing essential information__, such as
+but not limited to [minimal reproductions], or that do not comply with the
+quality standards and requirements stated in our issue templates. Issues
+can be reopened once the missing information has been provided.
+
+  [minimal reproductions]: ../guides/creating-a-reproduction.md
+
+### Code of Conduct
+
+As stated in our [Code of Conduct], we expect all members of our community to
+treat each other with respect, and use inclusive and welcoming language. We
+always strive to create a positive and supportive environment and do not accept
+inappropriate, offensive, or harmful behavior.
+
+We take violations seriously and will take appropriate action in response.

docs/contributing/reporting-a-bug.md

@@ -1,9 +1,9 @@
-# Reporting a bug
+# Bug reports
 
 Material for MkDocs is an actively maintained project that we constantly strive
 to improve. With a project of this size and complexity, bugs may occur. If you
 think you have discovered a bug, you can help us by submitting an issue in our
-public [issue tracker] by following this guide.
+public [issue tracker], following this guide.
 
   [issue tracker]: https://github.com/squidfunk/mkdocs-material/issues
 
@@ -14,7 +14,7 @@ of this project are trying very hard to keep the number of open issues down by
 fixing bugs as fast as possible. By following this guide, you will know exactly
 what information we need to help you quickly.
 
-__But first, please try the following things before creating an issue.__
+__But first, please do the following things before creating an issue.__
 
 ### Upgrade to latest version
 
@@ -37,7 +37,7 @@ We can't offer official support for bugs that might hide in your overrides, so
 make sure to omit the following settings from `mkdocs.yml`:
 
   - [`theme.custom_dir`][theme.custom_dir]
-  - [`theme.hooks`][theme.hooks]
+  - [`hooks`][hooks]
   - [`extra_css`][extra_css]
   - [`extra_javascript`][extra_javascript]
 
@@ -63,10 +63,10 @@ problems.__
   [JavaScript]: ../customization.md#additional-javascript
   [theme extension]: ../customization.md#extending-the-theme
   [theme.custom_dir]: https://www.mkdocs.org/user-guide/configuration/#custom_dir
-  [theme.hooks]: https://www.mkdocs.org/user-guide/configuration/#hooks
+  [hooks]: https://www.mkdocs.org/user-guide/configuration/#hooks
   [extra_css]: https://www.mkdocs.org/user-guide/configuration/#extra_css
   [extra_javascript]: https://www.mkdocs.org/user-guide/configuration/#extra_javascript
-  [discussion board]: https://github.com/squidfunk/mkdocs-material/discussions
+  [discussion board]: https://github.com/squidfunk/mkdocs-material/issues
   [StackOverflow]: https://stackoverflow.com
   [that our documentation explicitly mentions]: ?q="extends+base"
 
@@ -104,7 +104,7 @@ them in the bug report.__[^2]
 
   [^2]:
     We might be using terminology in our documentation different from yours,
-    but mean the same. When you include the search terms and related links
+    but we mean the same. When you include the search terms and related links
     in your bug report, you help us to adjust and improve the documentation.
 
 ---
@@ -119,13 +119,13 @@ how to create a complete and helpful bug report.
 ## Issue template
 
 We have created a new issue template to make the bug reporting process as simple
-as possible and more efficient for the community and us. It is the result of
+as possible and more efficient for our community and us. It is the result of
 our experience answering and fixing more than 1,600 issues (and counting) and
 consists of the following parts:
 
 - [Title]
 - [Context] <small>optional</small>
-- [Description]
+- [Bug description]
 - [Related links]
 - [Reproduction]
 - [Steps to reproduce]
@@ -134,7 +134,7 @@ consists of the following parts:
 
   [Title]: #title
   [Context]: #context
-  [Description]: #description
+  [Bug description]: #bug-description
   [Related links]: #related-links
   [Reproduction]: #reproduction
   [Steps to reproduce]: #steps-to-reproduce
@@ -152,12 +152,12 @@ can be inferred from the title.
 | :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
-| :material-close:{ style="color: #EF5350" } __Generic__ | Please help
+| :material-close:{ style="color: #EF5350" } __Useless__ | Help
 
 ### Context <small>optional</small> { #context }
 
 Before describing the bug, you can provide additional context for us to
-understand what you are trying to achieve. Explain the circumstances
+understand what you were trying to achieve. Explain the circumstances
 in which you're using Material for MkDocs, and what you _think_ might be
 relevant. Don't write about the bug here.
 
@@ -165,7 +165,7 @@ relevant. Don't write about the bug here.
 > environments or edge cases, for example, when your documentation contains
 > thousands of documents.
 
-### Description
+### Bug description
 
 Now, to the bug you want to report. Provide a clear, focused, specific, and
 concise summary of the bug you encountered. Explain why you think this is a bug
@@ -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 }
+[:material-bug: Create 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
@@ -256,7 +256,7 @@ automatically upload it to GitHub.
 
     While we know that it is a good practice among developers to include a link
     to a repository with the bug report, we currently don't support those in our
-    process. The reason is that the reproduction which is automatically
+    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.
 
@@ -264,16 +264,16 @@ automatically upload it to GitHub.
     have trouble creating repositories.
 
   [Create reproduction]: ../guides/creating-a-reproduction.md
-  [built-in info plugin]: ../guides/creating-a-reproduction.md#creating-a-zip-file
+  [built-in info plugin]: ../plugins/info.md
 
 ### Steps to reproduce
 
-At this point, you provided us with enough information to understand the bug,
+At this point, you provided us with enough information to understand the bug
-and you gave us a reproduction that we could run and inspect. However, when we
+and provided us with a reproduction that we could run and inspect. However, when
-run your reproduction, it might not be immediately apparent how we can see
+we run your reproduction, it might not be immediately apparent how we can see
 the bug in action.
 
-Next, please list the specific steps we should follow when running your
+Thus, please list the specific steps we should follow when running your
 reproduction to observe the bug. Keep the steps short and concise, and make sure
 not to leave anything out. Use simple language as you would explain it to a
 five-year-old, and focus on continuity.
@@ -284,11 +284,17 @@ five-year-old, and focus on continuity.
 
 ### Browser <small>optional</small> { #browser }
 
-If you're reporting a bug that only happens in one or more _specific_ browsers,
+If you're reporting a bug that only occurs in one or more _specific_ browsers,
 we need to know which browsers are affected. This field is optional, as it is
 only relevant when the bug you are reporting does not involve a crash when
 [previewing] or [building] your site.
 
+---
+
+:material-incognito: __Incognito mode__ – Please verify that a the bug is
+not caused by a browser extension. Switch to incognito mode and try to reproduce
+the bug. If it's gone, it's caused by an extension.
+
 > __Why we need this__: some bugs only occur in specific browsers or versions.
 > Since now, almost all browsers are evergreen, we usually don't need to know the
 > version in which it occurs, but we might ask for it later. When in doubt, add
@@ -300,15 +306,8 @@ only relevant when the bug you are reporting does not involve a crash when
 ### Checklist
 
 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
+report – you are almost done. The checklist 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 your best knowledge to provide us with everything we need to
-need to know to help you.
+know to help you.
 
 __We'll take it from here.__
-
-## Incomplete issues
-
-Please understand that we reserve the right to close incomplete issues which
-do not contain minimal reproductions or do not adhere to the quality standards
-and requirements mentioned in this document. Issues can be reopened when the
-missing information has been provided.

docs/contributing/reporting-a-docs-issue.md

@@ -1,18 +1,18 @@
-# Reporting a docs issue
+# Documentation issues
 
-In the past seven years, our documentation has grown to more than 60 pages. With
+Our documentation is composed of more than 80 pages and includes extensive
-a site being this large, inconsistencies can occur. If you find an inconsistency
+information on features, configurations, customizations, and much more. If you
-or see room for clarification or improvement, please submit an issue to
+have found an inconsistency or see room for improvement, please follow this
-our public [issue tracker] by following this guide.
+guide to submit an issue on our [issue tracker].
 
   [issue tracker]: https://github.com/squidfunk/mkdocs-material/issues
 
 ## Issue template
 
 Reporting a documentation issue is usually less involved than reporting a bug,
-as we don't need a [reproduction]. Please thoroughly read the following guide
+as we don't need a [reproduction]. Please thoroughly read this guide before
-before creating a new documentation issue, and provide the following information
+creating a new documentation issue, and provide the following information as
-as part of the issue:
+part of the issue:
 
 - [Title]
 - [Description]
@@ -31,13 +31,13 @@ as part of the issue:
 
 A good title should be a short, one-sentence description of the issue, contain
 all relevant information and, in particular, keywords to simplify the search in
-the issue tracker.
+our issue tracker.
 
 | <!-- --> | Example  |
 | -------- | -------- |
 | :material-check:{ style="color: #4DB6AC" } __Clear__ | Clarify social cards setup on Windows
 | :material-close:{ style="color: #EF5350" } __Unclear__ | Missing information in the docs
-| :material-close:{ style="color: #EF5350" } __Generic__ | Please help
+| :material-close:{ style="color: #EF5350" } __Useless__ | Help
 
 ### Description
 
@@ -47,15 +47,16 @@ improvement. Explain why you think the documentation should be adjusted and
 describe the severity of the issue:
 
 -   __Keep it short and concise__ – if the inconsistency or issue can be
-    precisely explained in one or two sentences, perfect. Maintainers and
+    precisely explained in one or two sentences, perfect. Maintainers and future
-    future users will be grateful for having to read less.
+    users will be grateful for having to read less.
 
 -   __One issue at a time__ – if you encounter several unrelated inconsistencies,
-    please create separate issues for them. Don't report them in the same issue – it makes attribution difficult.
+    please create separate issues for them. Don't report them in the same issue
+    – it makes attribution difficult.
 
-> __Why we need this__: in order for us to understand the problem, we need a
+> __Why we need this__: describing the problem clearly and concisely is a
-> clear description of it and quantify its impact, which is essential for triage
+> prerequisite for improving our documentation – we need to understand what's
-> and prioritization.
+> wrong, so we can fix it.
 
 ### Related links
 
@@ -68,6 +69,7 @@ where possible, as it simplifies discovery.
 > understand which sections of our documentation need to be adjusted, extended,
 > or overhauled.
 
+
 ### Proposed change <small>optional</small> { #proposed-change }
 
 Now that you have provided us with the description and links to the
@@ -75,15 +77,15 @@ documentation sections, you can help us, maintainers, and the community by
 proposing an improvement. You can sketch out rough ideas or write a concrete
 proposal. This field is optional but very helpful.
 
-> __Why we need this__: improvement proposal can be beneficial for other users 
+> __Why we need this__: an improvement proposal can be beneficial for other
-> who encounter the same issue, as they offer solutions before we maintainers
+> users who encounter the same issue, as they offer solutions before we
-> can update the documentation.
+> maintainers can update the documentation.
 
 ### Checklist
 
-Thanks for following the guide and creating a high-quality and complete issue 
+Thanks for following the guide and providing valuable feedback for our
-report – you are almost done. This section ensures that you have read this guide
+documentation – you are almost done. The checklist ensures that you have read
-and have worked to the best of your knowledge to provide us with every piece of
+this guide and have worked to your best knowledge to provide us with every piece
-information we need to improve our documentation.
+of information we need to improve it.
 
 __We'll take it from here.__

docs/contributing/requesting-a-change.md

@@ -1,9 +1,9 @@
-# Requesting a change
+# Change requests
 
 Material for MkDocs is a powerful tool for creating beautiful and functional
-project documentation. With more than 20,000 users, we understand that our
+documentation. With more than 20,000 users, we understand that our project
-project serves a wide range of use cases, which is why we have created the
+serves a wide range of use cases, which is why we have created the following
-following guide.
+guide.
 
 ---
 
@@ -12,7 +12,7 @@ to maintain existing functionality while constantly adding new features at the
 same time. We highly value every idea or contribution from our community, and
 we kindly ask you to take the time to read the following guidelines before
 submitting your change request in our public [issue tracker]. This will help us
-better understand the proposed change and how it will benefit the community.
+better understand the proposed change and how it will benefit our community.
 
 This guide is our best effort to explain the criteria and reasoning behind our
 decisions when evaluating change requests and considering them for
@@ -27,39 +27,46 @@ ask you to do some preliminary work by answering some questions to determine if
 your idea is a good fit for Material for MkDocs and matches the project's
 [philosophy] and tone.
 
-__Please find answers to the following questions before creating an issue.__
+__Please do the following things before creating an issue.__
 
   [philosophy]: ../philosophy.md
 
 ### It's not a bug, it's a feature
 
 Change requests are intended to suggest minor adjustments, ideas for new
-features, or to influence the project's direction and vision. It is important
+features, or to kindly influence the project's direction and vision. It is
-to note that change requests are not intended for reporting bugs, as they're
+important to note that change requests are not intended for reporting bugs, as
-missing essential information for debugging.
+they're missing essential information for debugging.
 
 If you want to report a bug, please refer to our [bug reporting guide] instead.
 
   [bug reporting guide]: reporting-a-bug.md
 
-### Source of inspiration
+### Look for sources of inspiration
 
 If you have seen your idea implemented in another static site generator or
 theme, make sure to collect enough information on its implementation before
 submitting, as this allows us to evaluate potential fit more quickly. Explain
 what you like and dislike about the implementation.
 
-### Benefit for the community
+### Connect with our community
 
 Our [discussion board] is the best place to connect with our community. When
 evaluating new ideas, it's essential to seek input from other users and consider
 alternative viewpoints. This approach helps to implement new features in a way
 that benefits a large number of users.
 
-[:octicons-comment-discussion-16:  Start a discussion][Start a discussion]{ .md-button .md-button--primary }
+__Keep track of all <u>search terms</u> and <u>relevant links</u>, you'll need
+them in the change request.__[^1]
+
+  [^1]:
+    We might be using terminology in our documentation different from yours,
+    but we mean the same. When you include the search terms and related links
+    in your change request, you help us to adjust and improve the documentation.
+
+[:octicons-comment-discussion-16:&nbsp; Start a discussion][discussion board]{ .md-button .md-button--primary }
 
   [discussion board]: https://github.com/squidfunk/mkdocs-material/discussions
-  [Start a discussion]: https://github.com/squidfunk/mkdocs-material/discussions
 
 ## Issue template
 
@@ -87,7 +94,7 @@ help you submit a comprehensive and useful issue:
 ### Title
 
 A good title is short and descriptive. It should be a one-sentence executive
-summary of the idea, so the potential impact and benefit for the community can 
+summary of the idea, so the potential impact and benefit for our community can
 be inferred from the title.
 
 | <!-- --> | Example  |
@@ -95,7 +102,7 @@ be inferred from the title.
 | :material-check:{ style="color: #4DB6AC" } __Clear__ | Index custom front matter in search
 | :material-close:{ style="color: #EF5350" } __Wordy__ | Add a feature where authors can define custom front matter to be indexed in search
 | :material-close:{ style="color: #EF5350" } __Unclear__ | Improve search
-| :material-close:{ style="color: #EF5350" } __Generic__ | Please help
+| :material-close:{ style="color: #EF5350" } __Useless__ | Help
 
 ### Context <small>optional</small> { #context }
 
@@ -112,12 +119,12 @@ relevant. Don't write about the change request here.
 ### Description
 
 Next, provide a detailed and clear description of your idea. Explain why your
-idea is relevant to Material for MkDocs and must be implemented here, and not
+idea is relevant to Material for MkDocs and must be implemented here and not
-in one of its dependencies:[^1]
+in one of its dependencies:[^2]
 
-  [^1]:
+  [^2]:
     Sometimes, users suggest ideas on our [issue tracker] that concern one of
-    our upstream dependencies, including [MkDocs], [Python Markdown],
+    our upstream dependencies, including [MkDocs][mkdocs], [Python Markdown],
     [Python Markdown Extensions] or third-party plugins. It's a good idea to
     think about whether your idea is beneficial to other themes, upstreaming
     change requests for a bigger impact.
@@ -131,7 +138,7 @@ in one of its dependencies:[^1]
     users will be grateful for having to read less.
 
 -   __One idea at a time__ – if you have multiple ideas that don't belong
-together, please open separate change requests for each of those ideas.
+    together, please open separate change requests for each of those ideas.
 
 ---
 
@@ -144,27 +151,25 @@ before we maintainers can add it to our code base.
 > precise description, you can help save you and us time spent discussing
 > further clarification of your idea in the comments.
 
-  [MkDocs]: https://www.mkdocs.org
   [Python Markdown]: https://python-markdown.github.io/extensions/
   [Python Markdown Extensions]: https://facelessuser.github.io/pymdown-extensions/
-  [theme.name]: https://www.mkdocs.org/user-guide/configuration/#theme
 
 ### Related links
 
 Please provide any relevant links to issues, discussions, or documentation
 sections related to your change request. If you (or someone else) already
-discussed this idea with the community on our discussion board, please include 
+discussed this idea with our community on our discussion board, please include
 the link to the discussion as well.
 
 > __Why we need this__: Related links help us gain a comprehensive
 > understanding of your change request by providing additional context.
 > Additionally, linking to previous issues and discussions allows us
-> to quickly evaluate the feedback and input already provided by the community.
+> to quickly evaluate the feedback and input already provided by our community.
 
 ### Use cases
 
 Explain how your change request would work from an author's and user's
-perspective – what's the expected impact, and why does it benefit not only you
+perspective – what's the expected impact, and why does it not only benefit you,
 but other users? How many of them? Furthermore, would it potentially break
 existing functionality?
 
@@ -186,19 +191,51 @@ Additionally, if you have seen this change, feature, or improvement used in
 other static site generators or themes, please provide an example by showcasing
 it and describing how it was implemented and incorporated.
 
-> __Why we need this__: Illustrations and visuals can help us maintainers 
+> __Why this might be helpful__: Illustrations and visuals can help us
-> better understand and envision your idea. Screenshots, sketches, or mockups 
+> maintainers better understand and envision your idea. Screenshots, sketches,
-> can create an additional level of detail and clarity that text alone may not 
+> or mockups can create an additional level of detail and clarity that text
-> be able to convey. Also, seeing how your idea has been implemented in other 
+> alone may not be able to convey. Also, seeing how your idea has been
-> projects can help us understand its potential impact and feasibility in 
+> implemented in other projects can help us understand its potential impact and
-> Material for MkDocs, which helps us maintainers evaluate and triage 
+> feasibility in Material for MkDocs, which helps us maintainers evaluate and
-> change requests.
+> triage change requests.
 
 ### Checklist
 
-Thanks for following the change request guide and creating a high-quality 
+Thanks for following the guide and creating a high-quality change request – you
-change request. This section ensures that you have read this guide and have
+are almost done. The checklist ensures that you have read this guide and have
-worked to the best of your knowledge to provide us with every piece of 
+worked to your best knowledge to provide us with every piece of information to
-information to review your idea for Material for MkDocs.
+review your idea for Material for MkDocs.
 
 __We'll take it from here.__
+
+---
+
+## Rejected requests
+
+__Your change request got rejected? We're sorry for that.__ We understand it can
+be frustrating when your ideas don't get accepted, but as the maintainers of a
+very popular project, we always need to consider the needs of our entire
+community, sometimes forcing us to make tough decisions.
+
+We always have to consider and balance many factors when evaluating change
+requests, and we explain the reasoning behind our decisions whenever we can.
+If you're unsure why your change request was rejected, please don't hesitate
+to ask for clarification.
+
+The following principles (in no particular order) form the basis for our
+decisions:
+
+- [ ] Alignment with vision and tone of the project
+- [ ] Compatibility with existing features and plugins
+- [ ] Compatibility with all screen sizes and browsers
+- [ ] Effort of implementation and maintenance
+- [ ] Usefulness to the majority of users
+- [ ] Simplicity and ease of use
+- [ ] Accessibility
+
+But that's not the end of your idea – you can always implement it on your own
+via [customization]. If you're unsure about how to do that or want to know if
+someone has already done it, feel free to get in touch with our community on
+the [discussion board].
+
+  [customization]: ../customization.md

docs/conventions.md

@@ -0,0 +1,93 @@
+# 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:flag metadata --> – Metadata property { #metadata data-toc-label="Metadata property" }
+
+This symbol denotes that the thing described is a metadata property, which can
+be used in Markdown documents as part of the front matter definition.
+
+### <!-- md:flag multiple --> – Multiple instances { #multiple-instances data-toc-label="Multiple instances" }
+
+This symbol denotes that the plugin supports multiple instances, i.e, that it
+can be used multiple times in the `plugins` setting in `mkdocs.yml`.
+
+### <!-- 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 they might
+(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:extension --> – Markdown extension { data-toc-label="Markdown extension" }
+
+This symbol denotes that the thing described is a Markdown extension, which can
+be enabled in `mkdocs.yml` and adds additional functionality to the Markdown
+parser.
+
+### <!-- md:flag required --> – Required value { #required data-toc-label="Required value" }
+
+Some (very few in fact) properties or settings are required, which means the
+authors must explicitly define them.
+
+### <!-- md:flag customization --> – Customization { #customization data-toc-label="Customization" }
+
+This symbol denotes that the thing described is a customization that must be
+added by the author.
+
+### <!-- 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

@@ -66,8 +66,8 @@ theme:
               "yaml.customTags": [ // (1)!
                 "!ENV scalar",
                 "!ENV sequence",
-                "tag:yaml.org,2002:python/name:materialx.emoji.to_svg",
+                "tag:yaml.org,2002:python/name:material.extensions.emoji.to_svg",
-                "tag:yaml.org,2002:python/name:materialx.emoji.twemoji",
+                "tag:yaml.org,2002:python/name:material.extensions.emoji.twemoji",
                 "tag:yaml.org,2002:python/name:pymdownx.superfences.fence_code_format"
               ]
             }
@@ -223,12 +223,5 @@ need for operating a database or server, as it is completely self-contained.
 The site can be hosted on [GitHub Pages], [GitLab Pages], a CDN of your choice
 or your private web space.
 
-!!! note "Enterprise support"
-
-    If you're using Material for MkDocs in your organization and need
-    assistance, e.g., to __reduce build times__, __improve performance__ or
-    ensure compliance, [__get in touch__](mailto:contact@squidfunk.com)
-    to discuss our __enterprise support__ offerings. We're happy to help!
-
   [GitHub Pages]: publishing-your-site.md#github-pages
   [GitLab pages]: publishing-your-site.md#gitlab-pages

docs/customization.md

@@ -100,6 +100,7 @@ assets may also be put in the `overrides` directory:
 │  │  └─ analytics.html                # Analytics setup
 │  ├─ languages/                       # Translation languages
 │  ├─ actions.html                     # Actions
+│  ├─ alternate.html                   # Site language selector
 │  ├─ comments.html                    # Comment system (empty by default)
 │  ├─ consent.html                     # Consent
 │  ├─ content.html                     # Page content
@@ -113,6 +114,7 @@ assets may also be put in the `overrides` directory:
 │  ├─ nav.html                         # Main navigation
 │  ├─ nav-item.html                    # Main navigation item
 │  ├─ pagination.html                  # Pagination (used for blog)
+│  ├─ palette.html                     # Color palette toggle
 │  ├─ post.html                        # Blog post excerpt
 │  ├─ search.html                      # Search interface
 │  ├─ social.html                      # Social links
@@ -223,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
@@ -235,20 +237,38 @@ directly in the source of the theme and recompile it.
 
 ### Environment setup
 
-In order to start development on Material for MkDocs, a [Node.js] version of
+First, clone the repository:
-at least 14 is required. First, clone the repository:
 
 ```
 git clone https://github.com/squidfunk/mkdocs-material
-```
-
-Next, all dependencies need to be installed, which is done with:
-
-```
 cd mkdocs-material
+```
+
+Next, create a new [Python virtual environment][venv] and
+[activate][venv-activate] it:
+
+```
+python -m venv venv
+source venv/bin/activate
+```
+
+  [venv]: https://docs.python.org/3/library/venv.html
+  [venv-activate]: https://docs.python.org/3/library/venv.html#how-venvs-work
+
+Then, install all Python dependencies:
+
+```
 pip install -e .
 pip install mkdocs-minify-plugin
 pip install mkdocs-redirects
+pip install nodeenv
+```
+
+Finally, install the [Node.js] LTS version into the Python virtual environment
+and install all Node.js dependencies:
+
+```
+nodeenv -p -n lts
 npm install
 ```
 
@@ -290,7 +310,7 @@ npm run build # (1)!
 1.  While this command will build all theme files, it will skip the overrides
     used in Material for MkDocs' own documentation which are not distributed
     with the theme. If you forked the theme and want to build the overrides
-    as well, use:
+    as well, e.g. before submitting a PR with changes, use:
 
     ```
     npm run build:all
@@ -303,10 +323,3 @@ This triggers the production-level compilation and minification of all style
 sheets and JavaScript files. After the command exits, the compiled files are
 located in the `material` directory. When running `mkdocs build`, you should
 now see your changes to the original theme.
-
-!!! note "Enterprise support"
-
-    If you're using Material for MkDocs in your organization and need
-    assistance, e.g., to __reduce build times__, __improve performance__ or
-    ensure compliance, [__get in touch__](mailto:contact@squidfunk.com)
-    to discuss our __enterprise support__ offerings. We're happy to help!

docs/enterprise-support.md

@@ -0,0 +1,5 @@
+---
+template: redirect.html
+location: https://calendly.com/squidfunk/enterprise
+status: new
+---

docs/faq/sponsoring.md

@@ -79,15 +79,28 @@ Note that [$15] is the minimum amount to be granted access to Insiders.
 
   [$15]: https://github.com/sponsors/squidfunk/sponsorships?tier_id=210638
 
-[__How is my sponsorship contribution used to support the project?__](#sponsorship-support){ #sponsorship-support }
+[__How are sponsorship contributions used?__](#sponsorship-support){ #sponsorship-support }
 
-Your sponsorship contribution directly supports the development and 
+It's vital to recognize that the total sponsorship amount doesn't directly
-maintenance of the project, by buying us maintainers time. It allows us to
+translate into the funds we have available for use. The way we allocate
-dedicate more time and resources to enhance the project's features and
+sponsorship amounts is detailed as follows:
-functionality. The additional funding helps us prioritize improvements and
+
-updates, benefiting Insiders users and the wider community. We also actively
+1.  __Taxes__: Since we provide a service to our sponsors, we're of course
-contribute to other upstream projects, fostering collaboration and giving
+    legally obligated to pay sales tax. This requirement applies to all
-back to the Open Source ecosystem.
+    sponsorship contributions, aligning us with standard business practices
+    as for the rest of the world.
+
+2.  __Sponsorships__: A significant portion of our funding is redirected to
+    upstream projects. This cultivates collaboration and supports the broader
+    Open Source ecosystem. Those projects and their maintainers are essential
+    for the ongoing development of Material for MkDocs.
+
+    [Explore our sponsorships](https://github.com/squidfunk?tab=sponsoring).
+
+3.  __Funds__: We are in the process of forming a team devoted to Material for
+    MkDocs and are proactively compensating critical contributors. These
+    funds cover various aspects of the project, like the creation of new
+    features, bug resolution, support, and sponsor relations.
 
 [__Are there any limitations on the number of sponsors for a particular tier?__](#sponsorship-limitations){ #sponsorship-limitations }
 
@@ -115,7 +128,7 @@ We manage all our transactions and sponsorships through [GitHub Sponsors] and
 [our sponsors' page]. On there, you can choose from five different sponsorship 
 tiers and pay by credit card. Please note that as of the beginning of 2023, 
 [GitHub no longer supports PayPal] payments. If you wish to pay with PayPal, 
-ou can find a selection of our sponsorship tiers on [Ko-fi]. Both platforms
+you can find a selection of our sponsorship tiers on [Ko-fi]. Both platforms
 provide you with a payment receipt once your purchase is successful.
 
 If you're a company and need assistance choosing the right payment method,
@@ -371,8 +384,8 @@ appearance of your site should be optional. Most Insiders features enhance the
 overall experience, e.g., by adding icons to pages or providing a feedback 
 widget. While these features add value for your site's users, they should be 
 optional for previewing when making changes to content. Currently, the only 
-content-related features in Insiders that non-Insiders users can't properly 
+content-related feature in Insiders that non-Insiders users can't properly 
-preview are [Annotations] and [Card grids].
+preview are [Card grids].
 
 This means that outside collaborators can build the documentation locally with 
 Material for MkDocs, and when they push their changes, your CI pipeline will 
@@ -384,10 +397,8 @@ See the [getting started guide] for more information.
 
   [configuration inheritance]: https://www.mkdocs.org/user-guide/configuration/#configuration-inheritance
   [getting started guide]: ../insiders/getting-started.md#caveats
-  [Annotations]: ../reference/annotations.md?h=anno#annotations
   [Card grids]: ../reference/grids.md?h=grids#using-card-grids
 
-
 ## Support	
 
 [__How can I contact support if I have questions about becoming a sponsor?__ ](#support-contact){ #support-contact }

docs/getting-started.md

@@ -166,18 +166,10 @@ want to use the very latest version:
 git clone https://github.com/squidfunk/mkdocs-material.git
 ```
 
-The theme will reside in the folder `mkdocs-material/material`. After cloning
+Next, install the theme and its dependencies with:
-from `git`, you must install all required dependencies with:
 
 ```
 pip install -e mkdocs-material
 ```
 
-!!! note "Enterprise support"
-
-    If you're using Material for MkDocs in your organization and need
-    assistance, e.g., to __reduce build times__, __improve performance__ or
-    ensure compliance, [__get in touch__](mailto:contact@squidfunk.com)
-    to discuss our __enterprise support__ offerings. We're happy to help!
-
   [GitHub]: https://github.com/squidfunk/mkdocs-material

docs/guides/creating-a-reproduction.md

@@ -56,7 +56,7 @@ just delete and recreate the environment. It's trivial to set up:
 
 Following the instructions below, you will set up a skeleton project to create
 a reproduction. As mentioned above, we recommend using a [virtual environment],
-so create a new folder in your working directory and a a new virtual environment
+so create a new folder in your working directory and a new virtual environment
 inside it. Next:
 
 1.  As mentioned in our [bug reporting guide], ensure that you're running the
@@ -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/index.md

@@ -1,6 +1,9 @@
 ---
 template: home.html
 title: Material for MkDocs
+social:
+  cards_layout_options:
+    title: Documentation that simply works
 ---
 
 Welcome to Material for MkDocs.

docs/insiders/changelog.md

@@ -2,6 +2,69 @@
 
 ## Material for MkDocs Insiders
 
+### 4.42.0 <small>September 19, 2023</small> { id="4.42.0" }
+
+- Added support for using git submodules in projects plugin
+- Added support for transforming project configurations
+- Improved resilience of optimize and blog plugin
+- Fixed optimize plugin crashing on `.jpeg` extension
+- Fixed project URLs not using site URLs in projects plugin
+
+### 4.41.0 <small>September 11, 2023</small> { id="4.41.0" }
+
+- Improved multi-instance support for optimize plugin
+- Added inclusion and exclusion patterns for optimize plugin
+- Added transparent keyword for color handling in social plugin
+- Changed default quality of PNGs to 3 in optimize plugin
+- Fixed #5979: meta file not detected in root of docs directory
+
+### 4.40.4 <small>September 4, 2023</small> { id="4.40.4" }
+
+- Fixed privacy plugin choking on boolean HTML5 attributes
+- Fixed wrapping of inline code blocks in typeset table of contents
+- Fixed blog plugin error when running under dirty reload
+
+### 4.40.3 <small>September 2, 2023</small> { id="4.40.3" }
+
+- Fixed #5946: Docker image missing pngquant for optimize plugin
+
+### 4.40.2 <small>August 31, 2023</small> { id="4.40.2" }
+
+- Added configurable error handling capabilities for social plugin
+- Fixed #5922: Blog plugin shows no posts when building a standalone blog
+- Fixed #5914: Tags plugin tags_extra_files errors (4.39.3 regression)
+- Fixed #5904: Blog plugin sometimes excludes files (4.40.1 regression)
+
+### 4.40.1 <small>August 27, 2023</small> { id="4.40.1" }
+
+- Fixed #5902: ResizeObserver polyfill not detected by privacy plugin
+- Fixed empty category pages in blog plugin (4.40.0 regression)
+
+### 4.40.0 <small>August 26, 2023</small> { id="4.40.0" }
+
+- Added logo, title and description options to social plugin default layouts
+- Fixed privacy plugin compatibility issue with Python < 3.10
+- Fixed #5896: Blog plugin errors when using custom index pages
+
+### 4.39.3 <small>August 24, 2023</small> { id="4.39.3" }
+
+- Fixed lxml dependency missing in Docker container (4.39.2 regression)
+
+### 4.39.2 <small>August 23, 2023</small> { id="4.39.2" }
+
+- Fixed color palette toggle being reversed (9.2.0 regression)
+
+### 4.39.1 <small>August 21, 2023</small> { id="4.39.1" }
+
+- Fixed git diff in tags plugin after merging back 9.2.0 changes
+
+### 4.39.0 <small>August 3, 2023</small> { id="4.39.0" }
+
+- Added support for hoisting theme media files when building projects
+- Added support for sorting pages on tags index for tags plugin
+- Added support for adding date of last update to blog posts
+- Fixed #5797: Parse error in typeset plugin (4.38.1 regression)
+
 ### 4.38.1 <small>August 1, 2023</small> { id="4.38.1" }
 
 - Improved nested serve mode for projects plugin

docs/insiders/getting-started.md

@@ -88,7 +88,7 @@ outlined in the [Getting Started guide](../getting-started.md#with-docker).
     outlined and discussed in #2442. It was removed on June 1, 2021.
 
   [^3]:
-    When forking a repository, GitHub will disables all workflows. While this
+    When forking a repository, GitHub will disable all workflows. While this
     is a reasonable default setting, you need to enable GitHub Actions to be
     able to automatically build and publish a Docker image on
     [GitHub Container Registry].
@@ -150,65 +150,45 @@ pip install --upgrade git+https://${GH_TOKEN}@github.com/squidfunk/mkdocs-materi
 
   [upgrade guide]: ../upgrade.md
 
-## Caveats
+## Built-in plugins
 
-This section describes some aspects to consider when using Insiders together
+When you're using built-in plugins that are solely available via Insiders,
-with Material for MkDocs to ensure that users without access to Insiders can
+outside contributors won't be able to build your documentation project on their
-still build your documentation.
+local machine. This is the reason why we developed the [built-in group plugin]
+that allows to conditionally load plugins:
 
-### Built-in plugins
+``` yaml
+plugins:
+  - search
+  - social
 
-When using built-in plugins that are solely available via Insiders, it might be 
+  # CI=1 mkdocs build
-necessary to split the `mkdocs.yml` configuration into a base configuration, and
+  - group:
-one with plugin overrides. Note that this is a limitation of MkDocs, which can
+      enabled: !ENV CI
-be mitigated by using [configuration inheritance]:
+      plugins:
+        - git-revision-date-localized
+        - git-committers
 
-=== ":octicons-file-code-16: `mkdocs.insiders.yml`"
+  # INSIDERS=1 mkdocs build
-
+  - group:
-    ``` yaml
+      enabled: !ENV INSIDERS
-    INHERIT: mkdocs.yml
+      plugins:
-    plugins:
+        - optimize
-      - search
+        - privacy
-      - social
-      - tags
-    ```
-
-=== ":octicons-file-code-16: `mkdocs.yml`"
-
-    ``` yaml
-    # Configuration with everything except Insiders plugins
-    ```
-
-Now, when you're in an environment with access to Insiders (e.g. in your CI
-pipeline), you can build your documentation project with the following lines:
-
-```
-mkdocs build --config-file mkdocs.insiders.yml
 ```
 
-!!! tip "Sharing plugin and extension configuration"
+Of course, you can also enable both groups with:
 
-    If you want to share `plugins` or `markdown_extensions` between both
+```
-    configuration files `mkdocs.insiders.yml` and `mkdocs.yml`, you can use
+CI=1 INSIDERS=1 mkdocs build
-    the alternative key-value syntax in both files. The above example would
+```
-    then look like:
-
-    === ":octicons-file-code-16: `mkdocs.insiders.yml`"
-
-        ``` yaml
-        INHERIT: mkdocs.yml
-        plugins:
-          social: {}
-        ```
-
-    === ":octicons-file-code-16: `mkdocs.yml`"
-
-        ``` yaml
-        # Additional configuration above
-        plugins:
-          search: {}
-          tags: {}
-        ```
 
+  [^1]:
+    Previously we recommended to use [configuration inheritance] to work around
+    this limitations, but the brand new [built-in group plugin] is a much better
+    approach, as it allows you to use a single configuration file for building
+    your project with the community edition and Insiders version of Material
+    for MkDocs.
 
+  [built-in group plugin]: ../plugins/group.md
   [configuration inheritance]: https://www.mkdocs.org/user-guide/configuration/#configuration-inheritance

docs/insiders/index.md

@@ -188,7 +188,6 @@ You can cancel your sponsorship anytime.[^5]
 [![Sparkfun]](https://sparkfun.com/){ target=_blank title="Sparkfun Electronics" }
 [![Eccenca]](https://eccenca.com/){ target=_blank title="Eccenca" }
 [![Neptune]](https://neptune.ai/){ target=_blank title="Neptune" }
-[![Cash App]](https://cash.app/){ target=_blank title="Cash App" }
 [![RackN]](https://rackn.com/){ target=_blank title="RackN" }
 [![CivicActions]](https://civicactions.com/){ target=_blank title="CivicActions" }
 [![bitcrowd]](https://bitcrowd.net/){ target=_blank title="bitcrowd" }
@@ -200,6 +199,8 @@ You can cancel your sponsorship anytime.[^5]
 [![Koor]](https://koor.tech/){ target=_blank title="Koor" }
 [![Astral]](https://astral.sh/){ target=_blank title="Astral" }
 [![Oikolab]](https://oikolab.com/){ target=_blank title="Oikolab" }
+[![Bühler Group]](https://www.buhlergroup.com/){ target=_blank title="Bühler Group" }
+[![Transformation Flow]](https://transformationflow.io/){ target=_blank title="Transformation Flow" }
 
 </div>
 
@@ -235,6 +236,8 @@ You can cancel your sponsorship anytime.[^5]
   [Koor]: https://raw.githubusercontent.com/squidfunk/mkdocs-material/master/.github/assets/sponsors/sponsor-koor.png
   [Astral]: https://raw.githubusercontent.com/squidfunk/mkdocs-material/master/.github/assets/sponsors/sponsor-astral.png
   [Oikolab]: https://raw.githubusercontent.com/squidfunk/mkdocs-material/master/.github/assets/sponsors/sponsor-oikolab.png
+  [Bühler Group]: https://raw.githubusercontent.com/squidfunk/mkdocs-material/master/.github/assets/sponsors/sponsor-buhler.png
+  [Transformation Flow]: https://raw.githubusercontent.com/squidfunk/mkdocs-material/master/.github/assets/sponsors/sponsor-transformationflow.png
 
 <hr />
 
@@ -286,7 +289,7 @@ are released for general availability.
 - [x] [Tags plugin: allow list] + [custom sorting]
 - [x] [Navigation subtitles]
 
-  [Meta plugin]: ../reference/index.md#built-in-meta-plugin
+  [Meta plugin]: ../plugins/meta.md
   [Blog plugin: related links]: ../setup/setting-up-a-blog.md#adding-related-links
   [Blog plugin: custom index pages]: ../setup/setting-up-a-blog.md#custom-index-pages
   [Tags plugin: additional indexes]: ../setup/setting-up-tags.md#+tags.tags_extra_files
@@ -303,8 +306,8 @@ are released for general availability.
 - [x] [Privacy plugin: external links]
 - [x] [Instant prefetching]
 
-  [Optimize plugin]: ../setup/building-an-optimized-site.md#built-in-optimize-plugin
+  [Optimize plugin]: ../plugins/optimize.md
-  [Typeset plugin]: ../reference/index.md#built-in-typeset-plugin
+  [Typeset plugin]: ../plugins/typeset.md
   [Privacy plugin: external links]: ../setup/ensuring-data-privacy.md#+privacy.links
   [Privacy plugin: optimization support]: ../setup/ensuring-data-privacy.md#+privacy.assets_include
   [Navigation path]: ../setup/setting-up-navigation.md#navigation-path
@@ -319,7 +322,7 @@ are released for general availability.
 - [x] [Code annotations: custom selectors]
 - [ ] Code line wrap button
 
-  [Projects plugin]: ../setup/building-an-optimized-site.md#built-in-projects-plugin
+  [Projects plugin]: ../plugins/projects.md
   [Social plugin: custom layouts]: ../setup/setting-up-social-cards.md#customization
   [Social plugin: background images]: ../setup/setting-up-social-cards.md#+social.cards_layout_params.background_image
   [Code range selection]: ../reference/code-blocks.md#code-selection-button
@@ -488,7 +491,7 @@ and configuration options are either backward-compatible or implemented behind
 feature flags. When working with outside collaborators, it should be rarely
 necessary to change the general appearance of your site. Most Insiders features
 enhance the overall experience, e.g. by adding icons to pages or providing a
-feedback widget. While this features add value for the user of your site, they
+feedback widget. While these features add value for the user of your site, they
 shouldn't be necessary for previewing when making changes to content. Currently,
 the only content-related features in Insiders that can't be properly previewed
 by non-Insiders users are:

docs/philosophy.md

@@ -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 meta file name 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,365 @@
+---
+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.
+
+---
+
+#### <!-- md:setting config.projects_config_files -->
+
+<!-- md:sponsors -->
+<!-- md:version insiders-4.42.0 -->
+<!-- md:default `*/mkdocs.yml` -->
+
+Use this setting to change the location or name of configuration files the
+plugin will look for when scanning the [`projects` directory]
+[config.projects_dir]. Adjusting this setting can be necessary when the
+configuration files are located in subdirectories of projects, e.g.
+`docs/mkdocs.yml`:
+
+``` yaml
+plugins:
+  - projects:
+      projects_config_files: "**/mkdocs.yml" # (1)!
+```
+
+1.  If all projects share the same location for their configuration files, e.g.,
+    `docs/mkdocs.yml`, it's advisable to fully qualify the path, as it's faster
+    to resolve than a `**` glob pattern.
+
+    ``` yaml
+    plugins:
+      - projects:
+          projects_config_files: "*/docs/mkdocs.yml"
+    ```
+
+    This configuration fits the following directory structure, which is quite
+    common for projects using git submodules:
+
+    ``` { .sh .no-copy }
+    .
+    ├─ docs/
+    ├─ projects/
+    │  ├─ git-submodule-a/
+    │  │  └─ docs/
+    │  │     └─ mkdocs.yml
+    │  └─ git-submodule-b/
+    │     └─ docs/
+    │        └─ mkdocs.yml
+    └─ mkdocs.yml
+    ```
+
+The provided path is resolved from the [`projects` directory]
+[config.projects_dir].
+
+---
+
+#### <!-- md:setting config.projects_config_transform -->
+
+<!-- md:sponsors -->
+<!-- md:version insiders-4.42.0 -->
+<!-- md:default none -->
+
+Use this setting to transform the configuration of each project as read from
+`mkdocs.yml` before it is built, which allows for adjusting the configuration
+of each project when building them together, but leave them untouched when
+building them individually:
+
+``` yaml
+plugins:
+  - projects:
+      projects_config_transform: !!python/name:projects.transform
+```
+
+The provided module and function name are looked up in Python's [module search
+path]. You need to add your root directory to the search path when building
+your site, so Python can resolve it. The easiest way is to add the working
+directory to the [`PYTHONPATH`][PYTHONPATH] environment variable:
+
+``` .sh
+export PYTHONPATH=.
+```
+
+!!! tip "How to define a configuration transformation function"
+
+    The [`python/name`][python-name] tag is provided by [PyYAML] and must point
+    to a valid module and function name within Python's [module search path].
+    The plugin passes the `project` and top-level `config` objects to the
+    function.
+
+    As an example, we can inherit the [`use_directory_urls`]
+    [mkdocs.use_directory_urls] setting for all projects from the top-level
+    configuration:
+
+    ``` py title="projects/__init__.py"
+    from mkdocs.config.defaults import MkDocsConfig
+
+    # Transform project configuration
+    def transform(project: MkDocsConfig, config: MkDocsConfig):
+        project.use_directory_urls = config.use_directory_urls
+    ```
+
+  [module search path]: https://docs.python.org/3/library/sys_path_init.html
+  [PYTHONPATH]: https://docs.python.org/3/using/cmdline.html#envvar-PYTHONPATH
+  [python-name]: https://pyyaml.org/wiki/PyYAMLDocumentation#yaml-tags-and-python-types
+  [PyYAML]: https://pyyaml.org/
+
+### 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/
@@ -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]: ../../plugins/optimize.md
   [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/publishing-your-site.md

@@ -34,7 +34,7 @@ contents:
       deploy:
         runs-on: ubuntu-latest
         steps:
-          - uses: actions/checkout@v3
+          - uses: actions/checkout@v4
           - uses: actions/setup-python@v4
             with:
               python-version: 3.x
@@ -89,7 +89,7 @@ contents:
         runs-on: ubuntu-latest
         if: github.event.repository.fork == false
         steps:
-          - uses: actions/checkout@v3
+          - uses: actions/checkout@v4
           - uses: actions/setup-python@v4
             with:
               python-version: 3.x
@@ -128,7 +128,7 @@ Your documentation should shortly appear at `<username>.github.io/<repository>`.
   [MkDocs plugins]: https://github.com/mkdocs/mkdocs/wiki/MkDocs-Plugins
   [personal access token]: https://docs.github.com/en/github/authenticating-to-github/creating-a-personal-access-token
   [Insiders]: insiders/index.md
-  [built-in optimize plugin]: setup/building-an-optimized-site.md#built-in-optimize-plugin
+  [built-in optimize plugin]: plugins/optimize.md
   [GitHub secrets]: https://docs.github.com/en/actions/configuring-and-managing-workflows/creating-and-storing-encrypted-secrets
   [publishing source branch]: https://docs.github.com/en/pages/getting-started-with-github-pages/configuring-a-publishing-source-for-your-github-pages-site
   [manual page]: https://man7.org/linux/man-pages/man1/date.1.html
@@ -207,13 +207,6 @@ other providers:
 
 </div>
 
-!!! note "Enterprise support"
-
-    If you're using Material for MkDocs in your organization and need
-    assistance, e.g., to __reduce build times__, __improve performance__ or
-    ensure compliance, [__get in touch__](mailto:contact@squidfunk.com)
-    to discuss our __enterprise support__ offerings. We're happy to help!
-
   [GitLab Pages]: https://gitlab.com/pages
   [GitLab CI]: https://docs.gitlab.com/ee/ci/
   [masked custom variables]: https://docs.gitlab.com/ee/ci/variables/#create-a-custom-variable-in-the-ui

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
@@ -504,5 +501,5 @@ After applying the customization, you can use the custom admonition type:
 
 </div>
 
-  [custom icons]: https://github.com/squidfunk/mkdocs-material/tree/master/material/.icons
+  [custom icons]: https://github.com/squidfunk/mkdocs-material/tree/master/material/templates/.icons
   [additional style sheet]: ../customization.md#additional-css

docs/reference/annotations.md

@@ -31,12 +31,51 @@ See additional configuration options:
   [Markdown in HTML]: ../setup/extensions/python-markdown.md#markdown-in-html
   [SuperFences]: ../setup/extensions/python-markdown-extensions.md#superfences
 
+### Annotation icons
+
+<!-- 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
+lines to `mkdocs.yml`:
+
+``` yaml
+theme:
+  icon:
+    annotation: material/arrow-right-circle # (1)!
+```
+
+1.  Enter a few keywords to find the perfect icon using our [icon search] and
+    click on the shortcode to copy it to your clipboard:
+
+    <div class="mdx-iconsearch" data-mdx-component="iconsearch">
+      <input class="md-input md-input--stretch mdx-iconsearch__input" placeholder="Search icon" data-mdx-component="iconsearch-query" value="material circle" />
+      <div class="mdx-iconsearch-result" data-mdx-component="iconsearch-result" data-mdx-mode="file">
+        <div class="mdx-iconsearch-result__meta"></div>
+        <ol class="mdx-iconsearch-result__list"></ol>
+      </div>
+    </div>
+
+Some popular choices:
+
+- :material-plus-circle: - `material/plus-circle`
+- :material-circle-medium: - `material/circle-medium`
+- :material-record-circle: - `material/record-circle`
+- :material-arrow-right-circle: - `material/arrow-right-circle`
+- :material-arrow-right-circle-outline: - `material/arrow-right-circle-outline`
+- :material-chevron-right-circle: - `material/chevron-right-circle`
+- :material-star-four-points-circle: - `material/star-four-points-circle`
+- :material-plus-circle-outline: - `material/plus-circle-outline`
+
+  [custom icon]: ../setup/changing-the-logo-and-icons.md#additional-icons
+  [icon search]: icons-emojis.md#search
+
 ## Usage
 
 ### Using annotations
 
-[:octicons-tag-24: 9.2.0b0][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
@@ -64,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.0b0
-
 #### in annotations
 
 When [SuperFences] is enabled, annotations can be nested inside annotations by

docs/reference/code-blocks.md

@@ -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
@@ -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
@@ -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
@@ -159,14 +156,13 @@ theme:
     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
@@ -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>"`
@@ -511,11 +505,11 @@ override it as part of your [additional style sheet]:
       - stylesheets/extra.css
     ```
 
-  [colors]: https://github.com/squidfunk/mkdocs-material/blob/master/src/assets/stylesheets/main/_colors.scss
+  [colors]: https://github.com/squidfunk/mkdocs-material/blob/master/src/templates/assets/stylesheets/main/_colors.scss
   [color schemes]: ../setup/changing-the-colors.md#color-scheme
   [types of string tokens]: https://pygments.org/docs/tokens/#literals
   [additional style sheet]: ../customization.md#additional-css
-  [syntax theme definition]: https://github.com/squidfunk/mkdocs-material/blob/master/src/assets/stylesheets/main/extensions/pymdownx/_highlight.scss
+  [syntax theme definition]: https://github.com/squidfunk/mkdocs-material/blob/master/src/templates/assets/stylesheets/main/extensions/pymdownx/_highlight.scss
 
 ### Annotation tooltip width
 
@@ -549,35 +543,3 @@ This will render annotations with a larger width:
 1. Muuuuuuuuuuuuuuuch more space for content
 
 </div>
-
-### Annotations with numbers
-
-Prior to [:octicons-tag-24: 8.1.0][code annotation markers], code annotations
-were rendered with markers showing the original number as used by the author.
-However, for technical reasons code annotation numbers restart each code block,
-which might lead to confusion. For this reason, code annotations now render as
-`+` signs which are rotated if they're open to denote that clicking them again
-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:
-
-=== ":octicons-file-code-16: `docs/stylesheets/extra.css`"
-
-    ``` css
-    .md-typeset .md-annotation__index > ::before {
-      content: attr(data-md-annotation-id);
-    }
-    .md-typeset :focus-within > .md-annotation__index > ::before {
-      transform: none;
-    }
-    ```
-
-=== ":octicons-file-code-16: `mkdocs.yml`"
-
-    ``` yaml
-    extra_css:
-      - stylesheets/extra.css
-    ```
-
-  [code annotation markers]: https://github.com/squidfunk/mkdocs-material/releases/tag/8.1.0

docs/reference/content-tabs.md

@@ -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,8 +73,8 @@ 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
@@ -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

@@ -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
 
@@ -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/icons-emojis.md

@@ -6,10 +6,11 @@ icon: material/emoticon-happy-outline
 
 One of the best features of Material for MkDocs is the possibility to use [more
 than 10,000 icons][icon search] and thousands of emojis in your project
-documentation with practically zero additional effort. Moreover, custom icons 
+documentation with practically zero additional effort. Moreover, [custom icons
-can be added and used in `mkdocs.yml`, documents and templates.
+can be added] and used in `mkdocs.yml`, documents and templates.
 
   [icon search]: #search
+  [custom icons can be added]: ../setup/changing-the-logo-and-icons.md#additional-icons
 
 ## Search
 
@@ -40,8 +41,8 @@ lines to `mkdocs.yml`:
 markdown_extensions:
   - attr_list
   - pymdownx.emoji:
-      emoji_index: !!python/name:materialx.emoji.twemoji
+      emoji_index: !!python/name:material.extensions.emoji.twemoji
-      emoji_generator: !!python/name:materialx.emoji.to_svg
+      emoji_generator: !!python/name:material.extensions.emoji.to_svg
 ```
 
 The following icon sets are bundled with Material for MkDocs:
@@ -102,7 +103,7 @@ a valid path to any icon bundled with the theme, which are located in the
 
 </div>
 
-  [custom icons]: https://github.com/squidfunk/mkdocs-material/tree/master/material/.icons
+  [custom icons]: https://github.com/squidfunk/mkdocs-material/tree/master/material/templates/.icons
 
 #### with colors
 
@@ -198,7 +199,7 @@ With the help of the [built-in typeset plugin], you can use icons and emojis
 in headings, which will then be rendered in the sidebars. The plugin preserves
 Markdown and HTML formatting.
 
-  [built-in typeset plugin]: ./index.md#built-in-typeset-plugin
+  [built-in typeset plugin]: ../plugins/typeset.md
 
 ## Customization
 

docs/reference/images.md

@@ -31,8 +31,8 @@ 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
 [glightbox] plugin is an excellent choice, as it integrates perfectly
@@ -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

@@ -7,68 +7,6 @@ within Markdown files.
 
 ## Configuration
 
-### Built-in <u>typeset</u> plugin
-
-[:octicons-heart-fill-24:{ .mdx-heart } Sponsors only][Insiders]{ .mdx-insiders } ·
-[:octicons-tag-24: insiders-4.27.0][Insiders] ·
-:octicons-cpu-24: Plugin ·
-:octicons-beaker-24: 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
-inline formatting will be preserved, which allows for a richer editing
-experience. Add the following lines to `mkdocs.yml`:
-
-``` yaml
-plugins:
-  - typeset
-```
-
-For a demo, just take a look at the table of contents of this page :material-arrow-right-circle: – code blocks and icons are preserved from the
-section headlines; even [highlighting inline code blocks] is supported :tada:
-
-  [highlighting inline code blocks]: code-blocks.md#highlighting-inline-code-blocks
-
-### Built-in meta plugin
-
-[:octicons-heart-fill-24:{ .mdx-heart } Sponsors only][Insiders]{ .mdx-insiders } ·
-[:octicons-tag-24: insiders-4.21.0][Insiders] ·
-:octicons-cpu-24: Plugin ·
-:octicons-beaker-24: Experimental
-
-The built-in meta plugin allows to __set front matter per folder__, which is
-especially handy to ensure that all pages in a folder use specific templates or 
-tags. Add the following lines to `mkdocs.yml`:
-
-``` yaml
-plugins:
-  - meta
-```
-
-> If you need to be able to build your documentation with and without
-> [Insiders], please refer to the [built-in plugins] section to learn how
-> shared configurations help to achieve this.
-
-The following configuration options are available:
-
-[`meta_file`](#+meta.meta_file){ #+meta.meta_file }
-
-:   :octicons-milestone-24: Default: `**/.meta.yml` – This option specifies the
-    name of the meta files that the plugin should look for. The default setting
-    assumes that meta files are called `.meta.yml`:
-
-    ``` yaml
-    plugins:
-      - meta:
-          meta_file: '**/.meta.yml' # (1)!
-    ```
-
-    1.  Note that it's strongly recommended to prefix meta files with a `.`,
-        since otherwise they would be included in the build output.
-
-  [built-in blog plugin]: ../setup/setting-up-a-blog.md#built-in-blog-plugin
-  [built-in plugins]: ../insiders/getting-started.md#built-in-plugins
-
 ## Usage
 
 ### Setting the page `title`
@@ -83,7 +21,7 @@ explicitly set with the front matter `title` property:
 title: Lorem ipsum dolor sit amet # (1)!
 ---
 
-# Document title
+# Page title
 ...
 ```
 
@@ -110,7 +48,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 +59,8 @@ description: Nullam urna elit, malesuada eget finibus ut, ac tortor. # (1)!
 
 ### Setting the page `icon`
 
-[:octicons-tag-24: 9.2.0b0][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 +72,7 @@ top of a Markdown file:
 icon: material/emoticon-happy # (1)!
 ---
 
-# Document title
+# Page title
 ...
 ```
 
@@ -149,15 +87,14 @@ icon: material/emoticon-happy # (1)!
       </div>
     </div>
 
-  [Page icon support]: https://github.com/squidfunk/mkdocs-material/releases/tag/9.2.0b0
   [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.0b0][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
@@ -188,7 +125,7 @@ Markdown file:
 status: new
 ---
 
-# Document title
+# Page title
 ...
 ```
 
@@ -197,13 +134,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.0b0
-
 ### 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,7 +149,7 @@ adding the following lines:
 subtitle: Nullam urna elit, malesuada eget finibus ut, ac tortor
 ---
 
-# Document title
+# Page title
 ...
 ```
 
@@ -229,7 +164,7 @@ lines at the top of a Markdown file:
 template: custom.html
 ---
 
-# Document title
+# Page title
 ...
 ```
 
@@ -244,7 +179,7 @@ template: custom.html
     ```
 
   [theme extension]: ../customization.md#extending-the-theme
-  [built-in meta plugin]: #built-in-meta-plugin
+  [built-in meta plugin]: ../plugins/meta.md
 
 ## Customization
 

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,8 +55,6 @@ 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

docs/schema/assets/icons.json

@@ -104,6 +104,7 @@
     "fontawesome/brands/d-and-d",
     "fontawesome/brands/dailymotion",
     "fontawesome/brands/dashcube",
+    "fontawesome/brands/debian",
     "fontawesome/brands/deezer",
     "fontawesome/brands/delicious",
     "fontawesome/brands/deploydog",
@@ -375,11 +376,13 @@
     "fontawesome/brands/square-reddit",
     "fontawesome/brands/square-snapchat",
     "fontawesome/brands/square-steam",
+    "fontawesome/brands/square-threads",
     "fontawesome/brands/square-tumblr",
     "fontawesome/brands/square-twitter",
     "fontawesome/brands/square-viadeo",
     "fontawesome/brands/square-vimeo",
     "fontawesome/brands/square-whatsapp",
+    "fontawesome/brands/square-x-twitter",
     "fontawesome/brands/square-xing",
     "fontawesome/brands/square-youtube",
     "fontawesome/brands/squarespace",
@@ -409,6 +412,7 @@
     "fontawesome/brands/themeco",
     "fontawesome/brands/themeisle",
     "fontawesome/brands/think-peaks",
+    "fontawesome/brands/threads",
     "fontawesome/brands/tiktok",
     "fontawesome/brands/trade-federation",
     "fontawesome/brands/trello",
@@ -459,6 +463,7 @@
     "fontawesome/brands/wpexplorer",
     "fontawesome/brands/wpforms",
     "fontawesome/brands/wpressr",
+    "fontawesome/brands/x-twitter",
     "fontawesome/brands/xbox",
     "fontawesome/brands/xing",
     "fontawesome/brands/y-combinator",
@@ -9503,8 +9508,17 @@
     "octicons/feed-discussion-16",
     "octicons/feed-forked-16",
     "octicons/feed-heart-16",
+    "octicons/feed-issue-closed-16",
+    "octicons/feed-issue-draft-16",
+    "octicons/feed-issue-open-16",
+    "octicons/feed-issue-reopen-16",
     "octicons/feed-merged-16",
     "octicons/feed-person-16",
+    "octicons/feed-plus-16",
+    "octicons/feed-public-16",
+    "octicons/feed-pull-request-closed-16",
+    "octicons/feed-pull-request-draft-16",
+    "octicons/feed-pull-request-open-16",
     "octicons/feed-repo-16",
     "octicons/feed-rocket-16",
     "octicons/feed-star-16",
@@ -9992,8 +10006,10 @@
     "simple/airtable",
     "simple/ajv",
     "simple/akamai",
+    "simple/akaunting",
     "simple/alacritty",
     "simple/albertheijn",
+    "simple/alby",
     "simple/alchemy",
     "simple/aldinord",
     "simple/aldisud",
@@ -10003,6 +10019,7 @@
     "simple/algorand",
     "simple/alibabacloud",
     "simple/alibabadotcom",
+    "simple/alienware",
     "simple/aliexpress",
     "simple/alipay",
     "simple/allegro",
@@ -10019,6 +10036,7 @@
     "simple/amazonapigateway",
     "simple/amazonaws",
     "simple/amazoncloudwatch",
+    "simple/amazondocumentdb",
     "simple/amazondynamodb",
     "simple/amazonec2",
     "simple/amazonecs",
@@ -10032,7 +10050,9 @@
     "simple/amazonprime",
     "simple/amazonrds",
     "simple/amazonredshift",
+    "simple/amazonroute53",
     "simple/amazons3",
+    "simple/amazonsimpleemailservice",
     "simple/amazonsqs",
     "simple/amd",
     "simple/ameba",
@@ -10120,6 +10140,7 @@
     "simple/arkecosystem",
     "simple/arlo",
     "simple/arm",
+    "simple/armkeil",
     "simple/arstechnica",
     "simple/artifacthub",
     "simple/artixlinux",
@@ -10157,11 +10178,13 @@
     "simple/autoprefixer",
     "simple/avajs",
     "simple/avast",
+    "simple/avira",
     "simple/awesomelists",
     "simple/awesomewm",
     "simple/awsamplify",
     "simple/awsfargate",
     "simple/awslambda",
+    "simple/awsorganizations",
     "simple/axios",
     "simple/azureartifacts",
     "simple/azuredataexplorer",
@@ -10259,6 +10282,7 @@
     "simple/brevo",
     "simple/britishairways",
     "simple/broadcom",
+    "simple/bsd",
     "simple/bspwm",
     "simple/bt",
     "simple/buddy",
@@ -10295,6 +10319,7 @@
     "simple/canva",
     "simple/capacitor",
     "simple/cardano",
+    "simple/carrd",
     "simple/carrefour",
     "simple/carthrottle",
     "simple/carto",
@@ -10329,6 +10354,7 @@
     "simple/chinaeasternairlines",
     "simple/chinasouthernairlines",
     "simple/chocolatey",
+    "simple/chromatic",
     "simple/chromecast",
     "simple/chrysler",
     "simple/chupachups",
@@ -10346,6 +10372,7 @@
     "simple/ckeditor4",
     "simple/clarifai",
     "simple/claris",
+    "simple/clarivate",
     "simple/clickhouse",
     "simple/clickup",
     "simple/clion",
@@ -10409,6 +10436,7 @@
     "simple/commonworkflowlanguage",
     "simple/compilerexplorer",
     "simple/composer",
+    "simple/comptia",
     "simple/comsol",
     "simple/conan",
     "simple/concourse",
@@ -10436,7 +10464,9 @@
     "simple/coveralls",
     "simple/cpanel",
     "simple/cplusplus",
+    "simple/cplusplusbuilder",
     "simple/craftcms",
+    "simple/craftsman",
     "simple/cratedb",
     "simple/crayon",
     "simple/creality",
@@ -10461,6 +10491,7 @@
     "simple/cultura",
     "simple/curl",
     "simple/curseforge",
+    "simple/cyberdefenders",
     "simple/cycling74",
     "simple/cypress",
     "simple/cytoscapedotjs",
@@ -10495,6 +10526,7 @@
     "simple/dbt",
     "simple/dcentertainment",
     "simple/debian",
+    "simple/decapcms",
     "simple/dedge",
     "simple/deepin",
     "simple/deepnote",
@@ -10533,12 +10565,15 @@
     "simple/discover",
     "simple/disqus",
     "simple/disroot",
+    "simple/distrokid",
     "simple/django",
     "simple/dlib",
     "simple/dlna",
     "simple/dm",
     "simple/docker",
     "simple/docsdotrs",
+    "simple/docsify",
+    "simple/docusaurus",
     "simple/docusign",
     "simple/dogecoin",
     "simple/doi",
@@ -10625,6 +10660,7 @@
     "simple/epicgames",
     "simple/epson",
     "simple/equinixmetal",
+    "simple/ericsson",
     "simple/erlang",
     "simple/esbuild",
     "simple/esea",
@@ -10657,6 +10693,7 @@
     "simple/facebooklive",
     "simple/faceit",
     "simple/facepunch",
+    "simple/falco",
     "simple/falcon",
     "simple/fampay",
     "simple/fandango",
@@ -10693,6 +10730,7 @@
     "simple/filezilla",
     "simple/fing",
     "simple/firebase",
+    "simple/firefish",
     "simple/fireflyiii",
     "simple/firefox",
     "simple/firefoxbrowser",
@@ -10709,13 +10747,16 @@
     "simple/flatpak",
     "simple/flattr",
     "simple/flickr",
+    "simple/flightaware",
     "simple/flipboard",
     "simple/flipkart",
     "simple/floatplane",
     "simple/flood",
     "simple/fluentbit",
     "simple/fluentd",
+    "simple/fluke",
     "simple/flutter",
+    "simple/flux",
     "simple/fluxus",
     "simple/flyway",
     "simple/fmod",
@@ -10763,8 +10804,10 @@
     "simple/g2",
     "simple/g2a",
     "simple/gameandwatch",
+    "simple/gamebanana",
     "simple/gamedeveloper",
     "simple/gamejolt",
+    "simple/gamemaker",
     "simple/garmin",
     "simple/gatling",
     "simple/gatsby",
@@ -10824,18 +10867,23 @@
     "simple/googleanalytics",
     "simple/googleappsscript",
     "simple/googleassistant",
+    "simple/googlebard",
+    "simple/googlebigquery",
     "simple/googlecalendar",
     "simple/googlecardboard",
     "simple/googlechat",
     "simple/googlechrome",
     "simple/googleclassroom",
     "simple/googlecloud",
+    "simple/googlecloudcomposer",
     "simple/googlecolab",
     "simple/googlecontaineroptimizedos",
+    "simple/googledatastudio",
     "simple/googledocs",
     "simple/googledomains",
     "simple/googledrive",
     "simple/googleearth",
+    "simple/googleearthengine",
     "simple/googlefit",
     "simple/googlefonts",
     "simple/googleforms",
@@ -10858,12 +10906,14 @@
     "simple/googlescholar",
     "simple/googlesearchconsole",
     "simple/googlesheets",
+    "simple/googleslides",
     "simple/googlestreetview",
     "simple/googletagmanager",
     "simple/googletranslate",
     "simple/gotomeeting",
     "simple/grab",
     "simple/gradle",
+    "simple/gradleplaypublisher",
     "simple/grafana",
     "simple/grammarly",
     "simple/grandfrais",
@@ -10900,7 +10950,9 @@
     "simple/hackerrank",
     "simple/hackster",
     "simple/hackthebox",
+    "simple/hal",
     "simple/handlebarsdotjs",
+    "simple/handm",
     "simple/handshake",
     "simple/handshake_protocol",
     "simple/happycow",
@@ -10917,6 +10969,7 @@
     "simple/hcl",
     "simple/headlessui",
     "simple/headspace",
+    "simple/hearth",
     "simple/hearthisdotat",
     "simple/hedera",
     "simple/hellofresh",
@@ -10927,6 +10980,7 @@
     "simple/here",
     "simple/heroku",
     "simple/hetzner",
+    "simple/hexlet",
     "simple/hexo",
     "simple/hey",
     "simple/hibernate",
@@ -10943,6 +10997,7 @@
     "simple/homify",
     "simple/honda",
     "simple/honey",
+    "simple/honor",
     "simple/hootsuite",
     "simple/hoppscotch",
     "simple/hotelsdotcom",
@@ -10954,6 +11009,7 @@
     "simple/hsbc",
     "simple/html5",
     "simple/htmlacademy",
+    "simple/htop",
     "simple/httpie",
     "simple/huawei",
     "simple/hubspot",
@@ -10968,6 +11024,7 @@
     "simple/hypothesis",
     "simple/hyundai",
     "simple/i18next",
+    "simple/i3",
     "simple/iata",
     "simple/ibeacon",
     "simple/ibm",
@@ -10988,6 +11045,7 @@
     "simple/ifixit",
     "simple/ifood",
     "simple/ifttt",
+    "simple/igdb",
     "simple/iheartradio",
     "simple/ikea",
     "simple/iledefrancemobilites",
@@ -10997,10 +11055,13 @@
     "simple/immer",
     "simple/immich",
     "simple/imou",
+    "simple/improvmx",
     "simple/indeed",
+    "simple/indigo",
     "simple/inertia",
     "simple/infiniti",
     "simple/influxdb",
+    "simple/infoq",
     "simple/informatica",
     "simple/infosys",
     "simple/infracost",
@@ -11019,9 +11080,11 @@
     "simple/intellijidea",
     "simple/interactiondesignfoundation",
     "simple/interactjs",
+    "simple/interbase",
     "simple/intercom",
     "simple/intermarche",
     "simple/internetarchive",
+    "simple/internetcomputer",
     "simple/internetexplorer",
     "simple/intigriti",
     "simple/intuit",
@@ -11034,6 +11097,8 @@
     "simple/iota",
     "simple/ipfs",
     "simple/iris",
+    "simple/isc2",
+    "simple/iscsquared",
     "simple/issuu",
     "simple/istio",
     "simple/itchdotio",
@@ -11057,6 +11122,7 @@
     "simple/jenkinsx",
     "simple/jest",
     "simple/jet",
+    "simple/jetblue",
     "simple/jetbrains",
     "simple/jetpackcompose",
     "simple/jfrog",
@@ -11107,6 +11173,7 @@
     "simple/kaufland",
     "simple/kde",
     "simple/kdenlive",
+    "simple/kedro",
     "simple/keepachangelog",
     "simple/keepassxc",
     "simple/kentico",
@@ -11172,6 +11239,7 @@
     "simple/lbry",
     "simple/leaderprice",
     "simple/leaflet",
+    "simple/leagueoflegends",
     "simple/leanpub",
     "simple/leetcode",
     "simple/legacygames",
@@ -11197,6 +11265,7 @@
     "simple/lichess",
     "simple/lidl",
     "simple/lifx",
+    "simple/lightburn",
     "simple/lighthouse",
     "simple/lightning",
     "simple/line",
@@ -11220,6 +11289,7 @@
     "simple/livewire",
     "simple/llvm",
     "simple/lmms",
+    "simple/local",
     "simple/lodash",
     "simple/logitech",
     "simple/logmein",
@@ -11238,6 +11308,7 @@
     "simple/lufthansa",
     "simple/lumen",
     "simple/lunacy",
+    "simple/lutris",
     "simple/lydia",
     "simple/lyft",
     "simple/maas",
@@ -11258,6 +11329,7 @@
     "simple/man",
     "simple/manageiq",
     "simple/manjaro",
+    "simple/mantine",
     "simple/mapbox",
     "simple/maplibre",
     "simple/mariadb",
@@ -11266,12 +11338,14 @@
     "simple/marketo",
     "simple/marko",
     "simple/marriott",
+    "simple/marvelapp",
     "simple/maserati",
     "simple/mastercard",
     "simple/mastercomfig",
     "simple/mastodon",
     "simple/materialdesign",
     "simple/materialdesignicons",
+    "simple/matillion",
     "simple/matomo",
     "simple/matrix",
     "simple/matterdotjs",
@@ -11296,6 +11370,7 @@
     "simple/medium",
     "simple/meetup",
     "simple/mega",
+    "simple/meilisearch",
     "simple/mendeley",
     "simple/mercadopago",
     "simple/mercedes",
@@ -11340,10 +11415,12 @@
     "simple/microstrategy",
     "simple/midi",
     "simple/mikrotik",
+    "simple/milvus",
     "simple/minds",
     "simple/minecraft",
     "simple/minetest",
     "simple/mini",
+    "simple/minio",
     "simple/minutemailer",
     "simple/miraheze",
     "simple/miro",
@@ -11351,6 +11428,7 @@
     "simple/mitsubishi",
     "simple/mix",
     "simple/mixcloud",
+    "simple/mixpanel",
     "simple/mlb",
     "simple/mlflow",
     "simple/mobx",
@@ -11405,11 +11483,13 @@
     "simple/nasa",
     "simple/nationalgrid",
     "simple/nativescript",
+    "simple/natsdotio",
     "simple/naver",
     "simple/nba",
     "simple/nbb",
     "simple/nbc",
     "simple/ndr",
+    "simple/near",
     "simple/nec",
     "simple/neo4j",
     "simple/neovim",
@@ -11482,6 +11562,7 @@
     "simple/ocaml",
     "simple/octanerender",
     "simple/octave",
+    "simple/octobercms",
     "simple/octoprint",
     "simple/octopusdeploy",
     "simple/oculus",
@@ -11524,6 +11605,7 @@
     "simple/openstreetmap",
     "simple/opensuse",
     "simple/opentelemetry",
+    "simple/opentf",
     "simple/openverse",
     "simple/openvpn",
     "simple/openwrt",
@@ -11564,6 +11646,7 @@
     "simple/palantir",
     "simple/paloaltonetworks",
     "simple/paloaltosoftware",
+    "simple/panasonic",
     "simple/pandas",
     "simple/pandora",
     "simple/pantheon",
@@ -11581,6 +11664,7 @@
     "simple/pcgamingwiki",
     "simple/peakdesign",
     "simple/pearson",
+    "simple/peerlist",
     "simple/peertube",
     "simple/pegasusairlines",
     "simple/pelican",
@@ -11607,6 +11691,7 @@
     "simple/php",
     "simple/phpmyadmin",
     "simple/phpstorm",
+    "simple/piaggiogroup",
     "simple/picardsurgeles",
     "simple/picartodottv",
     "simple/picnic",
@@ -11776,6 +11861,7 @@
     "simple/radar",
     "simple/radiopublic",
     "simple/radixui",
+    "simple/radstudio",
     "simple/railway",
     "simple/rainmeter",
     "simple/rakuten",
@@ -11830,6 +11916,7 @@
     "simple/researchgate",
     "simple/resharper",
     "simple/resurrectionremixos",
+    "simple/retool",
     "simple/retroarch",
     "simple/retropie",
     "simple/revanced",
@@ -11850,6 +11937,7 @@
     "simple/riseup",
     "simple/roadmapdotsh",
     "simple/roamresearch",
+    "simple/robinhood",
     "simple/roblox",
     "simple/robloxstudio",
     "simple/robotframework",
@@ -11860,6 +11948,7 @@
     "simple/rollsroyce",
     "simple/rollupdotjs",
     "simple/rome",
+    "simple/rootme",
     "simple/roots",
     "simple/rootsbedrock",
     "simple/rootssage",
@@ -11880,6 +11969,7 @@
     "simple/rubyonrails",
     "simple/rubysinatra",
     "simple/ruff",
+    "simple/rumble",
     "simple/rundeck",
     "simple/runkeeper",
     "simple/runkit",
@@ -11892,12 +11982,14 @@
     "simple/sage",
     "simple/sahibinden",
     "simple/sailfishos",
+    "simple/sailsdotjs",
     "simple/salesforce",
     "simple/saltproject",
     "simple/samsung",
     "simple/samsungpay",
     "simple/sandisk",
     "simple/sanfranciscomunicipalrailway",
+    "simple/sanic",
     "simple/sanity",
     "simple/saopaulometro",
     "simple/sap",
@@ -11913,6 +12005,7 @@
     "simple/scipy",
     "simple/scopus",
     "simple/scpfoundation",
+    "simple/scrapbox",
     "simple/scratch",
     "simple/screencastify",
     "simple/scribd",
@@ -11920,7 +12013,9 @@
     "simple/scrollreveal",
     "simple/scrumalliance",
     "simple/scrutinizerci",
+    "simple/scylladb",
     "simple/seagate",
+    "simple/searxng",
     "simple/seat",
     "simple/securityscorecard",
     "simple/sefaria",
@@ -11959,11 +12054,13 @@
     "simple/shopee",
     "simple/shopify",
     "simple/shopware",
+    "simple/shortcut",
     "simple/shotcut",
     "simple/showpad",
     "simple/showtime",
     "simple/shutterstock",
     "simple/siemens",
+    "simple/sifive",
     "simple/signal",
     "simple/similarweb",
     "simple/simkl",
@@ -11971,6 +12068,7 @@
     "simple/simpleicons",
     "simple/simplenote",
     "simple/sinaweibo",
+    "simple/singaporeairlines",
     "simple/singlestore",
     "simple/sitecore",
     "simple/sitepoint",
@@ -12016,6 +12114,7 @@
     "simple/sonarlint",
     "simple/sonarqube",
     "simple/sonarsource",
+    "simple/sonatype",
     "simple/songkick",
     "simple/songoda",
     "simple/sonicwall",
@@ -12041,6 +12140,8 @@
     "simple/spectrum",
     "simple/speedtest",
     "simple/speedypage",
+    "simple/sphinx",
+    "simple/spigotmc",
     "simple/spinnaker",
     "simple/spinrilla",
     "simple/splunk",
@@ -12135,6 +12236,7 @@
     "simple/swift",
     "simple/swiggy",
     "simple/swiper",
+    "simple/swr",
     "simple/symantec",
     "simple/symbolab",
     "simple/symfony",
@@ -12162,6 +12264,7 @@
     "simple/tata",
     "simple/tauri",
     "simple/taxbuzz",
+    "simple/tcs",
     "simple/teamcity",
     "simple/teamspeak",
     "simple/teamviewer",
@@ -12236,6 +12339,7 @@
     "simple/torbrowser",
     "simple/torproject",
     "simple/toshiba",
+    "simple/tourbox",
     "simple/toyota",
     "simple/tplink",
     "simple/tqdm",
@@ -12289,11 +12393,13 @@
     "simple/ubisoft",
     "simple/ublockorigin",
     "simple/ubuntu",
+    "simple/ubuntumate",
     "simple/udacity",
     "simple/udemy",
     "simple/ufc",
     "simple/uikit",
     "simple/ulule",
+    "simple/umami",
     "simple/umbraco",
     "simple/uml",
     "simple/unacademy",
@@ -12303,8 +12409,10 @@
     "simple/unicode",
     "simple/unilever",
     "simple/unitedairlines",
+    "simple/unitednations",
     "simple/unity",
     "simple/unlicense",
+    "simple/uno",
     "simple/unocss",
     "simple/unraid",
     "simple/unrealengine",
@@ -12320,6 +12428,7 @@
     "simple/uptobox",
     "simple/upwork",
     "simple/usps",
+    "simple/utorrent",
     "simple/v",
     "simple/v2ex",
     "simple/v8",
@@ -12330,6 +12439,7 @@
     "simple/valve",
     "simple/vapor",
     "simple/vault",
+    "simple/vaultwarden",
     "simple/vauxhall",
     "simple/vbulletin",
     "simple/vectorlogozone",
@@ -12343,9 +12453,11 @@
     "simple/verdaccio",
     "simple/veritas",
     "simple/verizon",
+    "simple/vespa",
     "simple/vexxhost",
     "simple/vfairs",
     "simple/viadeo",
+    "simple/viaplay",
     "simple/viber",
     "simple/vim",
     "simple/vimeo",
@@ -12382,6 +12494,7 @@
     "simple/vuetify",
     "simple/vulkan",
     "simple/vultr",
+    "simple/vyond",
     "simple/w3c",
     "simple/wacom",
     "simple/wagtail",
@@ -12423,6 +12536,7 @@
     "simple/wegame",
     "simple/weightsandbiases",
     "simple/welcometothejungle",
+    "simple/wellfound",
     "simple/wemo",
     "simple/westerndigital",
     "simple/wetransfer",
@@ -12470,6 +12584,7 @@
     "simple/writedotas",
     "simple/wwe",
     "simple/wwise",
+    "simple/x",
     "simple/xamarin",
     "simple/xaml",
     "simple/xampp",
@@ -12496,6 +12611,7 @@
     "simple/yarn",
     "simple/ycombinator",
     "simple/yelp",
+    "simple/yeti",
     "simple/yoast",
     "simple/yolo",
     "simple/yourtraveldottv",
@@ -12520,6 +12636,7 @@
     "simple/zendframework",
     "simple/zenn",
     "simple/zenodo",
+    "simple/zensar",
     "simple/zerodha",
     "simple/zeromq",
     "simple/zerply",

docs/schema/extensions/pymdownx.json

@@ -168,11 +168,11 @@
               "properties": {
                 "emoji_generator": {
                   "markdownDescription": "https://squidfunk.github.io/mkdocs-material/setup/extensions/python-markdown-extensions/#+pymdownx.emoji.emoji_generator",
-                  "default": "!!python/name:materialx.emoji.to_svg"
+                  "default": "!!python/name:material.extensions.emoji.to_svg"
                 },
                 "emoji_index": {
                   "markdownDescription": "https://squidfunk.github.io/mkdocs-material/setup/extensions/python-markdown-extensions/#+pymdownx.emoji.emoji_index",
-                  "default": "!!python/name:materialx.emoji.twemoji"
+                  "default": "!!python/name:material.extensions.emoji.twemoji"
                 },
                 "options": {
                   "markdownDescription": "https://squidfunk.github.io/mkdocs-material/setup/extensions/python-markdown-extensions/#+pymdownx.emoji.options.custom_icons",
@@ -224,6 +224,10 @@
                   "markdownDescription": "https://squidfunk.github.io/mkdocs-material/setup/extensions/python-markdown-extensions/#+pymdownx.highlight.use_pygments",
                   "type": "boolean"
                 },
+                "pygments_lang_class": {
+                  "markdownDescription": "https://squidfunk.github.io/mkdocs-material/setup/extensions/python-markdown-extensions/#+pymdownx.highlight.pygments_lang_class",
+                  "type": "boolean"
+                },
                 "auto_title": {
                   "markdownDescription": "https://squidfunk.github.io/mkdocs-material/setup/extensions/python-markdown-extensions/#+pymdownx.highlight.auto_title",
                   "type": "boolean"
@@ -247,6 +251,10 @@
                 "anchor_linenums": {
                   "markdownDescription": "https://squidfunk.github.io/mkdocs-material/setup/extensions/python-markdown-extensions/#+pymdownx.highlight.anchor_linenums",
                   "type": "boolean"
+                },
+                "line_spans": {
+                  "markdownDescription": "https://squidfunk.github.io/mkdocs-material/setup/extensions/python-markdown-extensions/#+pymdownx.highlight.line_spans",
+                  "type": "string"
                 }
               },
               "additionalProperties": false
@@ -536,6 +544,21 @@
                   "markdownDescription": "https://facelessuser.github.io/pymdown-extensions/extensions/snippets/#options",
                   "type": "boolean",
                   "default": false
+                },
+                "url_max_size": {
+                  "markdownDescription": "https://facelessuser.github.io/pymdown-extensions/extensions/snippets/#options",
+                  "type": "integer",
+                  "default": 33554432
+                },
+                "url_timeout": {
+                  "markdownDescription": "https://facelessuser.github.io/pymdown-extensions/extensions/snippets/#options",
+                  "type": "number",
+                  "default": 10.0
+                },
+                "url_request_headers": {
+                  "markdownDescription": "https://facelessuser.github.io/pymdown-extensions/extensions/snippets/#options",
+                  "type": "object",
+                  "default": {}
                 }
               },
               "additionalProperties": false
@@ -617,6 +640,11 @@
               ],
               "default": true
             },
+            "combine_header_slug": {
+              "markdownDescription": "https://squidfunk.github.io/mkdocs-material/setup/extensions/python-markdown-extensions/#+pymdownx.tabbed.combine_header_slug",
+              "type": "boolean",
+              "default": true
+            },
             "slugify": {
               "markdownDescription": "https://squidfunk.github.io/mkdocs-material/setup/extensions/python-markdown-extensions/#+pymdownx.tabbed.slugify",
               "default": "!!python/object/apply:pymdownx.slugs.slugify {kwds: {case: lower}}"

docs/schema/extra.json

@@ -132,6 +132,22 @@
         }
       ]
     },
+    "annotate": {
+      "title": "Custom selectors for annotations",
+      "markdownDescription": "https://squidfunk.github.io/mkdocs-material/reference/code-blocks/#custom-selectors",
+      "type": "object",
+      "patternProperties": {
+        ".*": {
+          "title": "Custom selector",
+          "markdownDescription": "https://squidfunk.github.io/mkdocs-material/reference/code-blocks/#custom-selectors",
+          "type": "array",
+          "items": {
+            "type": "string",
+            "pattern": "^\\.\\w+"
+          }
+        }
+      }
+    },
     "consent": {
       "title": "Cookie consent",
       "markdownDescription": "https://squidfunk.github.io/mkdocs-material/setup/ensuring-data-privacy/#cookie-consent",

docs/schema/plugins.json

@@ -25,6 +25,9 @@
         {
           "$ref": "plugins/blog.json"
         },
+        {
+          "$ref": "plugins/group.json"
+        },
         {
           "$ref": "plugins/info.json"
         },
@@ -90,7 +93,7 @@
       ]
     },
     "external-community": {
-      "description": "External plugins, schema provided by the community",
+      "description": "External plugins, schema provided by our community",
       "anyOf": [
         {
           "$ref": "https://raw.githubusercontent.com/mondeja/mkdocs-include-markdown-plugin/master/schema.json"

docs/schema/plugins/blog.json

@@ -3,7 +3,7 @@
   "title": "Built-in blog plugin",
   "oneOf": [
     {
-      "markdownDescription": "https://squidfunk.github.io/mkdocs-material/setup/setting-up-a-blog/#built-in-blog-plugin",
+      "markdownDescription": "https://squidfunk.github.io/mkdocs-material/plugins/blog/",
       "enum": [
         "blog"
       ]
@@ -12,30 +12,37 @@
       "type": "object",
       "properties": {
         "blog": {
-          "markdownDescription": "https://squidfunk.github.io/mkdocs-material/setup/setting-up-a-blog/#built-in-blog-plugin",
+          "markdownDescription": "https://squidfunk.github.io/mkdocs-material/plugins/blog/",
           "type": "object",
           "properties": {
             "enabled": {
               "title": "Enable plugin",
-              "markdownDescription": "https://squidfunk.github.io/mkdocs-material/setup/setting-up-a-blog/#+blog.enabled",
+              "markdownDescription": "https://squidfunk.github.io/mkdocs-material/plugins/blog/#config.enabled",
               "type": "boolean",
               "default": true
             },
             "blog_dir": {
               "title": "Blog directory",
-              "markdownDescription": "https://squidfunk.github.io/mkdocs-material/setup/setting-up-a-blog/#+blog.blog_dir",
+              "markdownDescription": "https://squidfunk.github.io/mkdocs-material/plugins/blog/#config.blog_dir",
               "type": "string",
               "default": "blog"
             },
             "blog_toc": {
               "title": "Blog table of contents",
-              "markdownDescription": "https://squidfunk.github.io/mkdocs-material/setup/setting-up-a-blog/#+blog.blog_toc",
+              "markdownDescription": "https://squidfunk.github.io/mkdocs-material/plugins/blog/#config.blog_toc",
               "type": "boolean",
               "default": false
             },
+            "post_dir": {
+              "title": "Blog posts directory",
+              "markdownDescription": "https://squidfunk.github.io/mkdocs-material/plugins/blog/#config.post_dir",
+              "type": "string",
+              "default": "\"{blog\\}/posts\""
+            },
             "post_date_format": {
               "title": "Format string for post dates",
-              "markdownDescription": "https://squidfunk.github.io/mkdocs-material/setup/setting-up-a-blog/#+blog.post_date_format",
+              "markdownDescription": "https://squidfunk.github.io/mkdocs-material/plugins/blog/#config.post_date_format",
+              "default": "long",
               "oneOf": [
                 {
                   "enum": [
@@ -48,12 +55,11 @@
                 {
                   "type": "string"
                 }
-              ],
+              ]
-              "default": "long"
             },
             "post_url_date_format": {
               "title": "Format string for post dates in URLs",
-              "markdownDescription": "https://squidfunk.github.io/mkdocs-material/setup/setting-up-a-blog/#+blog.post_url_date_format",
+              "markdownDescription": "https://squidfunk.github.io/mkdocs-material/plugins/blog/#config.post_url_date_format",
               "oneOf": [
                 {
                   "enum": [
@@ -70,7 +76,7 @@
             },
             "post_url_format": {
               "title": "Format string for post URLs",
-              "markdownDescription": "https://squidfunk.github.io/mkdocs-material/setup/setting-up-a-blog/#+blog.post_url_format",
+              "markdownDescription": "https://squidfunk.github.io/mkdocs-material/plugins/blog/#config.post_url_format",
               "oneOf": [
                 {
                   "enum": [
@@ -87,24 +93,24 @@
             },
             "post_url_max_categories": {
               "title": "Number of categories in post URLs",
-              "markdownDescription": "https://squidfunk.github.io/mkdocs-material/setup/setting-up-a-blog/#+blog.post_url_max_categories",
+              "markdownDescription": "https://squidfunk.github.io/mkdocs-material/plugins/blog/#config.post_url_max_categories",
               "type": "number",
               "default": 1
             },
             "post_slugify": {
               "title": "Post slugify function",
-              "markdownDescription": "https://squidfunk.github.io/mkdocs-material/setup/setting-up-a-blog/#+blog.post_slugify",
+              "markdownDescription": "https://squidfunk.github.io/mkdocs-material/plugins/blog/#config.post_slugify",
               "default": "!!python/object/apply:pymdownx.slugs.slugify {kwds: {case: lower}}"
             },
             "post_slugify_separator": {
               "title": "Post slugify separator",
-              "markdownDescription": "https://squidfunk.github.io/mkdocs-material/setup/setting-up-a-blog/#+blog.post_slugify_separator",
+              "markdownDescription": "https://squidfunk.github.io/mkdocs-material/plugins/blog/#config.post_slugify_separator",
               "type": "string",
               "default": "\"-\""
             },
             "post_excerpt": {
               "title": "Post excerpts",
-              "markdownDescription": "https://squidfunk.github.io/mkdocs-material/setup/setting-up-a-blog/#+blog.post_excerpt",
+              "markdownDescription": "https://squidfunk.github.io/mkdocs-material/plugins/blog/#config.post_excerpt",
               "oneOf": [
                 {
                   "title": "Post excerpts are optional",
@@ -123,49 +129,49 @@
             },
             "post_excerpt_max_authors": {
               "title": "Number of authors to render in post excerpts",
-              "markdownDescription": "https://squidfunk.github.io/mkdocs-material/setup/setting-up-a-blog/#+blog.post_excerpt_max_authors",
+              "markdownDescription": "https://squidfunk.github.io/mkdocs-material/plugins/blog/#config.post_excerpt_max_authors",
               "type": "number",
               "default": 1
             },
             "post_excerpt_max_categories": {
               "title": "Number of categories to render in post excerpts",
-              "markdownDescription": "https://squidfunk.github.io/mkdocs-material/setup/setting-up-a-blog/#+blog.post_excerpt_max_categories",
+              "markdownDescription": "https://squidfunk.github.io/mkdocs-material/plugins/blog/#config.post_excerpt_max_categories",
               "type": "number",
               "default": 5
             },
             "post_excerpt_separator": {
               "title": "Post excerpt separator",
-              "markdownDescription": "https://squidfunk.github.io/mkdocs-material/setup/setting-up-a-blog/#+blog.post_excerpt_separator",
+              "markdownDescription": "https://squidfunk.github.io/mkdocs-material/plugins/blog/#config.post_excerpt_separator",
               "type": "string",
               "default": "<!-- more -->"
             },
             "post_readtime": {
               "title": "Post reading time computation",
-              "markdownDescription": "https://squidfunk.github.io/mkdocs-material/setup/setting-up-a-blog/#+blog.post_readtime",
+              "markdownDescription": "https://squidfunk.github.io/mkdocs-material/plugins/blog/#config.post_readtime",
               "type": "boolean",
               "default": true
             },
             "post_readtime_words_per_minute": {
               "title": "Post reading time words per minute",
-              "markdownDescription": "https://squidfunk.github.io/mkdocs-material/setup/setting-up-a-blog/#+blog.post_readtime_words_per_minute",
+              "markdownDescription": "https://squidfunk.github.io/mkdocs-material/plugins/blog/#config.post_readtime_words_per_minute",
               "type": "number",
               "default": 265
             },
             "archive": {
               "title": "Archive",
-              "markdownDescription": "https://squidfunk.github.io/mkdocs-material/setup/setting-up-a-blog/#+blog.archive",
+              "markdownDescription": "https://squidfunk.github.io/mkdocs-material/plugins/blog/#config.archive",
               "type": "boolean",
               "default": true
             },
             "archive_name": {
               "title": "Archive name",
-              "markdownDescription": "https://squidfunk.github.io/mkdocs-material/setup/setting-up-a-blog/#+blog.archive_name",
+              "markdownDescription": "https://squidfunk.github.io/mkdocs-material/plugins/blog/#config.archive_name",
               "type": "string",
               "default": "Archive"
             },
             "archive_date_format": {
               "title": "Format string for archive dates",
-              "markdownDescription": "https://squidfunk.github.io/mkdocs-material/setup/setting-up-a-blog/#+blog.archive_date_format",
+              "markdownDescription": "https://squidfunk.github.io/mkdocs-material/plugins/blog/#config.archive_date_format",
               "oneOf": [
                 {
                   "enum": [
@@ -181,7 +187,7 @@
             },
             "archive_url_date_format": {
               "title": "Format string for archive dates in URLs",
-              "markdownDescription": "https://squidfunk.github.io/mkdocs-material/setup/setting-up-a-blog/#+blog.archive_url_date_format",
+              "markdownDescription": "https://squidfunk.github.io/mkdocs-material/plugins/blog/#config.archive_url_date_format",
               "oneOf": [
                 {
                   "enum": [
@@ -197,7 +203,7 @@
             },
             "archive_url_format": {
               "title": "Format string for archive URLs",
-              "markdownDescription": "https://squidfunk.github.io/mkdocs-material/setup/setting-up-a-blog/#+blog.archive_url_format",
+              "markdownDescription": "https://squidfunk.github.io/mkdocs-material/plugins/blog/#config.archive_url_format",
               "oneOf": [
                 {
                   "enum": [
@@ -211,25 +217,25 @@
             },
             "archive_toc": {
               "title": "Archive table of contents",
-              "markdownDescription": "https://squidfunk.github.io/mkdocs-material/setup/setting-up-a-blog/#+blog.archive_toc",
+              "markdownDescription": "https://squidfunk.github.io/mkdocs-material/plugins/blog/#config.archive_toc",
               "type": "boolean",
               "default": false
             },
             "categories": {
               "title": "Categories",
-              "markdownDescription": "https://squidfunk.github.io/mkdocs-material/setup/setting-up-a-blog/#+blog.categories",
+              "markdownDescription": "https://squidfunk.github.io/mkdocs-material/plugins/blog/#config.categories",
               "type": "boolean",
               "default": true
             },
             "categories_name": {
               "title": "Categories name",
-              "markdownDescription": "https://squidfunk.github.io/mkdocs-material/setup/setting-up-a-blog/#+blog.categories_name",
+              "markdownDescription": "https://squidfunk.github.io/mkdocs-material/plugins/blog/#config.categories_name",
               "type": "string",
               "default": "Categories"
             },
             "categories_url_format": {
               "title": "Format string for category URLs",
-              "markdownDescription": "https://squidfunk.github.io/mkdocs-material/setup/setting-up-a-blog/#+blog.categories_url_format",
+              "markdownDescription": "https://squidfunk.github.io/mkdocs-material/plugins/blog/#config.categories_url_format",
               "oneOf": [
                 {
                   "enum": [
@@ -244,18 +250,18 @@
             },
             "categories_slugify": {
               "title": "Categories slugify function",
-              "markdownDescription": "https://squidfunk.github.io/mkdocs-material/setup/setting-up-a-blog/#+blog.categories_slugify",
+              "markdownDescription": "https://squidfunk.github.io/mkdocs-material/plugins/blog/#config.categories_slugify",
               "default": "!!python/object/apply:pymdownx.slugs.slugify {kwds: {case: lower}}"
             },
             "categories_slugify_separator": {
               "title": "Categories slugify separator",
-              "markdownDescription": "https://squidfunk.github.io/mkdocs-material/setup/setting-up-a-blog/#+blog.categories_slugify_separator",
+              "markdownDescription": "https://squidfunk.github.io/mkdocs-material/plugins/blog/#config.categories_slugify_separator",
               "type": "string",
               "default": "\"-\""
             },
             "categories_allowed": {
               "title": "Categories allowed",
-              "markdownDescription": "https://squidfunk.github.io/mkdocs-material/setup/setting-up-a-blog/#+blog.categories_allowed",
+              "markdownDescription": "https://squidfunk.github.io/mkdocs-material/plugins/blog/#config.categories_allowed",
               "type": "array",
               "items": {
                 "type": "string"
@@ -265,25 +271,25 @@
             },
             "categories_toc": {
               "title": "Categories table of contents",
-              "markdownDescription": "https://squidfunk.github.io/mkdocs-material/setup/setting-up-a-blog/#+blog.categories_toc",
+              "markdownDescription": "https://squidfunk.github.io/mkdocs-material/plugins/blog/#config.categories_toc",
               "type": "boolean",
               "default": false
             },
             "pagination": {
               "title": "Pagination",
-              "markdownDescription": "https://squidfunk.github.io/mkdocs-material/setup/setting-up-a-blog/#+blog.pagination",
+              "markdownDescription": "https://squidfunk.github.io/mkdocs-material/plugins/blog/#config.pagination",
               "type": "boolean",
               "default": true
             },
             "pagination_per_page": {
               "title": "Posts per page",
-              "markdownDescription": "https://squidfunk.github.io/mkdocs-material/setup/setting-up-a-blog/#+blog.pagination_per_page",
+              "markdownDescription": "https://squidfunk.github.io/mkdocs-material/plugins/blog/#config.pagination_per_page",
               "type": "number",
               "default": 10
             },
             "pagination_url_format": {
               "title": "Format string for pagination URLs",
-              "markdownDescription": "https://squidfunk.github.io/mkdocs-material/setup/setting-up-a-blog/#+blog.pagination_url_format",
+              "markdownDescription": "https://squidfunk.github.io/mkdocs-material/plugins/blog/#config.pagination_url_format",
               "oneOf": [
                 {
                   "enum": [
@@ -298,7 +304,7 @@
             },
             "pagination_template": {
               "title": "Template string for pagination",
-              "markdownDescription": "https://squidfunk.github.io/mkdocs-material/setup/setting-up-a-blog/#+blog.pagination_template",
+              "markdownDescription": "https://squidfunk.github.io/mkdocs-material/plugins/blog/#config.pagination_template",
               "oneOf": [
                 {
                   "enum": [
@@ -315,37 +321,37 @@
             },
             "pagination_keep_content": {
               "title": "Paginated indexes inherit content",
-              "markdownDescription": "https://squidfunk.github.io/mkdocs-material/setup/setting-up-a-blog/#+blog.pagination_keep_content",
+              "markdownDescription": "https://squidfunk.github.io/mkdocs-material/plugins/blog/#config.pagination_keep_content",
               "type": "boolean",
               "default": false
             },
             "authors": {
               "title": "Author info",
-              "markdownDescription": "https://squidfunk.github.io/mkdocs-material/setup/setting-up-a-blog/#+blog.authors",
+              "markdownDescription": "https://squidfunk.github.io/mkdocs-material/plugins/blog/#config.authors",
               "type": "boolean",
               "default": true
             },
             "authors_file": {
               "title": "Authors file",
-              "markdownDescription": "https://squidfunk.github.io/mkdocs-material/setup/setting-up-a-blog/#+blog.authors_file",
+              "markdownDescription": "https://squidfunk.github.io/mkdocs-material/plugins/blog/#config.authors_file",
               "type": "string",
-              "default": ".authors.yml"
+              "default": "\"{blog\\}/.authors.yml\""
             },
             "draft": {
               "title": "Render posts marked as drafts",
-              "markdownDescription": "https://squidfunk.github.io/mkdocs-material/setup/setting-up-a-blog/#+blog.draft",
+              "markdownDescription": "https://squidfunk.github.io/mkdocs-material/plugins/blog/#config.draft",
               "type": "boolean",
               "default": false
             },
             "draft_on_serve": {
               "title": "Render posts marked as drafts when previewing",
-              "markdownDescription": "https://squidfunk.github.io/mkdocs-material/setup/setting-up-a-blog/#+blog.draft_on_serve",
+              "markdownDescription": "https://squidfunk.github.io/mkdocs-material/plugins/blog/#config.draft_on_serve",
               "type": "boolean",
               "default": true
             },
             "draft_if_future_date": {
               "title": "Automatically mark posts with future dates as drafts",
-              "markdownDescription": "https://squidfunk.github.io/mkdocs-material/setup/setting-up-a-blog/#+blog.draft_if_future_date",
+              "markdownDescription": "https://squidfunk.github.io/mkdocs-material/plugins/blog/#config.draft_if_future_date",
               "type": "boolean",
               "default": false
             }

docs/schema/plugins/group.json

@@ -0,0 +1,29 @@
+{
+  "$schema": "https://json-schema.org/draft-07/schema",
+  "title": "Built-in group plugin",
+  "oneOf": [
+    {
+      "type": "object",
+      "properties": {
+        "group": {
+          "markdownDescription": "https://squidfunk.github.io/mkdocs-material/plugins/group/",
+          "type": "object",
+          "properties": {
+            "enabled": {
+              "title": "Enable plugin",
+              "markdownDescription": "https://squidfunk.github.io/mkdocs-material/plugins/group/#config.enabled",
+              "type": "boolean",
+              "default": true
+            },
+            "plugins": {
+              "markdownDescription": "https://squidfunk.github.io/mkdocs-material/plugins/group/#config.plugins",
+              "$ref": "../plugins.json"
+            }
+          },
+          "additionalProperties": false
+        }
+      },
+      "additionalProperties": false
+    }
+  ]
+}

docs/schema/plugins/info.json

@@ -3,7 +3,7 @@
   "title": "Built-in info plugin",
   "oneOf": [
     {
-      "markdownDescription": "https://squidfunk.github.io/mkdocs-material/reporting-an-issue/#creating-a-zip-file",
+      "markdownDescription": "https://squidfunk.github.io/mkdocs-material/plugins/info/",
       "enum": [
         "info"
       ]
@@ -12,12 +12,30 @@
       "type": "object",
       "properties": {
         "info": {
-          "markdownDescription": "https://squidfunk.github.io/mkdocs-material/reporting-an-issue/#creating-a-zip-file",
+          "markdownDescription": "https://squidfunk.github.io/mkdocs-material/plugins/info/",
           "type": "object",
           "properties": {
             "enabled": {
               "title": "Enable plugin",
-              "markdownDescription": "https://squidfunk.github.io/mkdocs-material/reporting-an-issue/#creating-a-zip-file",
+              "markdownDescription": "https://squidfunk.github.io/mkdocs-material/plugins/info/#config.enabled",
+              "type": "boolean",
+              "default": true
+            },
+            "enabled_on_serve": {
+              "title": "Enable plugin when previewing",
+              "markdownDescription": "https://squidfunk.github.io/mkdocs-material/plugins/info/#config.enabled_on_serve",
+              "type": "boolean",
+              "default": false
+            },
+            "archive": {
+              "title": "Enable creation of archive",
+              "markdownDescription": "https://squidfunk.github.io/mkdocs-material/plugins/info/#config.archive",
+              "type": "boolean",
+              "default": true
+            },
+            "archive_stop_on_violation": {
+              "title": "Stop creation of archive on violation",
+              "markdownDescription": "https://squidfunk.github.io/mkdocs-material/plugins/info/#config.archive_stop_on_violation",
               "type": "boolean",
               "default": true
             }

docs/schema/plugins/meta.json

@@ -3,7 +3,7 @@
   "title": "Built-in meta plugin",
   "oneOf": [
     {
-      "markdownDescription": "https://squidfunk.github.io/mkdocs-material/reference/#built-in-meta-plugin",
+      "markdownDescription": "https://squidfunk.github.io/mkdocs-material/plugins/meta/",
       "enum": [
         "meta"
       ]
@@ -12,12 +12,18 @@
       "type": "object",
       "properties": {
         "meta": {
-          "markdownDescription": "https://squidfunk.github.io/mkdocs-material/reference/#built-in-meta-plugin",
+          "markdownDescription": "https://squidfunk.github.io/mkdocs-material/plugins/meta/",
           "type": "object",
           "properties": {
+            "enabled": {
+              "title": "Enable plugin",
+              "markdownDescription": "https://squidfunk.github.io/mkdocs-material/plugins/meta/#config.enabled",
+              "type": "boolean",
+              "default": true
+            },
             "meta_file": {
               "title": "Meta file name",
-              "markdownDescription": "https://squidfunk.github.io/mkdocs-material/reference/#+meta.meta_file",
+              "markdownDescription": "https://squidfunk.github.io/mkdocs-material/plugins/meta/#config.meta_file",
               "pattern": "\\.yml$",
               "default": "\"**/.meta.yml\""
             }

docs/schema/plugins/offline.json

@@ -3,7 +3,7 @@
   "title": "Built-in offline plugin",
   "oneOf": [
     {
-      "markdownDescription": "https://squidfunk.github.io/mkdocs-material/setup/building-for-offline-usage/#built-in-offline-plugin",
+      "markdownDescription": "https://squidfunk.github.io/mkdocs-material/plugins/offline/",
       "enum": [
         "offline"
       ]
@@ -12,12 +12,12 @@
       "type": "object",
       "properties": {
         "offline": {
-          "markdownDescription": "https://squidfunk.github.io/mkdocs-material/setup/building-for-offline-usage/#built-in-offline-plugin",
+          "markdownDescription": "https://squidfunk.github.io/mkdocs-material/plugins/offline/",
           "type": "object",
           "properties": {
             "enabled": {
               "title": "Enable plugin",
-              "markdownDescription": "https://squidfunk.github.io/mkdocs-material/setup/building-for-offline-usage/#+offline.enabled",
+              "markdownDescription": "https://squidfunk.github.io/mkdocs-material/plugins/offline/#config.enabled",
               "type": "boolean",
               "default": true
             }

docs/schema/plugins/optimize.json

@@ -3,7 +3,7 @@
   "title": "Built-in optimize plugin",
   "oneOf": [
     {
-      "markdownDescription": "https://squidfunk.github.io/mkdocs-material/setup/building-an-optimized-site/#built-in-optimize-plugin",
+      "markdownDescription": "https://squidfunk.github.io/mkdocs-material/plugins/optimize/",
       "enum": [
         "optimize"
       ]
@@ -12,75 +12,101 @@
       "type": "object",
       "properties": {
         "optimize": {
-          "markdownDescription": "https://squidfunk.github.io/mkdocs-material/setup/building-an-optimized-site/#built-in-optimize-plugin",
+          "markdownDescription": "https://squidfunk.github.io/mkdocs-material/plugins/optimize/",
           "type": "object",
           "properties": {
             "enabled": {
               "title": "Enable plugin",
-              "markdownDescription": "https://squidfunk.github.io/mkdocs-material/setup/building-an-optimized-site/#+optimize.enabled",
+              "markdownDescription": "https://squidfunk.github.io/mkdocs-material/plugins/optimize/#config.enabled",
               "type": "boolean",
               "default": true
             },
             "concurrency": {
               "title": "Concurrency (number of CPUs)",
-              "markdownDescription": "https://squidfunk.github.io/mkdocs-material/setup/building-an-optimized-site/#+optimize.concurrency",
+              "markdownDescription": "https://squidfunk.github.io/mkdocs-material/plugins/optimize/#config.concurrency",
               "type": "number"
             },
             "cache": {
               "title": "Enable caching",
-              "markdownDescription": "https://squidfunk.github.io/mkdocs-material/setup/building-an-optimized-site/#+optimize.cache",
+              "markdownDescription": "https://squidfunk.github.io/mkdocs-material/plugins/optimize/#config.cache",
               "type": "boolean",
               "default": true
             },
             "cache_dir": {
               "title": "Cache directory",
-              "markdownDescription": "https://squidfunk.github.io/mkdocs-material/setup/building-an-optimized-site/#+optimize.cache_dir",
+              "markdownDescription": "https://squidfunk.github.io/mkdocs-material/plugins/optimize/#config.cache_dir",
               "type": "string",
-              "default": ".cache/plugins/social"
+              "default": ".cache/plugins/optimize"
             },
             "optimize_png": {
               "title": "Optimization of PNGs",
-              "markdownDescription": "https://squidfunk.github.io/mkdocs-material/setup/building-an-optimized-site/#+optimize.optimize_png",
+              "markdownDescription": "https://squidfunk.github.io/mkdocs-material/plugins/optimize/#config.optimize_png",
               "type": "boolean",
               "default": true
             },
             "optimize_png_speed": {
               "title": "Speed/quality tradeoff [1,10]",
-              "markdownDescription": "https://squidfunk.github.io/mkdocs-material/setup/building-an-optimized-site/#+optimize.optimize_png_speed",
+              "markdownDescription": "https://squidfunk.github.io/mkdocs-material/plugins/optimize/#config.optimize_png_speed",
               "type": "number",
               "default": 4
             },
             "optimize_png_strip": {
               "title": "Strip unnecessary metadata from PNGs",
-              "markdownDescription": "https://squidfunk.github.io/mkdocs-material/setup/building-an-optimized-site/#+optimize.optimize_png_strip",
+              "markdownDescription": "https://squidfunk.github.io/mkdocs-material/plugins/optimize/#config.optimize_png_strip",
               "type": "boolean",
               "default": true
             },
             "optimize_jpg": {
               "title": "Optimization of JPGs",
-              "markdownDescription": "https://squidfunk.github.io/mkdocs-material/setup/building-an-optimized-site/#+optimize.optimize_jpg",
+              "markdownDescription": "https://squidfunk.github.io/mkdocs-material/plugins/optimize/#config.optimize_jpg",
               "type": "boolean",
               "default": true
             },
             "optimize_jpg_quality": {
               "title": "Speed/quality tradeoff for pngquant [0,10]",
-              "markdownDescription": "https://squidfunk.github.io/mkdocs-material/setup/building-an-optimized-site/#+optimize.optimize_jpg_quality",
+              "markdownDescription": "https://squidfunk.github.io/mkdocs-material/plugins/optimize/#config.optimize_jpg_quality",
               "type": "number",
               "default": 60
             },
             "optimize_jpg_progressive": {
               "title": "Progressive encoding (faster rendering)",
-              "markdownDescription": "https://squidfunk.github.io/mkdocs-material/setup/building-an-optimized-site/#+optimize.optimize_jpg_progressive",
+              "markdownDescription": "https://squidfunk.github.io/mkdocs-material/plugins/optimize/#config.optimize_jpg_progressive",
               "type": "boolean",
               "default": true
             },
+            "optimize_include": {
+              "title": "Files or folders to include",
+              "markdownDescription": "https://squidfunk.github.io/mkdocs-material/plugins/optimize/#config.optimize_include",
+              "type": "array",
+              "items": {
+                "title": "Files or folders matching this pattern will be included",
+                "markdownDescription": "https://squidfunk.github.io/mkdocs-material/plugins/optimize/#config.optimize_include",
+                "pattern": ".*"
+              },
+              "uniqueItems": true,
+              "minItems": 1
+            },
+            "optimize_exclude": {
+              "title": "Files or folders to exclude",
+              "markdownDescription": "https://squidfunk.github.io/mkdocs-material/plugins/optimize/#config.optimize_exclude",
+              "type": "array",
+              "items": {
+                "title": "Files or folders matching this pattern will be excluded",
+                "markdownDescription": "https://squidfunk.github.io/mkdocs-material/plugins/optimize/#config.optimize_exclude",
+                "pattern": ".*"
+              },
+              "uniqueItems": true,
+              "minItems": 1
+            },
             "print_gain": {
               "title": "Print optimization gain",
+              "markdownDescription": "https://squidfunk.github.io/mkdocs-material/plugins/optimize/#config.print_gain",
               "type": "boolean",
               "default": true
             },
             "print_gain_summary": {
               "title": "Print optimization gain summary",
+              "markdownDescription": "https://squidfunk.github.io/mkdocs-material/plugins/optimize/#config.print_gain_summary",
               "type": "boolean",
               "default": true
             }

docs/schema/plugins/privacy.json

@@ -3,7 +3,7 @@
   "title": "Built-in privacy plugin",
   "oneOf": [
     {
-      "markdownDescription": "https://squidfunk.github.io/mkdocs-material/setup/ensuring-data-privacy/#built-in-privacy-plugin",
+      "markdownDescription": "https://squidfunk.github.io/mkdocs-material/plugins/privacy/",
       "enum": [
         "privacy"
       ]
@@ -12,45 +12,57 @@
       "type": "object",
       "properties": {
         "privacy": {
-          "markdownDescription": "https://squidfunk.github.io/mkdocs-material/setup/ensuring-data-privacy/#built-in-privacy-plugin",
+          "markdownDescription": "https://squidfunk.github.io/mkdocs-material/plugins/privacy/",
           "type": "object",
           "properties": {
             "enabled": {
               "title": "Enable plugin",
-              "markdownDescription": "https://squidfunk.github.io/mkdocs-material/setup/ensuring-data-privacy/#+privacy.enabled",
+              "markdownDescription": "https://squidfunk.github.io/mkdocs-material/plugins/privacy/#config.enabled",
               "type": "boolean",
               "default": true
             },
             "concurrency": {
               "title": "Concurrency (number of CPUs)",
-              "markdownDescription": "https://squidfunk.github.io/mkdocs-material/setup/ensuring-data-privacy/#+privacy.concurrency",
+              "markdownDescription": "https://squidfunk.github.io/mkdocs-material/plugins/privacy/#config.concurrency",
               "type": "number"
             },
+            "cache": {
+              "title": "Enable caching",
+              "markdownDescription": "https://squidfunk.github.io/mkdocs-material/plugins/privacy/#config.cache",
+              "type": "boolean",
+              "default": true
+            },
+            "cache_dir": {
+              "title": "Cache directory",
+              "markdownDescription": "https://squidfunk.github.io/mkdocs-material/plugins/privacy/#config.cache_dir",
+              "type": "string",
+              "default": ".cache/plugins/privacy"
+            },
             "assets": {
               "title": "Process external assets",
-              "markdownDescription": "https://squidfunk.github.io/mkdocs-material/setup/ensuring-data-privacy/#+privacy.assets",
+              "markdownDescription": "https://squidfunk.github.io/mkdocs-material/plugins/privacy/#config.assets",
               "type": "boolean",
               "default": true
             },
             "assets_fetch": {
               "title": "Download external assets",
-              "markdownDescription": "https://squidfunk.github.io/mkdocs-material/setup/ensuring-data-privacy/#+privacy.assets_fetch",
+              "markdownDescription": "https://squidfunk.github.io/mkdocs-material/plugins/privacy/#config.assets_fetch",
               "type": "boolean",
               "default": true
             },
             "assets_fetch_dir": {
               "title": "Download external assets to this directory",
-              "markdownDescription": "https://squidfunk.github.io/mkdocs-material/setup/ensuring-data-privacy/#+privacy.assets_fetch_dir",
+              "markdownDescription": "https://squidfunk.github.io/mkdocs-material/plugins/privacy/#config.assets_fetch_dir",
               "type": "string",
               "default": "assets/external"
             },
             "assets_include": {
               "title": "External assets to include",
-              "markdownDescription": "https://squidfunk.github.io/mkdocs-material/setup/ensuring-data-privacy/#+privacy.assets_include",
+              "markdownDescription": "https://squidfunk.github.io/mkdocs-material/plugins/privacy/#config.assets_include",
               "type": "array",
               "items": {
                 "title": "External assets matching this pattern will be downloaded",
-                "markdownDescription": "https://squidfunk.github.io/mkdocs-material/setup/ensuring-data-privacy/#+privacy.assets_include",
+                "markdownDescription": "https://squidfunk.github.io/mkdocs-material/plugins/privacy/#config.assets_include",
                 "pattern": ".*"
               },
               "uniqueItems": true,
@@ -58,11 +70,11 @@
             },
             "assets_exclude": {
               "title": "External assets to exclude",
-              "markdownDescription": "https://squidfunk.github.io/mkdocs-material/setup/ensuring-data-privacy/#+privacy.assets_exclude",
+              "markdownDescription": "https://squidfunk.github.io/mkdocs-material/plugins/privacy/#config.assets_exclude",
               "type": "array",
               "items": {
                 "title": "External assets matching this pattern will not be downloaded",
-                "markdownDescription": "https://squidfunk.github.io/mkdocs-material/setup/ensuring-data-privacy/#+privacy.assets_exclude",
+                "markdownDescription": "https://squidfunk.github.io/mkdocs-material/plugins/privacy/#config.assets_exclude",
                 "pattern": ".*"
               },
               "uniqueItems": true,
@@ -70,13 +82,13 @@
             },
             "links": {
               "title": "Process external links",
-              "markdownDescription": "https://squidfunk.github.io/mkdocs-material/setup/ensuring-data-privacy/#+privacy.links",
+              "markdownDescription": "https://squidfunk.github.io/mkdocs-material/plugins/privacy/#config.links",
               "type": "boolean",
               "default": true
             },
             "links_attr_map": {
               "title": "Custom attributes to add to external links",
-              "markdownDescription": "https://squidfunk.github.io/mkdocs-material/setup/ensuring-data-privacy/#+privacy.links_attr_map",
+              "markdownDescription": "https://squidfunk.github.io/mkdocs-material/plugins/privacy/#config.links_attr_map",
               "type": "object",
               "patternProperties": {
                 "^[\\w_]+$": {
@@ -86,7 +98,7 @@
             },
             "links_noopener": {
               "title": "Behavior for external links that open in new windows",
-              "markdownDescription": "https://squidfunk.github.io/mkdocs-material/setup/ensuring-data-privacy/#+privacy.links_noopener",
+              "markdownDescription": "https://squidfunk.github.io/mkdocs-material/plugins/privacy/#config.links_noopener",
               "type": "boolean",
               "default": true
             }

docs/schema/plugins/projects.json

@@ -3,7 +3,7 @@
   "title": "Built-in projects plugin",
   "oneOf": [
     {
-      "markdownDescription": "https://squidfunk.github.io/mkdocs-material/setup/building-an-optimized-site/#built-in-projects-plugin",
+      "markdownDescription": "https://squidfunk.github.io/mkdocs-material/plugins/projects/",
       "enum": [
         "projects"
       ]
@@ -12,31 +12,65 @@
       "type": "object",
       "properties": {
         "projects": {
-          "markdownDescription": "https://squidfunk.github.io/mkdocs-material/setup/building-an-optimized-site/#built-in-projects-plugin",
+          "markdownDescription": "https://squidfunk.github.io/mkdocs-material/plugins/projects/",
           "type": "object",
           "properties": {
             "enabled": {
               "title": "Enable plugin",
-              "markdownDescription": "https://squidfunk.github.io/mkdocs-material/setup/building-an-optimized-site/#+projects.enabled",
+              "markdownDescription": "https://squidfunk.github.io/mkdocs-material/plugins/projects/#config.enabled",
               "type": "boolean",
               "default": true
             },
             "concurrency": {
               "title": "Concurrency (number of CPUs)",
-              "markdownDescription": "https://squidfunk.github.io/mkdocs-material/setup/building-an-optimized-site/#+projects.concurrency",
+              "markdownDescription": "https://squidfunk.github.io/mkdocs-material/plugins/projects/#config.concurrency",
               "type": "number"
             },
+            "cache": {
+              "title": "Enable caching",
+              "markdownDescription": "https://squidfunk.github.io/mkdocs-material/plugins/projects/#config.cache",
+              "type": "boolean",
+              "default": true
+            },
+            "cache_dir": {
+              "title": "Cache directory",
+              "markdownDescription": "https://squidfunk.github.io/mkdocs-material/plugins/projects/#config.cache_dir",
+              "type": "string",
+              "default": ".cache/plugins/projects"
+            },
             "projects": {
               "title": "Enable projects",
-              "markdownDescription": "https://squidfunk.github.io/mkdocs-material/setup/building-an-optimized-site/#+projects.projects",
+              "markdownDescription": "https://squidfunk.github.io/mkdocs-material/plugins/projects/#config.projects",
               "type": "boolean",
               "default": true
             },
             "projects_dir": {
               "title": "Projects directory",
-              "markdownDescription": "https://squidfunk.github.io/mkdocs-material/setup/building-an-optimized-site/#+projects.projects_dir",
+              "markdownDescription": "https://squidfunk.github.io/mkdocs-material/plugins/projects/#config.projects_dir",
               "type": "string",
               "default": "projects"
+            },
+            "projects_config_files": {
+              "title": "Projects configuration files",
+              "markdownDescription": "https://squidfunk.github.io/mkdocs-material/plugins/projects/#config.projects_config_files",
+              "type": "string",
+              "default": "\"*/mkdocs.yml\""
+            },
+            "projects_config_transform": {
+              "title": "Projects configuration transform",
+              "markdownDescription": "https://squidfunk.github.io/mkdocs-material/plugins/projects/#config.projects_config_transform",
+              "type": "string",
+              "defaultSnippets": [
+                {
+                  "body": "!!python/name:${1:module}.${2:function}"
+                }
+              ]
+            },
+            "hosting": {
+              "title": "Enable hoisting",
+              "markdownDescription": "https://squidfunk.github.io/mkdocs-material/plugins/projects/#config.hoisting",
+              "type": "boolean",
+              "default": true
             }
           },
           "additionalProperties": false

docs/schema/plugins/search.json

@@ -3,7 +3,7 @@
   "title": "Built-in search plugin",
   "oneOf": [
     {
-      "markdownDescription": "https://squidfunk.github.io/mkdocs-material/setup/setting-up-site-search/#built-in-search-plugin",
+      "markdownDescription": "https://squidfunk.github.io/mkdocs-material/plugins/search/",
       "enum": [
         "search"
       ]
@@ -12,7 +12,7 @@
       "type": "object",
       "properties": {
         "search": {
-          "markdownDescription": "https://squidfunk.github.io/mkdocs-material/setup/setting-up-site-search/#built-in-search-plugin",
+          "markdownDescription": "https://squidfunk.github.io/mkdocs-material/plugins/search/",
           "type": "object",
           "properties": {
             "lang": {
@@ -33,12 +33,12 @@
             },
             "separator": {
               "title": "Separator for indexing and query tokenization",
-              "markdownDescription": "https://squidfunk.github.io/mkdocs-material/setup/setting-up-site-search/#+search.separator",
+              "markdownDescription": "https://squidfunk.github.io/mkdocs-material/plugins/search/#config.separator",
               "type": "string"
             },
             "pipeline": {
               "title": "Text processing pipeline for indexing",
-              "markdownDescription": "https://squidfunk.github.io/mkdocs-material/setup/setting-up-site-search/#+search.pipeline",
+              "markdownDescription": "https://squidfunk.github.io/mkdocs-material/plugins/search/#config.pipeline",
               "type": "array",
               "items": {
                 "enum": [
@@ -51,12 +51,12 @@
             },
             "jieba_dict": {
               "title": "Jieba dictionary replacement",
-              "markdownDescription": "https://squidfunk.github.io/mkdocs-material/setup/setting-up-site-search/#+search.jieba_dict",
+              "markdownDescription": "https://squidfunk.github.io/mkdocs-material/plugins/search/#config.jieba_dict",
               "type": "string"
             },
             "jieba_dict_user": {
               "title": "Jieba dictionary augmentation",
-              "markdownDescription": "https://squidfunk.github.io/mkdocs-material/setup/setting-up-site-search/#+search.jieba_dict_user",
+              "markdownDescription": "https://squidfunk.github.io/mkdocs-material/plugins/search/#config.jieba_dict_user",
               "type": "string"
             }
           },
@@ -69,7 +69,7 @@
   "definitions": {
     "lang": {
       "title": "Site search language",
-      "markdownDescription": "https://squidfunk.github.io/mkdocs-material/setup/setting-up-site-search/#+search.lang",
+      "markdownDescription": "https://squidfunk.github.io/mkdocs-material/plugins/search/#config.lang",
       "oneOf": [
         {
           "title": "Site search language: Arabic",

docs/schema/plugins/social.json

@@ -3,7 +3,7 @@
   "title": "Built-in social plugin",
   "oneOf": [
     {
-      "markdownDescription": "https://squidfunk.github.io/mkdocs-material/setup/setting-up-social-cards/#built-in-social-plugin",
+      "markdownDescription": "https://squidfunk.github.io/mkdocs-material/plugins/social/",
       "enum": [
         "social"
       ]
@@ -12,61 +12,80 @@
       "type": "object",
       "properties": {
         "social": {
-          "markdownDescription": "https://squidfunk.github.io/mkdocs-material/setup/setting-up-social-cards/#built-in-social-plugin",
+          "markdownDescription": "https://squidfunk.github.io/mkdocs-material/plugins/social/",
           "type": "object",
           "properties": {
             "enabled": {
               "title": "Enable plugin",
-              "markdownDescription": "https://squidfunk.github.io/mkdocs-material/setup/setting-up-social-cards/#+social.enabled",
+              "markdownDescription": "https://squidfunk.github.io/mkdocs-material/plugins/social/#config.enabled",
               "type": "boolean",
               "default": true
             },
             "concurrency": {
               "title": "Concurrency (number of CPUs)",
-              "markdownDescription": "https://squidfunk.github.io/mkdocs-material/setup/setting-up-social-cards/#+social.concurrency",
+              "markdownDescription": "https://squidfunk.github.io/mkdocs-material/plugins/social/#config.concurrency",
               "type": "number"
             },
+            "cache": {
+              "title": "Enable caching",
+              "markdownDescription": "https://squidfunk.github.io/mkdocs-material/plugins/social/#config.cache",
+              "type": "boolean",
+              "default": true
+            },
+            "cache_dir": {
+              "title": "Cache directory",
+              "markdownDescription": "https://squidfunk.github.io/mkdocs-material/plugins/social/#config.cache_dir",
+              "type": "string",
+              "default": ".cache/plugins/social"
+            },
             "cards": {
               "title": "Social cards",
-              "markdownDescription": "https://squidfunk.github.io/mkdocs-material/setup/setting-up-social-cards/#+social.cards",
+              "markdownDescription": "https://squidfunk.github.io/mkdocs-material/plugins/social/#config.cards",
               "type": "boolean",
               "default": true
             },
             "cards_dir": {
               "title": "Social cards directory",
-              "markdownDescription": "https://squidfunk.github.io/mkdocs-material/setup/setting-up-social-cards/#+social.cards_dir",
+              "markdownDescription": "https://squidfunk.github.io/mkdocs-material/plugins/social/#config.cards_dir",
               "type": "string",
               "default": "assets/images/social"
             },
             "cards_layout_dir": {
               "title": "Social cards layout directory",
-              "markdownDescription": "https://squidfunk.github.io/mkdocs-material/setup/setting-up-social-cards/#+social.cards_layout_dir",
+              "markdownDescription": "https://squidfunk.github.io/mkdocs-material/plugins/social/#config.cards_layout_dir",
               "type": "string",
               "default": "layouts"
             },
             "cards_layout": {
               "title": "Social cards layout",
-              "markdownDescription": "https://squidfunk.github.io/mkdocs-material/setup/setting-up-social-cards/#+social.cards_layout",
+              "markdownDescription": "https://squidfunk.github.io/mkdocs-material/plugins/social/#config.cards_layout",
               "default": "default",
-              "enum": [
+              "oneOf": [
-                "default",
+                {
-                "default/accent",
+                  "enum": [
-                "default/invert",
+                    "default",
-                "default/variant"
+                    "default/accent",
+                    "default/invert",
+                    "default/variant"
+                  ]
+                },
+                {
+                  "type": "string"
+                }
               ]
             },
             "cards_layout_options": {
               "title": "Social cards layout options",
-              "markdownDescription": "https://squidfunk.github.io/mkdocs-material/setup/setting-up-social-cards/#+social.cards_layout_options",
+              "markdownDescription": "https://squidfunk.github.io/mkdocs-material/plugins/social/#config.cards_layout_options",
               "type": "object"
             },
             "cards_include": {
               "title": "Pages or folders to include",
-              "markdownDescription": "https://squidfunk.github.io/mkdocs-material/setup/setting-up-social-cards/#+social.cards_include",
+              "markdownDescription": "https://squidfunk.github.io/mkdocs-material/plugins/social/#config.cards_include",
               "type": "array",
               "items": {
                 "title": "Pages or folders matching this pattern will be included",
-                "markdownDescription": "https://squidfunk.github.io/mkdocs-material/setup/setting-up-social-cards/#+social.cards_include",
+                "markdownDescription": "https://squidfunk.github.io/mkdocs-material/plugins/social/#config.cards_include",
                 "pattern": ".*"
               },
               "uniqueItems": true,
@@ -74,11 +93,11 @@
             },
             "cards_exclude": {
               "title": "Pages or folders to exclude",
-              "markdownDescription": "https://squidfunk.github.io/mkdocs-material/setup/setting-up-social-cards/#+social.cards_exclude",
+              "markdownDescription": "https://squidfunk.github.io/mkdocs-material/plugins/social/#config.cards_exclude",
               "type": "array",
               "items": {
                 "title": "Pages or folders matching this pattern will be excluded",
-                "markdownDescription": "https://squidfunk.github.io/mkdocs-material/setup/setting-up-social-cards/#+social.cards_exclude",
+                "markdownDescription": "https://squidfunk.github.io/mkdocs-material/plugins/social/#config.cards_exclude",
                 "pattern": ".*"
               },
               "uniqueItems": true,
@@ -86,45 +105,33 @@
             },
             "debug": {
               "title": "Debug mode",
-              "markdownDescription": "https://squidfunk.github.io/mkdocs-material/setup/setting-up-social-cards/#+social.debug",
+              "markdownDescription": "https://squidfunk.github.io/mkdocs-material/plugins/social/#config.debug",
               "type": "boolean",
               "default": true
             },
             "debug_on_build": {
               "title": "Always disable debug mode on build",
-              "markdownDescription": "https://squidfunk.github.io/mkdocs-material/setup/setting-up-social-cards/#+social.debug_on_build",
+              "markdownDescription": "https://squidfunk.github.io/mkdocs-material/plugins/social/#config.debug_on_build",
               "type": "boolean",
               "default": false
             },
             "debug_grid": {
               "title": "Debug grid",
-              "markdownDescription": "https://squidfunk.github.io/mkdocs-material/setup/setting-up-social-cards/#+social.debug_grid",
+              "markdownDescription": "https://squidfunk.github.io/mkdocs-material/plugins/social/#config.debug_grid",
               "type": "boolean",
               "default": true
             },
             "debug_grid_step": {
               "title": "Debug grid step size",
-              "markdownDescription": "https://squidfunk.github.io/mkdocs-material/setup/setting-up-social-cards/#+social.debug_grid_step",
+              "markdownDescription": "https://squidfunk.github.io/mkdocs-material/plugins/social/#config.debug_grid_step",
               "type": "number",
               "default": 32
             },
             "debug_color": {
               "title": "Debug color",
-              "markdownDescription": "https://squidfunk.github.io/mkdocs-material/setup/setting-up-social-cards/#+social.debug_color",
+              "markdownDescription": "https://squidfunk.github.io/mkdocs-material/plugins/social/#config.debug_color",
               "type": "string",
               "default": "yellow"
-            },
-            "cache": {
-              "title": "Enable caching",
-              "markdownDescription": "https://squidfunk.github.io/mkdocs-material/setup/setting-up-social-cards/#+social.cache",
-              "type": "boolean",
-              "default": true
-            },
-            "cache_dir": {
-              "title": "Cache directory",
-              "markdownDescription": "https://squidfunk.github.io/mkdocs-material/setup/setting-up-social-cards/#+social.cache_dir",
-              "type": "string",
-              "default": ".cache/plugins/social"
             }
           },
           "additionalProperties": false

docs/schema/plugins/tags.json

@@ -3,7 +3,7 @@
   "title": "Built-in tags plugin",
   "oneOf": [
     {
-      "markdownDescription": "https://squidfunk.github.io/mkdocs-material/setup/setting-up-tags/#built-in-tags-plugin",
+      "markdownDescription": "https://squidfunk.github.io/mkdocs-material/plugins/tags/",
       "enum": [
         "tags"
       ]
@@ -12,24 +12,24 @@
       "type": "object",
       "properties": {
         "tags": {
-          "markdownDescription": "https://squidfunk.github.io/mkdocs-material/setup/setting-up-tags/#built-in-tags-plugin",
+          "markdownDescription": "https://squidfunk.github.io/mkdocs-material/plugins/tags/",
           "type": "object",
           "properties": {
             "enabled": {
               "title": "Enable plugin",
-              "markdownDescription": "https://squidfunk.github.io/mkdocs-material/setup/setting-up-tags/#+tags.enabled",
+              "markdownDescription": "https://squidfunk.github.io/mkdocs-material/plugins/tags/#config.enabled",
               "type": "boolean",
               "default": true
             },
             "tags_file": {
               "title": "Markdown file to render tags index",
-              "markdownDescription": "https://squidfunk.github.io/mkdocs-material/setup/setting-up-tags/#+tags.tags_file",
+              "markdownDescription": "https://squidfunk.github.io/mkdocs-material/plugins/tags/#config.tags_file",
               "pattern": "\\.md$",
               "default": "tags.md"
             },
             "tags_extra_files": {
               "title": "Markdown files to render additional tags indexes",
-              "markdownDescription": "https://squidfunk.github.io/mkdocs-material/setup/setting-up-tags/#+tags.tags_extra_files",
+              "markdownDescription": "https://squidfunk.github.io/mkdocs-material/plugins/tags/#config.tags_extra_files",
               "type": "object",
               "patternProperties": {
                 "\\.md$": {
@@ -44,18 +44,38 @@
             },
             "tags_slugify": {
               "title": "Tags slugify function",
-              "markdownDescription": "https://squidfunk.github.io/mkdocs-material/setup/setting-up-tags/#+tags.tags_slugify",
+              "markdownDescription": "https://squidfunk.github.io/mkdocs-material/plugins/tags/#config.tags_slugify",
               "default": "!!python/object/apply:pymdownx.slugs.slugify {kwds: {case: lower}}"
             },
             "tags_slugify_separator": {
               "title": "Tags slugify separator",
-              "markdownDescription": "https://squidfunk.github.io/mkdocs-material/setup/setting-up-tags/#+tags.tags_slugify_separator",
+              "markdownDescription": "https://squidfunk.github.io/mkdocs-material/plugins/tags/#config.tags_slugify_separator",
               "type": "string",
               "default": "\"-\""
             },
+            "tags_compare": {
+              "title": "Sort tags by this function",
+              "markdownDescription": "https://squidfunk.github.io/mkdocs-material/plugins/tags/#config.tags_compare",
+              "default": "!!python/name:material.plugins.tags.casefold"
+            },
+            "tags_compare_reverse": {
+              "title": "Soft tags in reverse",
+              "markdownDescription": "https://squidfunk.github.io/mkdocs-material/plugins/tags/#config.tags_compare_reverse",
+              "default": false
+            },
+            "tags_pages_compare": {
+              "title": "Sort tags pages by this function",
+              "markdownDescription": "https://squidfunk.github.io/mkdocs-material/plugins/tags/#config.tags_pages_compare",
+              "default": "!!python/name:material.plugins.tags.page_title"
+            },
+            "tags_pages_compare_reverse": {
+              "title": "Soft tags pages in reverse",
+              "markdownDescription": "https://squidfunk.github.io/mkdocs-material/plugins/tags/#config.tags_pages_compare_reverse",
+              "default": false
+            },
             "tags_allowed": {
               "title": "Tags allowed",
-              "markdownDescription": "https://squidfunk.github.io/mkdocs-material/setup/setting-up-tags/#+tags.tags_allowed",
+              "markdownDescription": "https://squidfunk.github.io/mkdocs-material/plugins/tags/#config.tags_allowed",
               "type": "array",
               "items": {
                 "type": "string"

docs/schema/plugins/typeset.json

@@ -3,7 +3,7 @@
   "title": "Built-in typeset plugin",
   "oneOf": [
     {
-      "markdownDescription": "https://squidfunk.github.io/mkdocs-material/reference/#built-in-typeset-plugin",
+      "markdownDescription": "https://squidfunk.github.io/mkdocs-material/plugins/typeset/",
       "enum": [
         "typeset"
       ]
@@ -12,12 +12,12 @@
       "type": "object",
       "properties": {
         "typeset": {
-          "markdownDescription": "https://squidfunk.github.io/mkdocs-material/reference/#built-in-typeset-plugin",
+          "markdownDescription": "https://squidfunk.github.io/mkdocs-material/plugins/typeset/",
           "type": "object",
           "properties": {
             "enabled": {
               "title": "Enable plugin",
-              "markdownDescription": "https://squidfunk.github.io/mkdocs-material/reference/#+typeset.enabled",
+              "markdownDescription": "https://squidfunk.github.io/mkdocs-material/plugins/typeset/#config.enabled",
               "type": "boolean",
               "default": true
             }

docs/schema/theme.json

@@ -629,6 +629,13 @@
               "content.code.copy"
             ]
           },
+          {
+            "title": "Code selection button",
+            "markdownDescription": "https://squidfunk.github.io/mkdocs-material/reference/code-blocks/#code-selection-button",
+            "enum": [
+              "content.code.select"
+            ]
+          },
           {
             "title": "Linked content tabs",
             "markdownDescription": "https://squidfunk.github.io/mkdocs-material/reference/content-tabs/#linked-content-tabs",

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

@@ -51,22 +51,28 @@ and [override the `comments.html` partial][overriding partials] with:
   <script>
     var giscus = document.querySelector("script[src*=giscus]")
 
-    /* Set palette on initial load */
+    // Set palette on initial load
     var palette = __md_get("__palette")
     if (palette && typeof palette.color === "object") {
-      var theme = palette.color.scheme === "slate" ? "dark" : "light"
+      var theme = palette.color.scheme === "slate"
+        ? "transparent_dark"
+        : "light"
+
+      // Instruct Giscus to set theme
       giscus.setAttribute("data-theme", theme) // (1)!
     }
 
-    /* Register event handlers after documented loaded */
+    // Register event handlers after documented loaded
     document.addEventListener("DOMContentLoaded", function() {
       var ref = document.querySelector("[data-md-component=palette]")
       ref.addEventListener("change", function() {
         var palette = __md_get("__palette")
         if (palette && typeof palette.color === "object") {
-          var theme = palette.color.scheme === "slate" ? "dark" : "light"
+          var theme = palette.color.scheme === "slate"
+            ? "transparent_dark"
+            : "light"
 
-          /* Instruct Giscus to change theme */
+          // Instruct Giscus to change theme
           var frame = document.querySelector(".giscus-frame")
           frame.contentWindow.postMessage(
             { giscus: { setConfig: { theme } } },
@@ -93,7 +99,7 @@ property to `true`:
 comments: true
 ---
 
-# Document title
+# Page title
 ...
 ```
 
@@ -102,6 +108,6 @@ If you wish to enable comments for an entire folder, you can use the
 
   [Giscus GitHub App]: https://github.com/apps/giscus
   [theme extension]: ../customization.md#extending-the-theme
-  [comments]: https://github.com/squidfunk/mkdocs-material/blob/master/src/partials/comments.html
+  [comments]: https://github.com/squidfunk/mkdocs-material/blob/master/src/templates/partials/comments.html
   [overriding partials]: ../customization.md#overriding-partials
-  [built-in meta plugin]: ../reference/index.md#built-in-meta-plugin
+  [built-in meta plugin]: ../plugins/meta.md

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
@@ -33,16 +33,14 @@ GitHub repositories also include the tag of the latest release.[^1]
     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,15 @@ 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 }
+    !!! note "When using build environments"
 
-:   :octicons-milestone-24: Default: `false` – Enables falling back to
+        If you are deploying through a CI system, you might need to adjust your
+        CI settings when fetching the code. For more information, see
+        [git-revision-date-localized].
+
+<!-- md:option git-revision-date-localized.fallback_to_build_date -->
+
+:   <!-- 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 +244,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 +278,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 +290,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 +302,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 +324,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,67 +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
-    ```
-
 ### 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
@@ -131,180 +55,9 @@ the following lines to `mkdocs.yml`:
 
 ``` yaml
 plugins:
-  - optimize # (1)!
+  - optimize
 ```
 
-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,12 +34,9 @@ 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
+  [built-in privacy plugin]:../plugins/privacy.md
-  [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

@@ -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,11 @@ 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 -->
+<!-- md:example color-palette-toggle -->
 
 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 +208,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 +220,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 +234,9 @@ 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 -->
+<!-- md:example color-palette-system-preference -->
 
 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 +265,12 @@ 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 -->
+<!-- md:example color-palette-system-preference -->
 
 Newer operating system allow to automatically switch between light and dark
 appearance during day and night times. [Insiders] adds support for automatic
@@ -322,6 +316,9 @@ reload the site.
 
 ### Custom colors
 
+<!-- md:version 5.0.0 -->
+<!-- md:example custom-colors -->
+
 Material for MkDocs implements colors using [CSS variables] (custom
 properties). If you want to customize the colors beyond the palette (e.g. to
 use your brand-specific colors), you can add an [additional style sheet] and
@@ -361,7 +358,7 @@ add:
 See the file containing the [color definitions] for a list of all CSS variables.
 
   [CSS variables]: https://developer.mozilla.org/en-US/docs/Web/CSS/Using_CSS_custom_properties
-  [color definitions]: https://github.com/squidfunk/mkdocs-material/blob/master/src/assets/stylesheets/main/_colors.scss
+  [color definitions]: https://github.com/squidfunk/mkdocs-material/blob/master/src/templates/assets/stylesheets/main/_colors.scss
   [additional style sheet]: ../customization.md#additional-css
 
 

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,8 +68,7 @@ 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]:../plugins/privacy.md
-  [built-in privacy plugin]: ensuring-data-privacy.md#built-in-privacy-plugin
 
 ## Customization
 

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:
 
@@ -37,11 +37,10 @@ the default slug function works. Consider using a [Unicode-aware slug function].
 !!! tip "Translations missing? Help us out, it takes only 5 minutes"
 
     Material for MkDocs relies on outside contributions for adding and updating
-    translations for the almost 60 languages it supports. If your language shows
+    translations for the more than 60 languages it supports. If your language
-    that some translations are missing, click on the link to add them. If your
+    shows that some translations are missing, click on the link to add them. If
-    language is not in the list, click here to [add a new language].
+    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
@@ -176,5 +172,5 @@ adjust the ones you want to override:
     ```
 
   [theme extension]: ../customization.md#extending-the-theme
-  [translations]: https://github.com/squidfunk/mkdocs-material/blob/master/src/partials/languages/
+  [translations]: https://github.com/squidfunk/mkdocs-material/blob/master/src/templates/partials/languages/
-  [list of available languages]: https://github.com/squidfunk/mkdocs-material/blob/master/src/partials/languages/
+  [list of available languages]: https://github.com/squidfunk/mkdocs-material/blob/master/src/templates/partials/languages/

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

@@ -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,8 +57,8 @@ 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
 must be located in the `docs` folder. Add the following lines to `mkdocs.yml`:
@@ -69,9 +68,43 @@ 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
+
+[:octicons-tag-24: 9.2.0][Site icon support]
+
+Most icons you see on your site, such as navigation icons, can also be changed. For example,
+to change the navigation arrows in the footer, add the following lines to `mkdocs.yml`:
+
+```yaml
+theme:
+  icon:
+    previous: fontawesome/solid/angle-left
+    next: fontawesome/solid/angle-right
+```
+
+The following is a complete list of customizable icons used by the theme:
+
+| Icon name    | Purpose                                                                       |
+|:-------------|:------------------------------------------------------------------------------|
+| `logo`       | See [Logo](#logo)                                                             |
+| `menu`       | Open drawer                                                                   |
+| `alternate`  | Change language                                                               |
+| `search`     | Search icon                                                                   |
+| `share`      | Share search                                                                  |
+| `close`      | Reset search, dismiss announcements                                           |
+| `top`        | Back-to-top button                                                            |
+| `edit`       | Edit current page                                                             |
+| `view`       | View page source                                                              |
+| `repo`       | Repository icon                                                               |
+| `admonition` | See [Admonition icons](../reference/admonitions.md#admonition-icons)          |
+| `tag`        | See [Tag icons and identifiers](setting-up-tags.md#tag-icons-and-identifiers) |
+| `previous`   | Previous page in footer, hide search on mobile                                |
+| `next`       | Next page in footer                                                           |
+
+  [Site icon support]: https://github.com/squidfunk/mkdocs-material/releases/tag/9.2.0
+
 ## Customization
 
 ### Additional icons
@@ -96,8 +129,8 @@ Then, add the following lines to `mkdocs.yml`:
 ``` yaml
 markdown_extensions:
   - pymdownx.emoji:
-      emoji_index: !!python/name:materialx.emoji.twemoji
+      emoji_index: !!python/name:material.extensions.emoji.twemoji
-      emoji_generator: !!python/name:materialx.emoji.to_svg
+      emoji_generator: !!python/name:material.extensions.emoji.to_svg
       options:
         custom_icons:
           - overrides/.icons

docs/setup/ensuring-data-privacy.md

@@ -13,9 +13,10 @@ 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 -->
+<!-- md:example cookie-consent -->
 
 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 +38,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
     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,9 +101,9 @@ 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
     cookies and manage settings:
 
@@ -128,7 +129,6 @@ 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
@@ -147,12 +147,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,145 +161,27 @@ 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?"
 
@@ -320,95 +202,11 @@ The following configuration options are available for external assets:
     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,72 +278,16 @@ 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
 
+<!-- md:version 8.4.0 -->
+<!-- md:example custom-cookies -->
+
 If you've customized the [cookie consent] and added a `custom` cookie, the user
 will be prompted to accept or reject your custom cookie. Once the user accepts
 or rejects the cookie consent, or [changes the settings], the page reloads[^1].

docs/setup/extensions/index.md

@@ -121,8 +121,8 @@ markdown_extensions:
   - pymdownx.caret
   - pymdownx.details
   - pymdownx.emoji:
-      emoji_index: !!python/name:materialx.emoji.twemoji
+      emoji_index: !!python/name:material.extensions.emoji.twemoji
-      emoji_generator: !!python/name:materialx.emoji.to_svg
+      emoji_generator: !!python/name:material.extensions.emoji.to_svg
   - pymdownx.highlight
   - pymdownx.inlinehilite
   - pymdownx.keys

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
@@ -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_`
@@ -104,12 +103,11 @@ 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`:
@@ -227,8 +222,8 @@ in `*.svg` file format into the resulting HTML page. Enable it via `mkdocs.yml`:
 ``` yaml
 markdown_extensions:
   - pymdownx.emoji:
-      emoji_index: !!python/name:materialx.emoji.twemoji # (1)!
+      emoji_index: !!python/name:material.extensions.emoji.twemoji # (1)!
-      emoji_generator: !!python/name:materialx.emoji.to_svg
+      emoji_generator: !!python/name:material.extensions.emoji.to_svg
 ```
 
 1.  [Python Markdown Extensions] uses the `pymdownx` namespace, but in order to
@@ -237,41 +232,41 @@ 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]:
 
     ``` yaml
     markdown_extensions:
       - pymdownx.emoji:
-          emoji_index: !!python/name:materialx.emoji.twemoji
+          emoji_index: !!python/name:material.extensions.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:
 
     ``` yaml
     markdown_extensions:
       - pymdownx.emoji:
-          emoji_generator: !!python/name:materialx.emoji.to_svg
+          emoji_generator: !!python/name:material.extensions.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
     explained in more detail in the [icon customization guide]:
 
     ``` yaml
     markdown_extensions:
       - pymdownx.emoji:
-          emoji_index: !!python/name:materialx.emoji.twemoji
+          emoji_index: !!python/name:material.extensions.emoji.twemoji
-          emoji_generator: !!python/name:materialx.emoji.to_svg
+          emoji_generator: !!python/name:material.extensions.emoji.to_svg
           options:
             custom_icons:
               - overrides/.icons
@@ -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:
 
@@ -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:
@@ -427,9 +420,9 @@ markdown_extensions:
     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,8 +473,8 @@ 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
 blocks. It's built on top of the [Highlight][pymdownx.highlight] extension, from
@@ -505,15 +496,14 @@ 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
 keys and combinations, e.g. ++ctrl+alt+del++. Enable it via `mkdocs.yml`:
@@ -533,14 +523,13 @@ 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
 corresponding symbols, e.h. copyright symbols or fractions. Enable it via
@@ -556,12 +545,11 @@ 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
@@ -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,21 @@ The following configuration options are supported:
           alternate_style: true
     ```
 
-[`slugify`](#+pymdownx.tabbed.slugify){ #+pymdownx.tabbed.slugify }
+<!-- md:option pymdownx.tabbed.combine_header_slug -->
 
-:   :octicons-milestone-24: Default: `headerid.slugify` – This option allows for
+:   <!-- md:default `false` --> This option enables the content tabs
+    [combine_header_slug style] flag, which prepends the id of the header to
+    the id of the tab:
+
+    ``` yaml
+    markdown_extensions:
+      - pymdownx.tabbed:
+          combine_header_slug: true
+    ```
+
+<!-- md:option pymdownx.tabbed.slugify -->
+
+:   <!-- 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,9 +713,8 @@ 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
+  [combine_header_slug style]: https://facelessuser.github.io/pymdown-extensions/extensions/tabbed/#tab-ids
   [better behavior on mobile viewports]: https://twitter.com/squidfunk/status/1424740370596958214
   [Grouping code blocks]: ../../reference/content-tabs.md#grouping-code-blocks
   [Grouping other content]: ../../reference/content-tabs.md#grouping-other-content
@@ -727,8 +723,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,9 +738,9 @@ 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,
     and is therefore recommended:
 
@@ -754,9 +750,9 @@ 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
     option is _rather discouraged_ from a user experience perspective:
 
@@ -775,7 +771,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