Merge branch 'master' into docs/guides

.devcontainer/devcontainer.json

@@ -0,0 +1,11 @@
+{
+	"name": "Material for MkDocs - VS Code dev container",
+	"image": "mcr.microsoft.com/devcontainers/typescript-node:0-18",
+	"features": {
+		"ghcr.io/devcontainers/features/python:1": {
+			"installTools": true,
+			"version": "3.11"
+	  }
+	},
+	"postCreateCommand": "pip install -e . && pip install mkdocs-minify-plugin mkdocs-redirects && npm install && npm run build"
+}

.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

.eslintrc

@@ -320,7 +320,6 @@
       }
     ],
     "jsdoc/empty-tags": "warn",
-    "jsdoc/newline-after-description": "warn",
     "jsdoc/no-bad-blocks": "warn",
     "jsdoc/no-defaults": "warn",
     "jsdoc/no-types": "warn",

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

@@ -31,7 +31,7 @@ body:
       description: >-
         Please list all links to the sections of
         [our documentation](https://squidfunk.github.io/mkdocs-material) that
-        are relevant to the bug, in order to show that you have consulted and
+        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)
         and [discussions](https://github.com/squidfunk/mkdocs-material/discussions)
@@ -54,7 +54,7 @@ body:
         .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)
       placeholder: |-
-        Drag and drop .zip file with minimal reproduction here.
+        Drag and drop the .zip file with minimal reproduction here.
     validations:
       required: true
 

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

@@ -12,7 +12,7 @@ body:
         Please describe the inconsistency or issue you have found in
         [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., it's impact on you and potentially
+        explain the severity of the issue, i.e., its impact on you and potentially
         other users.
         [More](https://squidfunk.github.io/mkdocs-material/contributing/reporting-a-docs-issue/#description)
     validations:

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

@@ -17,8 +17,8 @@ body:
     attributes:
       label: Description
       description: >-
-        Please provide a detailed description of your idea in 2-3 sentences, so
+        Please provide a detailed description of your idea in 2-3 sentences so
-        that we maintainers can fully understand what change, feature, or
+        that we maintainers can fully understand what change, feature, or the
         improvement you are proposing. Don't yet explain the benefits of your
         idea, we'll come to that. Focus on functionality.
         [More](https://squidfunk.github.io/mkdocs-material/contributing/requesting-a-change/#description)
@@ -31,7 +31,7 @@ body:
       label: Related links
       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)
+        [discussions](https://github.com/squidfunk/mkdocs-material/discussions),
         or to [documentation sections](https://squidfunk.github.io/mkdocs-material)
         that are relevant to your idea.
         If you discussed your idea with the community on our
@@ -50,8 +50,8 @@ body:
       label: Use Cases
       description: >-
         Please explain how your idea will work from an author's and user's
-        perspective. Elaborate how the change would positively impact not only
+        perspective. Elaborate on how the change would positively impact not only
-        you, but the community, and how it aligns with the goals and [philopsophy](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:
@@ -87,9 +87,9 @@ body:
             I have verified that [my idea is a change request and not a bug report](https://squidfunk.github.io/mkdocs-material/contributing/requesting-a-change/#its-not-a-bug-its-a-feature).
         required: true
       - label: >-
-            I have ensured that, to the best knowledge, [my idea will benefit the entire community](https://squidfunk.github.io/mkdocs-material/contributing/requesting-a-change/#benefit-for-the-community).
+            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-translations.yml

@@ -30,6 +30,14 @@ body:
           "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",
@@ -42,6 +50,10 @@ body:
           "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",
@@ -57,6 +69,7 @@ body:
           "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",
@@ -89,7 +102,7 @@ body:
       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 have assured that, to the best of my knowledge, the translations are accurate.
+        - 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

.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

@@ -29,7 +29,7 @@ on:
       - published
 
 env:
-  NODE_VERSION: 14.x
+  NODE_VERSION: 18.x
   PYTHON_VERSION: 3.x
 
 permissions:
@@ -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,20 +122,22 @@ 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 }}
             ghcr.io/${{ github.event.repository.full_name }}
           tags: |
+            type=semver,pattern={{version}}
+            type=semver,pattern={{major}}.{{minor}}
+            type=semver,pattern={{major}}
             type=ref,event=branch
-            type=ref,event=tag
             type=ref,event=pr
           flavor: |
             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
@@ -144,9 +146,11 @@ jobs:
 
       - name: Check Docker image
         working-directory: /tmp
+        env:
+          REPO_FULL_NAME: '${{ github.event.repository.full_name }}'
         run: |
-          docker run --rm -i -v ${PWD}:/docs ${{ github.event.repository.full_name }}:${{ steps.meta.outputs.version }} new .
+          docker run --rm -i -v ${PWD}:/docs ${REPO_FULL_NAME,,}:${{ steps.meta.outputs.version }} new .
-          docker run --rm -i -v ${PWD}:/docs ${{ github.event.repository.full_name }}:${{ steps.meta.outputs.version }} build
+          docker run --rm -i -v ${PWD}:/docs ${REPO_FULL_NAME,,}:${{ steps.meta.outputs.version }} build
 
       - name: Set platforms
         if: github.event_name == 'release'
@@ -154,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
 
@@ -46,12 +46,17 @@ jobs:
         with:
           python-version: ${{ env.PYTHON_VERSION }}
 
+      - name: Set the date environmental variable
+        run: echo "cache_id=$(date --utc '+%V')" >> $GITHUB_ENV
+
       - name: Set up build cache
         uses: actions/cache@v3
         id: cache
         with:
-          key: ${{ runner.os }}-${{ hashFiles('.cache/**') }}
+          key: mkdocs-material-${{ env.cache_id }}
           path: .cache
+          restore-keys: |
+            mkdocs-material-
 
       - name: Install dependencies
         run: sudo apt-get install pngquant
@@ -65,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
 

.stylelintrc

@@ -73,6 +73,8 @@
     ],
     "linebreaks": "unix",
     "media-feature-name-no-unknown": null,
+    "media-feature-range-notation": null,
+    "media-query-no-invalid": null,
     "no-descending-specificity": null,
     "no-empty-first-line": true,
     "no-unknown-animations": true,

.vscode/settings.json

@@ -17,8 +17,5 @@
     "tag:yaml.org,2002:python/name:materialx.emoji.to_svg",
     "tag:yaml.org,2002:python/name:materialx.emoji.twemoji",
     "tag:yaml.org,2002:python/name:pymdownx.superfences.fence_code_format"
-  ],
-  "cSpell.words": [
-    "mkdocs"
   ]
 }

CHANGELOG

@@ -1,3 +1,373 @@
+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
+  * Improved compat in privacy plugin with third-party plugins
+  * Fixed #5790: Typeset plugin ignores data-toc-label attribute
+  * Fixed #5778: Interplay of privacy plugin with git-revision-date-localized
+  * Fixed #5773: Info plugin erroring when community edition is in beta
+
+mkdocs-material-9.1.21+insiders-4.38.0 (2023-07-29)
+
+  * Added projects plugin for building nested projects
+  * Updated privacy plugin to new MkDocs API
+
+mkdocs-material-9.1.21+insiders-4.37.1 (2023-07-28)
+
+  * Updated MkDocs to 1.5.1
+  * Fixed deprecation warning in social plugin due to MkDocs upgrade
+  * Fixed #5772: Privacy plugin fails due to API change in MkDocs
+
+mkdocs-material-9.1.21 (2023-07-27)
+
+  * Fixed MkDocs 1.4 compat issue in social plugin (9.1.20 regression)
+
+mkdocs-material-9.1.20 (2023-07-27)
+
+  * Fixed deprecation warnings for social plugin
+
+mkdocs-material-9.1.19 (2023-07-18)
+
+  * Added support for MkDocs 1.5+
+  * Fixed #5699: Improve error reporting in social plugin
+
+mkdocs-material-9.1.18+insiders-4.37.0 (2023-07-07)
+
+  * Added support for overriding social cards settings per page
+  * Added new social card default/only/image layout
+  * Improved resilience of optimize and social plugin
+  * Fixed rendering bugs for pruned navigation items
+  * Fixed jumping of content tabs anchor links when instant loading is enabled
+  * Fixed #5676: Optimize plugin doesn't check for pngquant
+
+mkdocs-material-9.1.18 (2023-07-03)
+
+  * Updated Danish translations
+  * Added support for installing user requirements in Docker image
+  * Fixed #5655: Search separator with lookbehind breaks highlighting
+
+mkdocs-material-9.1.17+insiders-4.36.1 (2023-06-23)
+
+  * Fixed #5618: Date comparison breaking for drafts in blog plugin
+
+mkdocs-material-9.1.17 (2023-06-23)
+
+  * Fixed #5633: Code annotations with nested lists incorrectly mounted
+  * Fixed #5628: Regression in new social plugin configuration scheme
+
+mkdocs-material-9.1.16+insiders-4.36.0 (2023-06-15)
+
+  * Added support for instant prefetching to speed up slow connections
+  * Improved stability of anchor link removal in built-in typeset plugin
+  * Improved performance of regular expressions in typeset plugin
+  * Removed unnecessary import test for cairosvg in optimize plugin
+  * Fixed #5590: regular expression for anchor link removal too greedy
+
+mkdocs-material-9.1.16 (2023-06-15)
+
+  * Updated Indonesian translations
+  * Ensure scroll bar follows color scheme of operating system
+
+mkdocs-material-9.1.15+insiders-4.35.3 (2023-06-01)
+
+  * Fixed #5579: Abbreviations in headlines filtered by typeset plugin
+
+mkdocs-material-9.1.15+insiders-4.35.2 (2023-05-29)
+
+  * Fixed #5555: Blog plugin crashes when computing readtime for emojis
+
+mkdocs-material-9.1.15 (2023-05-29)
+
+  * Fixed #5566: Indicate color scheme to operating system
+  * Fixed #5565: Update Dockerfile to latest version of base image
+  * Fixed #5554: Add additional version tags (9, 9.1) to Docker image
+  * Fixed #5536: Strip tags of ARIA labels in table of contents
+
+mkdocs-material-9.1.14+insiders-4.35.1 (2023-05-20)
+
+  * Fixed internal handling of errors in social plugin
+
+mkdocs-material-9.1.14+insiders-4.35.0 (2023-05-20)
+
+  * Improve editing experience and stability of social plugin
+  * Added support for custom layout syntax validation in social plugin
+  * Added support for layer origin for easier placement in social plugin
+  * Added support for in- and exclusion patterns in social plugin
+  * Catch and print syntax errors in custom layouts
+
+mkdocs-material-9.1.14 (2023-05-20)
+
+  * Updated Armenian and Greek translations
+
+mkdocs-material-9.1.13+insiders-4.34.1 (2023-05-16)
+
+  * Disable social plugin debug mode by default on mkdocs build
+  * Added warning in social plugin debug mode when font style couldn't be found
+  * Set default concurrency of built-in multi-threaded plugins to CPUs - 1
+  * Fixed #5521: Social plugin triggers race condition when downloading fonts
+  * Fixed #5515: Social plugin crashes when concurrency is set to 1
+
+mkdocs-material-9.1.13 (2023-05-16)
+
+  * Fixed #5517: Social plugin crashes for some fonts (e.g. Open Sans)
+
+mkdocs-material-9.1.12+insiders-4.34.0 (2023-05-14)
+
+  * Added support for new overflow mode to auto-fit text in social plugin
+  * Reduced subtle rendering bugs in (code) annotations due to subpixel rounding
+  * Improved print styles for (code) annotation lists
+  * Improved performance of social plugin, now 3x as fast
+  * Improved interop of typeset plugin with MkDocstrings
+  * Fixed logo location for variants of default template in social plugin
+  * Fixed #5446: Built-in typeset plugin picks up headings in code blocks
+
+mkdocs-material-9.1.12+insiders-4.33.2 (2023-05-12)
+
+  * Fixed #5508: Social plugin crashes trying to copy cards on Docker/Windows
+  * Fixed #5507: Social plugin crashes on serve when layouts folder doesn't exist
+  * Fixed #5505: Social plugin trying to resolve logo in wrong location
+  * Fixed #5496: Annotations with nested lists incorrectly mounted
+  * Fixed #5493: Social plugin crashes on Python 3.8
+
+mkdocs-material-9.1.12 (2023-05-12)
+
+  * Updated Bengali (Bangla) translations
+  * Fixed #5503: Docker image publish errors on uppercase characters
+  * Fixed #5407: Auto-pause media when in hidden content tabs
+
+mkdocs-material-9.1.11+insiders-4.33.1 (2023-05-09)
+
+  * Added support for SVG background images in social plugin
+
+mkdocs-material-9.1.11 (2023-05-08)
+
+  * Fixed #5487: Social plugin crashes without options (9.1.10 regression)
+
+mkdocs-material-9.1.10+insiders-4.33.0 (2023-05-08)
+
+  * Added support for custom layouts for social plugin
+  * Added support for background images for social cards
+
+mkdocs-material-9.1.10 (2023-05-08)
+
+  * Added cards_layout_options setting for social cards
+  * Deprecated cards_color and cards_font setting for social cards
+
+mkdocs-material-9.1.9 (2023-05-02)
+
+  * Added Telugu, Kannada and Sanskrit translations
+  * Fixed #5428: Fixed margins for light/dark mode images in figures
+  * Fixed #5420: Social plugin crashing for some specific Google Fonts
+  * Fixed #5160: Instant loading makes code annotations jump (9.1.1 regression)
+  * Fixed #4920: Social plugin not loading logo from custom icon set
+  * Fixed social plugin crashing when only code font is specified
+
+mkdocs-material-9.1.8 (2023-04-24)
+
+  * Fixed #5417: Theme breaks when palette is not defined (9.1.7 regression)
+
+mkdocs-material-9.1.7+insiders-4.32.6 (2023-04-22)
+
+  * Fixed #5336: Interplay of blog plugin with git-revision-date-localized
+
+mkdocs-material-9.1.7 (2023-04-22)
+
+  * Updated Persian (Farsi) and Turkish translations
+  * Fixed #5401: Added missing flag to disable built-in tags plugin
+  * Fixed #5206: Ensure defaults are set for primary and accent colors
+  * Fixed unnecessary inclusion of palette CSS when unused
+
+mkdocs-material-9.1.6+insiders-4.32.5 (2023-04-07)
+
+  * Fixed #5322: Navigation tabs hoist nested page icons
+
+mkdocs-material-9.1.6 (2023-04-07)
+
+  * Updated Persian (Farsi) translations
+  * Fixed #5300: Boxes in Mermaid sequence diagrams not color-abiding
+
 mkdocs-material-9.1.5 (2023-03-31)
 
   * Updated Lithuanian and Japanese translations
@@ -143,7 +513,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

@@ -2,58 +2,60 @@
 
 Material for MkDocs is an actively maintained and constantly improved project
 that serves a diverse user base with varying backgrounds and needs. In order to
-effectively address the needs of all our users, evaluatgit e requests, and fix bugs, 
+effectively address the needs of all our users, evaluate change requests, and
-we maintainers need to put in a lot of work. We have devoted significant effort 
+fix bugs, we maintainers need to put in a lot of work. We have devoted
-to creating better templates for our issue tracker, optimizing the processes for 
+significant effort to creating better templates for our issue tracker,
-our users to report bugs, request features or changes, contribute to the 
+optimizing the processes for our users to report bugs, request features or
-project, or exchange with our community. 
+changes, contribute to the project, or exchange with our community.
 
 Given the wealth of valuable knowledge contained in numerous issues and
-discussions, we consider our [issue tracker] and [discussion board] to serve as a 
+discussions, we consider our [issue tracker] and [discussion board] to serve as
-crucial __knowledge base__ that is an important addition to our [documentation] 
+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.
 
-## How to contribute
-
-Selecting the appropriate contribution template is essential to maintain the 
-organization, searchability, and ease of use of this knowledge base. In this 
-section of our documentation, we outline the available options and their 
-respective procedures.
-
   [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 to contribute
 
 ### Creating an issue
 
--   #### [Report a bug][report a bug]
+-   #### [Report a bug]
 
-    __Something is not working?__ Report a bug in Material for MkDocs by creating an issue with a reproduction
+    __Something is not working?__ Report a bug in Material for MkDocs by
+    creating an issue with a reproduction
 
--   #### [Report a docs issue][report a docs issue]
+-   #### [Report a docs issue]
 
-    __Missing information in our docs?__ Report missing information or potential inconsistencies in our documentation 
+    __Missing information in our docs?__ Report missing information or
+    potential inconsistencies in our documentation
 
--   #### [Request a change][request a change]
+-   #### [Request a change]
 
-    __Want to submit an idea?__ Propose a change or feature request or suggest an improvement
+    __Want to submit an idea?__ Propose a change, feature request, or
+    suggest an improvement
 
--   #### [Ask a question][ask a question]
+-   #### [Ask a question]
 
-    __Have a question or need help?__ Ask a question on our discussion board and get in touch with our community
+    __Have a question or need help?__ Ask a question on our [discussion board]
+    and get in touch with our community
 
-### Contributing to this project
+### Contributing
 
--   #### [Add a translation](https://github.com/squidfunk/mkdocs-material/adding-a-translation)
+-   #### [Add a translation]
 
-    __Missing support for your language?__ Add missing translations for a new or supported language
+    __Missing support for your language?__ Add missing translations for a new
+    or already supported language
 
--   #### [Create a pull request](https://github.com/squidfunk/mkdocs-material/creating-a-pull-request) 
+-   #### [Create a pull request]
 
-    __Want to create a pull request?__ Learn how to create a comprehensive pull request (PR)
+    __Want to create a pull request?__ Learn how to create a comprehensive
+    and useful pull request (PR)s
 
-  [report a bug]: reporting-a-bug.md
+  [Report a bug]: reporting-a-bug.md
-  [report a docs issue]: reporting-a-docs-issue.md
+  [Report a docs issue]: reporting-a-docs-issue.md
-  [request a change]: requesting-a-change.md
+  [Request a change]: requesting-a-change.md
-  [ask a question]: https://github.com/squidfunk/mkdocs-material/discussions
+  [Ask a question]: https://github.com/squidfunk/mkdocs-material/discussions
+  [Add a translation]: https://github.com/squidfunk/mkdocs-material/adding-a-translation
+  [Create a pull request]: https://github.com/squidfunk/mkdocs-material/pulls

Dockerfile

@@ -18,7 +18,7 @@
 # FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS
 # IN THE SOFTWARE.
 
-FROM python:3.11.0-alpine3.17
+FROM python:3.11-alpine3.18
 
 # Build-time flags
 ARG WITH_PLUGINS=true
@@ -34,7 +34,7 @@ WORKDIR /tmp
 COPY material material
 COPY package.json package.json
 COPY README.md README.md
-COPY requirements.txt requirements.txt
+COPY *requirements.txt ./
 COPY pyproject.toml pyproject.toml
 
 # Perform build and cleanup artifacts and caches
@@ -54,15 +54,19 @@ RUN \
     gcc \
     libffi-dev \
     musl-dev \
+&& \
+  pip install --no-cache-dir --upgrade pip \
 && \
   pip install --no-cache-dir . \
 && \
   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" \
+  fi \
-      "cairosvg>=2.5"; \
+&& \
+  if [ -e user-requirements.txt ]; then \
+    pip install -U -r user-requirements.txt; \
   fi \
 && \
   apk del .build \
@@ -70,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

@@ -6,9 +6,7 @@
 
 <p align="center">
   <strong>
-    A 
+    A powerful documentation framework on top of
-    <a href="https://material.io/">Material Design</a> 
-    theme for 
     <a href="https://www.mkdocs.org/">MkDocs</a>
   </strong>
 </p>
@@ -22,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"
@@ -39,7 +33,7 @@
 <p align="center">
   Write your documentation in Markdown and create a professional static site for
   your Open Source or commercial project in minutes – searchable, customizable,
-  more than 50 languages, for all devices.
+  more than 60 languages, for all devices.
 </p>
 
 <p align="center">
@@ -107,9 +101,6 @@
   <a href="https://elastic.co" target=_blank><img
     src="https://raw.githubusercontent.com/squidfunk/mkdocs-material/master/.github/assets/sponsors/sponsor-elastic.png" height="58"
   /></a>
-  <a href="https://www.hyperledger.org/" target=_blank><img
-    src="https://raw.githubusercontent.com/squidfunk/mkdocs-material/master/.github/assets/sponsors/sponsor-hyperledger.png" height="58"
-  /></a>
   <a href="https://ipfabric.io/" target=_blank><img
     src="https://raw.githubusercontent.com/squidfunk/mkdocs-material/master/.github/assets/sponsors/sponsor-ip-fabric.png" height="58"
   /></a>
@@ -122,18 +113,15 @@
   <a href="https://sparkfun.com/" target=_blank><img
     src="https://raw.githubusercontent.com/squidfunk/mkdocs-material/master/.github/assets/sponsors/sponsor-sparkfun.png" height="58"
   /></a>
-  <a href="https://automationtechnology.de/" target=_blank><img
-    src="https://raw.githubusercontent.com/squidfunk/mkdocs-material/master/.github/assets/sponsors/sponsor-automation-technology.png" height="58"
-  /></a>
   <a href="https://eccenca.com/" target=_blank><img
     src="https://raw.githubusercontent.com/squidfunk/mkdocs-material/master/.github/assets/sponsors/sponsor-eccenca.png" height="58"
   /></a>
   <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>
@@ -143,6 +131,36 @@
   <a href="https://bitcrowd.net/" target=_blank><img
     src="https://raw.githubusercontent.com/squidfunk/mkdocs-material/master/.github/assets/sponsors/sponsor-bitcrowd.png" height="58"
   /></a>
+  <a href="https://getscreen.me/" target=_blank><img
+    src="https://raw.githubusercontent.com/squidfunk/mkdocs-material/master/.github/assets/sponsors/sponsor-getscreenme.png" height="58"
+  /></a>
+  <a href="https://botcity.dev/" target=_blank><img
+    src="https://raw.githubusercontent.com/squidfunk/mkdocs-material/master/.github/assets/sponsors/sponsor-botcity.png" height="58"
+  /></a>
+  <a href="https://www.springernature.com/gp" target=_blank><img
+    src="https://raw.githubusercontent.com/squidfunk/mkdocs-material/master/.github/assets/sponsors/sponsor-sn-technology.png" height="58"
+  /></a>
+  <a href="https://kolena.io/" target=_blank><img
+    src="https://raw.githubusercontent.com/squidfunk/mkdocs-material/master/.github/assets/sponsors/sponsor-kolena.png" height="58"
+  /></a>
+  <a href="https://www.evergiving.com/" target=_blank><img
+    src="https://raw.githubusercontent.com/squidfunk/mkdocs-material/master/.github/assets/sponsors/sponsor-evergiving.png" height="58"
+  /></a>
+  <a href="https://koor.tech/" target=_blank><img
+    src="https://raw.githubusercontent.com/squidfunk/mkdocs-material/master/.github/assets/sponsors/sponsor-koor.png" height="58"
+  /></a>
+  <a href="https://astral.sh/" target=_blank><img
+    src="https://raw.githubusercontent.com/squidfunk/mkdocs-material/master/.github/assets/sponsors/sponsor-astral.png" height="58"
+  /></a>
+  <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>
 
@@ -208,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/),
@@ -222,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/),
@@ -240,17 +262,18 @@ 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/),
 [WTF](https://wtfutil.com/)
 
 ## License

docs/blog/.authors.yml

@@ -1,4 +1,5 @@
-squidfunk:
+authors:
+  squidfunk:
     name: Martin Donath
     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,6 +2,211 @@
 
 ## Material for MkDocs
 
+### 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)
+
+### 9.1.20 <small>July 27, 2023</small> { id="9.1.20" }
+
+- Updated Sanskrit translations
+- Fixed deprecation warnings for social plugin
+
+### 9.1.19 <small>July 18, 2023</small> { id="9.1.19" }
+
+- Added support for MkDocs 1.5+
+- Fixed #5699: Improve error reporting in social plugin
+
+### 9.1.18 <small>July 3, 2023</small> { id="9.1.18" }
+
+- Updated Danish translations
+- Added support for installing user requirements in Docker image
+- Fixed #5655: Search separator with lookbehind breaks highlighting
+
+### 9.1.17 <small>June 23, 2023</small> { id="9.1.17" }
+
+- Fixed #5633: Code annotations with nested lists incorrectly mounted
+- Fixed #5628: Regression in new social plugin configuration scheme
+
+### 9.1.16 <small>June 15, 2023</small> { id="9.1.16" }
+
+- Updated Indonesian translations
+- Ensure scroll bar follows color scheme of operating system
+
+### 9.1.15 <small>May 29, 2023</small> { id="9.1.15" }
+
+- Fixed #5566: Indicate color scheme to operating system
+- Fixed #5565: Update `Dockerfile` to latest version of base image
+- Fixed #5554: Add additional version tags (`9`, `9.1`) to Docker image
+- Fixed #5536: Strip tags of ARIA labels in table of contents
+
+### 9.1.14 <small>May 20, 2023</small> { id="9.1.14" }
+
+- Updated Armenian and Greek translations
+
+### 9.1.13 <small>May 16, 2023</small> { id="9.1.13" }
+
+- Fixed #5517: Social plugin crashes for some fonts (e.g. Open Sans)
+
+### 9.1.12 <small>May 12, 2023</small> { id="9.1.12" }
+
+- Updated Bengali (Bangla) translations
+- Fixed #5503: Docker image publish errors on uppercase characters
+- Fixed #5407: Auto-pause media when in hidden content tabs
+
+### 9.1.11 <small>May 8, 2023</small> { id="9.1.11" }
+
+- Fixed #5487: Social plugin crashes without options (9.1.10 regression)
+
+### 9.1.10 <small>May 8, 2023</small> { id="9.1.10" }
+
+- Added `cards_layout_options` setting for social cards
+- Deprecated `cards_color` and `cards_font` setting for social cards
+
+### 9.1.9 <small>May 2, 2023</small> { id="9.1.9" }
+
+- Added Telugu, Kannada and Sanskrit translations
+- Fixed #5428: Fixed margins for light/dark mode images in figures
+- Fixed #5420: Social plugin crashing for some specific Google Fonts
+- Fixed #5160: Instant loading makes code annotations jump (9.1.1 regression)
+- Fixed #4920: Social plugin not loading logo from custom icon set
+- Fixed social plugin crashing when only code font is specified
+
+### 9.1.8 <small>April 24, 2023</small> { id="9.1.8" }
+
+- Fixed #5417: Theme breaks when `palette` is not defined (9.1.7 regression)
+
+### 9.1.7 <small>April 22, 2023</small> { id="9.1.7" }
+
+- Updated Persian (Farsi) and Turkish translations
+- Fixed #5401: Added missing flag to disable built-in tags plugin
+- Fixed #5206: Ensure defaults are set for primary and accent colors
+- Fixed unnecessary inclusion of palette CSS when unused
+
+### 9.1.6 <small>April 7, 2023</small> { id="9.1.6" }
+
+- Updated Persian (Farsi) translations
+- Fixed #5300: Boxes in Mermaid sequence diagrams not color-abiding
+
 ### 9.1.5 <small>March 31, 2023</small> { id="9.1.5" }
 
 - Updated Lithuanian and Japanese translations
@@ -103,7 +308,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-a-translation.md

@@ -1,236 +0,0 @@
-# Adding a translation
-
-We can't believe it ourselves but with the help of community contribution, 
-Material for MkDocs already supports 50+ languages. As you can imagine, it's
-impossible for us maintainers to keep all languages up-to-date (we just don't 
-speak 50+ languages). That's why we need the help of our international community 
-to help us add new or update translations, as new feature releases sometimes 
-require new translations.
-
-If you would like to help us to make Material for MkDocs more globally 
-accessible and have noticed a missing translation in your language or want to 
-add a new one. In that case, we have simplified the contributing process for you. 
-Just follow the few steps of the guide below.
-
-## Before adding a translation
-
-Given the constant expansion of our project and the frequent translation updates, 
-it is essential to check the following things before submitting a translation 
-contribution.
-
-### List of supported languages
-
-Chances are your language is already supported by Material for MkDocs. To check
-if your language is supported or needs improvements and updates, we would advise 
-you to check the [list of supported languages].
-
-[:material-earth-plus:  Search for your language][Search for your language]{ .md-button .md-button--primary }
-
-  [list of supported languages]: https://squidfunk.github.io/mkdocs-material/setup/changing-the-language/#site-language
-  [Search for your language]: https://squidfunk.github.io/mkdocs-material/setup/changing-the-language/#site-language
-
-In case your language is already supported, you can add **missing translations**, 
-displayed below each language. If your language is not on the list of supported 
-languages, you can contribute translations by opening a new issue and 
-[adding a translation] by following the guide below.
-
-> __Please note,__ that we use region designators in conjunction with regions, 
-> and cluster all languages using language designators with regions. Language 
-> region designators consist of codes that represent countries and follow the 
-> [ISO 3166-1 standard], which employs two-letter capitalized codes. If you need 
-> to specify a particular dialect, please utilize this system by hyphenating a 
-> language designator with a region designator. For instance, to specify the 
-> British English, use the "en" language designator and indicate the locale as 
-> "en-GB."
-
-  [Adding a translation]: https://github.com/squidfunk/mkdocs-material/issues/new?assignees=&labels=change+request&template=04-add-a-translation.yml&title=Add+translations+for+...
-  [ISO 3166-1 standard]: https://lingohub.com/developers/supported-locales/language-designators-with-regions
-
-### Issue tracker
-
-Our issue tracker might already contain an open issue with a contribution with 
-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.
-
-[:octicons-issue-opened-24:  Search our issue tracker][Search our issue tracker]{ .md-button .md-button--primary }
-  
-  [issue tracker]: https://github.com/squidfunk/mkdocs-material/issues
-  [search our issue tracker]: https://github.com/squidfunk/mkdocs-material/issues
-
-### Update supported languages
-
-Have you noticed that other users haven't yet updated your language? You are 
-welcome to contribute and add any missing translations by clicking the link 
-provided underneath each language in the [list of supported languages]. This 
-link will direct you to a new issue template that is pre-filled with all the 
-necessary information. Any fields that can be adjusted will be highlighted for 
-your convenience.
-
-[:material-translate-variant:  Add missing translations][Update your translations]{ .md-button .md-button--primary }
-
- [List of supported languages]: https://squidfunk.github.io/mkdocs-material/setup/changing-the-language/#site-language
- [Update your translations]: https://squidfunk.github.io/mkdocs-material/setup/changing-the-language/#site-language
-
----
-
-At this point, when you have made sure that Material for MkDocs doesn't already 
-support your language you can add translations for it by following the issue 
-template.
-
-## Issue template
-
-We have created a new issue template to make contributing translations for new 
-languages as simple as possible. It is the result of our experience with 50+
-language contributions and updates over the last couple of years. We recently 
-simplified the language contribution process, and the new template consists of the 
-following parts:
-
-- [Title]
-- [Translations]
-- [Country flag] <small>optional</small>
-- [Checklist]
-
-  [Title]: #title
-  [Translations]: #translations
-  [Country flag]: #country-flag
-  [Checklist]: #checklist
-
-### Title
-
-Translation issue titles are simple. When adding a new language, the first part 
-of the title with "Add translations for..." is already pre-filled in the 
-template, and you need to replace the three dots with your language name. If 
-adding missing translations for a language from the [list of supported languages], 
-the title is already set with no need for adjustment. 
-
-| <!-- --> | Example  |
-| -------- | -------- | 
-| :material-check:{ style="color: #4DB6AC" } __Clear__ | Add translations for German
-| :material-close:{ style="color: #EF5350" } __Unclear__ | Add translations ...
-| :material-close:{ style="color: #EF5350" } __Generic__ | German
-
- [List of supported languages]: https://squidfunk.github.io/mkdocs-material/setup/changing-the-language/#site-language
-
-### Translations
-
-With the preliminary work done, you can now add all missing translations for 
-your language. Each label on the right side containing the `⬅️ icon` is missing 
-a translation. To ensure the accuracy of your translation, consider double-checking 
-the context of the words by looking at the [English version].
-
-After adding the translation, remove the `⬅️ icon` from each translated line. If 
-you don't know how to translate specific fields, simply leave them for other 
-contributors to complete.
-
-[English version]: https://github.com/squidfunk/mkdocs-material/tree/master/src/partials/languages/en.html
-
-#### Translation context
-
-TO DO MARTIN - explain the translation context
-.
-.
-
-
-### Country flag
-
-Congratulations on contributing translations for a new language! To make it 
-easier for you and others to find the language in our list of supported 
-languages, please select the best-fitting flag for your language from our 
-documentation's [Icons, Emojis site] by entering the command `flag` in the 
-search field.
-
-!!! warning "Icon limitation by Twemoji"
-
-    Please note that only icons provided by Twemoji can be used. If your flag is 
-    not available on the list on the [Icons, Emojis site], please choose an 
-    alternative.
-
-> __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 Temoji, it is best that you provide us with an alternative instead of us 
-> choosing one for you.
-
- [Icons, Emojis site]: https://squidfunk.github.io/mkdocs-material/reference/icons-emojis/#search
-
-### Checklist
-
-Thanks for following the guide and creating a high-quality and complete 
-translation issue – 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 know to integrate your contribution to Material for MkDocs.
-
-__We'll take it from here.__
-
----
-
-## Authors credits
-
-Authors who submit a translation using the template above will be 
-__credited as co-authors__ in commits for Material for MkDocs. To list your 
-account as a co-author without knowing or revealing your email address, we will 
-use your GitHub-provided no-reply email, following 
-[GitHub's recommended workaround] to protect your privacy. This way, your 
-commit will count as a contribution without opening a pull request.
-
- [GitHub's recommended workaround]: https://docs.github.com/en/pull-requests/committing-changes-to-your-project/creating-and-editing-commits/creating-a-commit-with-multiple-authors
-
-## Contributing via pull request
-
-If you want to contribute missing translations by creating a pull request to be 
-listed as the sole author of the commit, you can open a PR after submitting the 
-translation issue. Ensure you thoroughly read the pull request guide below to 
-prevent breaking functionality in the translation file.
-
-1.  Fill out a [translation issue] according to the guide and submit it in the 
-    [issue tracker].
-
-2.  Tick the box for the last point in the "Before submitting..." section.
-    - [x]  __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).
-
-3.  Fork the Material for MkDocs repository, set up a [development environment] 
-and create a separate git branch on which you make all your changes.
-
-4.  Please review all [existing language files] in the repository and search for 
-your language. If a file for your language already exists, please use it for 
-your edits or create a new file if your language is not listed by copying one of 
-the existing files.
-    
-5.  Add the missing translations for your language to the best of your knowledge
-    and save the changes.
-
-    !!! warning "Important"
-        Only add the translations that are different from the defaults. For 
-        example, if your language is left-to-right, don't add the `direction` 
-        translation, as English is also left-to-right. The following 
-        translations are for technical purposes, and __should not be updated__. 
-        If they're missing from your language, it's for a good reason:
-
-        - `search.config.lang`
-        - `search.config.pipeline`
-        - `search.config.separator`
-
-6.  Open the [English translations] file and compare your translations with the 
-    up-to-date English translations file. 
-
-7.  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.
-
-8.  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.
-
-9. After your PR is merged, you can safely delete your branch and pull the 
-changes from the main (upstream) repository.
-
-  [translation issue]: https://github.com/squidfunk/mkdocs-material/issues/new?assignees=&labels=change+request&template=04-add-a-translation.yml&title=Add+translations+for+...
-  [issue tracker]: https://github.com/squidfunk/mkdocs-material/issues/new/choose
-  [existing language files]: https://github.com/squidfunk/mkdocs-material/tree/master/src/partials/languages
-  [English translations]: https://github.com/squidfunk/mkdocs-material/tree/master/src/partials/languages/en.html
-  [development environment]: https://squidfunk.github.io/mkdocs-material/customization/#environment-setup
-
-__After your PR was merged by us maintainers, you can start using the new language.__

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,206 +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 serves a diverse user base with varying backgrounds and needs. In order to 
+serving a diverse user base with versatile backgrounds and needs. In order to
-effectively address the needs of all our users, evaluate requests, and fix bugs, 
+efficiently address the requirements of all our users, evaluate change requests,
-we maintainers need to put in a lot of work.
+and fix bugs, we put in a lot of work.
 
-Our community is pretty big and includes many active users who open new 
+Our ever-growing community includes many active users, who open new
-discussions or issues multiple times a day, filling the [issue tracker] or the 
+issues and discussions several times a day, evolving our [issue tracker] and
-[discussion board] with a lot of valuable knowledge. As such, we consider our 
+[discussion board] into a knowledge base – an important addition to
-issue tracker and discussion board to be a knowledge base that is an important 
+our [documentation] – yielding value to both new and experienced users.
-addition to our [documentation], and brings value to both new and experienced 
-users of Material for MkDocs. 
 
-## How to contribute
+  [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/
 
-We've invested time and effort into making our [issue tracker] and [discussion board] 
+## How you can contribute
-as user-friendly as possible. We understand that reporting bugs, 
-requesting features, and engaging with our community can be challenging, so 
-we've optimized our templates and added guidelines to improve all overall 
-interaction within this project.
 
-Our goal is to ensure that our platform is __well-structured__, __easy to navigate__, 
+We understand that reporting bugs, raising change requests, as well as engaging
-and __searchable__, so you can find what you need quickly and efficiently. We've 
+in discussions can be time-consuming, which is why we've carefully optimized our
-also optimized our templates to help us understand your needs better, so we can 
+issue templates and defined guidelines to improve the overall interaction
-provide you with faster and more effective support. In this documentation 
+within the project. We've invested a lot of time and effort into making our
-section, we'll give you an overview of each process and guide you to the
+[issue tracker] and [discussion board] as efficient as possible.
-detailed subpages.
 
+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 with 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, 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 a question 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 to this project
+### Contributing
 
 <div class="grid cards" markdown>
 
--   :material-translate-variant:{ .lg .middle } __Missing support for your language?__
+-   :material-translate: &nbsp;
+    __Missing support for your language?__
 
     ---
 
-    Add missing translations for a new or supported language
+    Add or improve translations for a new or already supported language
-
-    [:octicons-arrow-right-24: Add a translation](https://github.com/squidfunk/mkdocs-material/adding-a-translation)
-
--   :material-source-pull:{ .lg .middle } __Want to create a pull request?__
 
     ---
 
-    Learn how to create a comprehensive pull request (PR)
+    [:octicons-arrow-right-24: Add a translation][add a translation]
 
-    [:octicons-arrow-right-24: Create a pull request](https://github.com/squidfunk/mkdocs-material/creating-a-pull-request)
+-   :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 a translation]: https://github.com/squidfunk/mkdocs-material/adding-a-translation
+  [create a pull request]: https://github.com/squidfunk/mkdocs-material/pulls
 
----
+## Checklist
 
-!!! warning "Issues, discussions, and comments are permanent"
+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 in this project forever. Therefore, be nice, follow
+    for everyone to read – forever. Therefore, please always be nice and
-    our contribution guidelines, and comply with our Code of Conduct.
+    constructive, follow our contribution guidelines, and comply with our
+    [Code of Conduct].
 
----
+### Before creating an issue
 
-## Before contributing
+- Are you using the appropriate issue template, or is there another issue
+  template that better fits the context of your request?
 
-Before interacting within this project, please take a moment to consider the 
+- Have you checked if a similar bug report or change request has already been
-following questions. By doing so, you can ensure that you are using the correct 
+  created, or have you stumbled upon something that might be related?
-issue template or provide all necessary information when interacting with the 
-community:
 
-### Before submitting an issue, review:
+- Did your fill out every field as requested and did you provide all additional
+  information we maintainers need to comprehend your request?
 
-- Am I using the right issue template for my [request], [report], or [contribution]?           
+### Before asking a question
-- Have I checked if a similar issue or request has already been submitted?
-- Did I fill out every field as requested?
-- Did I provide all additional information others might need to comprehend my request?
 
- [request]: https://github.com/squidfunk/mkdocs-material/issues/new?assignees=&labels=&template=03-request-a-change.yml
+- Is the topic a question for our [discussion board], or is it a bug report or
- [report]: https://github.com/squidfunk/mkdocs-material/issues/new?assignees=&labels=&template=01-report-a-bug.yml
+  change request that should better be raised on our [issue tracker]?
- [contribution]: https://github.com/squidfunk/mkdocs-material/issues/new?assignees=&labels=change+request&template=04-add-a-translation.yml&title=Add+translations+for+...
 
-### Before asking a question, reconsider:
+- 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?
 
-- Is there an open discussion on the topic of my request?
+- Did your provide our community with all the necessary information to
-- Does my question fit the direction of the discussion, or should I open a new discussion?
+  understand your question and help you quickly, or can you make it easier to
-- Is my topic a question for the discussion boards, or is it a bug report or idea request that requires a new issue?
+  help you?
-- Did I provide the community with all the necessary information to comprehend my question?
-- Have I checked if my question has been answered before?
 
-### Before leaving a comment, rethink:
+### Before commenting
 
-- Is my comment directly related to the topic of this page, e.g., blog post or discussion?
+- Is your comment relevant to the topic of the current page, post, issue, or
-- Is it a comment or a request?
+  discussion, or is it a better idea to create a new issue or discussion?
-- Should I use the discussion board for my request or comment instead?
-- Does my comment add value to the conversation?
-- Is my comment respectful and constructive?
 
----
+- 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 (CoC)
+  [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/
-With a large community like ours, it's essential to follow the rules of our
-[Code of Conduct] and value the standards of acceptable behavior. Please take a 
-moment to read through our [Code of Conduct], which can always be found 
-in full on our documentation. Please pay particular attention to our key values 
-and keep them in mind when participating in any interactions within this project.
-
-### Our key values
-
-:material-handshake: Treat the community and the maintainers with respect
-
-:material-comment-text-multiple: Use welcoming, inclusive, and respectful language
-
-:material-account-group: Embrace and understand different viewpoints and experiences
-
-:material-checkbox-multiple-marked-circle: Accept decisions from the maintainers, even if things are not going your way
-
-:material-heart-multiple: Focus on what's best for the community and show empathy towards other community members
-
----
 
 ## Rights and responsibilities
 
 As maintainers, we reserve the right and have the responsibility to close,
-remove, reject, or edit contributions, such as issues, comments, or commits, 
+remove, reject, or edit contributions, such as issues, discussions, comments,
-that do not align with our contribution guidelines and our [Code of Conduct].
+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 information that is crucial to us when reviewing and 
+carefully assessed the essential requirements when reviewing and responding to
-responding to issues. Each field in our issue templates has been thoughtfully 
+issues. Each field in our issue templates has been thoughtfully curated, helping
-curated, requesting only the necessary information to understand your report or 
+us to understand your matter.
-request. Therefore, it is mandatory for you to fill out every field as requested 
-to the best of your knowledge without questioning the issue template. Trust us, 
-we need this information because it ensures that every user and project
-maintainer, regardless of experience, can understand the content and severity of 
-your report or request.
 
-> __Please note that we reserve the right to close issues__ missing essential 
+__Therefore, it is mandatory to fill out every field as requested__ to the best
-> information, such as minimal reproductions, or that do not comply with 
+of your knowledge. We need all of this information because it ensures that every
-> the quality standards and requirements stated in the issue template. Issues 
+user and maintainer, regardless of their experience, can understand the content
-> can be reopened once the missing information has been provided.
+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.
 
-### CoC violations
+  [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 
+treat each other with respect, and use inclusive and welcoming language. We
-strive to create a positive and supportive environment and consider any 
+always strive to create a positive and supportive environment and do not accept
-inappropriate, threatening, offensive, or harmful behavior violating our Code of 
+inappropriate, offensive, or harmful behavior.
-Conduct. We take such violations seriously and will take appropriate action in 
-response.
-
-> __Please note__ that we __reserve the right and have the responsibility to remove, edit, or reject any contributions__,
-> including comments, commits, and issues, that violate our Code of Conduct. We 
-> may also temporarily or permanently ban users found to be violating of the CoC 
-> from contributing to or interacting in the project.
-
-  [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/
-  [Code of Conduct]: https://github.com/squidfunk/mkdocs-material/blob/master/CODE_OF_CONDUCT.md
 
+We take violations seriously and will take appropriate action in response.

docs/contributing/reporting-a-bug.md

@@ -1,4 +1,4 @@
-# Bug reporting
+# 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
@@ -9,12 +9,12 @@ public [issue tracker], following this guide.
 
 ## Before creating an issue
 
-With more than 20.000 users, issues are created every other day. The maintainers
+With more than 20,000 users, issues are created every other day. The maintainers
 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,7 +63,7 @@ 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/issues
@@ -118,8 +118,8 @@ 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
+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:
 
@@ -152,7 +152,7 @@ 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 }
 
@@ -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: 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
@@ -263,17 +263,17 @@ automatically upload it to GitHub.
     Additionally, there are many non-technical users of Material for MkDocs that
     have trouble creating repositories.
 
-  [Create reproduction]: reproduction.md
+  [Create reproduction]: ../guides/creating-a-reproduction.md
-  [built-in info plugin]: 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
-and 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.
@@ -287,9 +287,13 @@ five-year-old, and focus on continuity.
 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. Moreover, to verify that a browser 
+[previewing] or [building] your site.
-extension is not the source of the bug, test if the issue persists when 
+
-switching to incognito mode.
+---
+
+: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

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

@@ -1,76 +1,91 @@
-# Documentation issue reporting
+# Documentation issues
 
-The documentation for Material for MkDocs is spread across more than 60 pages 
+Our documentation is composed of more than 80 pages and includes extensive
-and covers information about its features, configurations, and everything you 
+information on features, configurations, customizations, and much more. If you
-need to take advantage of Material for MkDocs' full capabilities. If you have 
+have found an inconsistency or see room for improvement, please follow this
-found an inconsistency, an issue, or see room for improvement in the 
+guide to submit an issue on our [issue tracker].
-documentation, please submit an issue to our public [issue tracker] by following 
-this guide.
 
   [issue tracker]: https://github.com/squidfunk/mkdocs-material/issues
 
-## Documentation issue template
+## Issue template
 
-Reporting something in the documentation differs from reporting a bug in the code. 
+Reporting a documentation issue is usually less involved than reporting a bug,
-Please thoroughly read the following guide before creating a new documentation 
+as we don't need a [reproduction]. Please thoroughly read this guide before
-issue.
+creating a new documentation issue, and provide the following information as
+part of the issue:
+
+- [Title]
+- [Description]
+- [Related links]
+- [Proposed change] <small>optional</small>
+- [Checklist]
+
+  [reproduction]: ../guides/creating-a-reproduction.md
+  [Title]: #title
+  [Description]: #description
+  [Related links]: #related-links
+  [Proposed change]: #proposed-change
+  [Checklist]: #checklist
 
 ### Title
 
-An excellent documentation issue title should be a short, one-sentence 
+A good title should be a short, one-sentence description of the issue, contain
-description of the issue and contain all relevant information and, in particular 
+all relevant information and, in particular, keywords to simplify the search in
-keywords  – to simplify the search in the issue tracker.
+our issue tracker.
 
 | <!-- --> | Example  |
 | -------- | -------- |
-| :material-check:{ style="color: #4DB6AC" } __Clear__ | wrong feature flag code.action
+| :material-check:{ style="color: #4DB6AC" } __Clear__ | Clarify social cards setup on Windows
-| :material-close:{ style="color: #EF5350" } __Unclear__ | Missing information 
+| :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
 
 Provide a clear and concise summary of the inconsistency or issue you
 encountered in the documentation or the documentation section that needs
 improvement. Explain why you think the documentation should be adjusted and
-describe the severity of the issue. 
+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.
+    precisely explained in one or two sentences, perfect. Maintainers and future
+    users will be grateful for having to read less.
 
--   __One issue at a time__ – if you encounter multiple unrelated inconsistencies 
+-   __One issue at a time__ – if you encounter several unrelated inconsistencies,
-    or issues on different documentation sites, please create separate issues. 
+    please create separate issues for them. Don't report them in the same issue
-    Don't report multiple issues in one issue report, which makes identifying 
+    – it makes attribution difficult.
-    them difficult.
 
-> __Why we need this__: for us to understand the issue you have found or the 
+> __Why we need this__: describing the problem clearly and concisely is a
-> clarification of the documentation needs, we ask for a description and 
+> prerequisite for improving our documentation – we need to understand what's
-> explanation of the serenity.
+> wrong, so we can fix it.
 
-### Links to the documentation
+### Related links
 
 After you described the documentation section that needs to be adjusted above,
-we now ask you to share the link to this specific documentation section. Make 
+we now ask you to share the link to this specific documentation section and
-sure you link to the sub-pages and anchor the headings directly.
+other possibly related sections. Make sure to use anchor links (permanent links)
+where possible, as it simplifies discovery.
 
-> __Why we need this__: providing the link to the documentation helps us 
+> __Why we need this__: providing the links to the documentation help us
 > understand which sections of our documentation need to be adjusted, extended,
 > or overhauled.
 
-### Improvement proposals
 
-Now that you have provided us with the description and link to the 
+### Proposed change <small>optional</small> { #proposed-change }
-documentation, you can help us, maintainers, and the community by proposing an 
-improvement. This can be a suggestion, a fix, or a temporary workaround.
 
-> __Why we need this__: improvement proposal can be beneficial for other users 
+Now that you have provided us with the description and links to the
-> who encounter the same issue, since it will offer them a temporary solution 
+documentation sections, you can help us, maintainers, and the community by
-> until we maintainers can update the documentation.
+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__: an improvement proposal can be beneficial for other
+> users who encounter the same issue, as they offer solutions before we
+> maintainers can update the documentation.
 
 ### Checklist
 
-Thanks for following the documentation issue reporting guide and creating a 
+Thanks for following the guide and providing valuable feedback for our
-high-quality documentation issue report. The checklist ensures that you have read 
+documentation – you are almost done. The checklist ensures that you have read
 this guide and have worked to your best knowledge to provide us with every piece
-of information we need to improve the Material for MkDocs 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
@@ -22,43 +22,51 @@ implementation.
 
 ## Before creating an issue
 
-Before you invest your time in filling out and submit a change request, we kindly
+Before you invest your time to fill out and submit a change request, we kindly
 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]
 
-  [Start a discussion]: https://github.com/squidfunk/mkdocs-material/discussions
+  [^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
 
 ## Issue template
 
@@ -86,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  |
@@ -94,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,7 +120,14 @@ relevant. Don't write about the change request here.
 
 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
-in one of its dependencies:
+in one of its dependencies:[^2]
+
+  [^2]:
+    Sometimes, users suggest ideas on our [issue tracker] that concern one of
+    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.
 
 -   __Explain the <u>what</u>, not the <u>why</u>__ – don't explain
     [the benefits of your idea][Use cases] here, we're getting there.
@@ -136,17 +151,20 @@ 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.
 
+  [Python Markdown]: https://python-markdown.github.io/extensions/
+  [Python Markdown Extensions]: https://facelessuser.github.io/pymdown-extensions/
+
 ### 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
 
@@ -173,18 +191,18 @@ 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. The checklist 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 your best knowledge to provide us with every piece of information to
 review your idea for Material for MkDocs.
 
@@ -192,58 +210,32 @@ __We'll take it from here.__
 
 ---
 
-## Your change request was rejected?
+## Rejected requests
 
-We're sorry that your change request didn't make the cut. We understand it can 
+__Your change request got rejected? We're sorry for that.__ We understand it can
-be frustrating when your ideas don't get accepted. We want you to know that as 
+be frustrating when your ideas don't get accepted, but as the maintainers of a
-project maintainers, we have to weigh the community's needs as a whole, and 
+very popular project, we always need to consider the needs of our entire
-sometimes that means making tough decisions. We always try to consider many 
+community, sometimes forcing us to make tough decisions.
-factors when evaluating change requests, and we'll explain the reasoning behind 
-our decisions whenever we can. If you're unsure why your request was turned 
-down, please ask for clarification.
 
-### Common reasons
+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.
 
-To provide you with some insight as to why your idea may have been rejected, 
+The following principles (in no particular order) form the basis for our
-it's possible that it didn't align with the project's goals and direction or 
+decisions:
-the available resources. Here are a few common reasons for rejections:
 
-> __Your idea may not...__
+- [ ] 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
 
-> - match the overall tone or vision of this project
+But that's not the end of your idea – you can always implement it on your own
-> - be compatible with existing features, themes, or plugins
+via [customization]. If you're unsure about how to do that or want to know if
-> - be useful to the majority of users
+someone has already done it, feel free to get in touch with our community on
-> - be user-friendly for authors
+the [discussion board].
-> - be implemented in an accessible way
-> - be implemented with reasonable effort
-> - be implemented using the [principle of progressive enhancement]
-> - be implemented to work on all screen sizes
-> - be implemented to work on all modern browsers
 
-
+  [customization]: ../customization.md
-We highly value and appreciate every idea and contribution you bring to the 
-table, and we encourage you to keep sharing them with us. Some of these ideas 
-might even be implemented by us! However, we want to remind you that you also 
-have the power to implement your ideas on your own by customizing the theme. If 
-you're unsure about how to realize your ideas or want to know if someone has 
-already found a solution, feel free to visit our [discussion board] - it's the 
-perfect place for you!
-
- [discussion board]: https://github.com/squidfunk/mkdocs-material/discussions
- [principle of progressive enhancement]: https://developer.mozilla.org/en-US/docs/Glossary/Progressive_Enhancement?retiredLocale=de
-
-### Dependencies
-
-Occasionally, users propose ideas on our [issue tracker] that concern one of our 
-upstream [dependencies], such as [MkDocs], [Python Markdown],
-[Python Markdown Extensions] or third-party plugins. In such cases, it's 
-worthwhile to consider whether your idea could benefit other themes as well. If 
-so, you might want to consider submitting a change request upstream to have a 
-greater impact.
-
-  [dependencies]: https://squidfunk.github.io/mkdocs-material/setup/dependencies/image-processing/
-  [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
-  [dependencies]: #dependencies

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 the ymight
+(although rarely) change at any time, including their complete removal (which
+hasn't happened yet).
+
+### <!-- md:plugin --> – Plugin { data-toc-label="Plugin" }
+
+Several features are implemented through MkDocs excellent plugin architecture,
+some of which are built-in and distributed with Material for MkDocs, so no
+installation is required.
+
+### <!-- md: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/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

docs/enterprise-support.md

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

docs/faq/sponsoring.md

@@ -0,0 +1,481 @@
+# Sponsoring FAQs
+
+Do you have questions about Material for MkDocs Insiders? We do our best to
+answer all of your questions on this page. If you can't find your question 
+below, ask it on our [discussion board]!
+
+  [discussion board]: https://github.com/squidfunk/mkdocs-material/discussions/new/chooses
+
+## General	
+
+[__Why is the Insiders edition offered as a subscription model?__](#insiders-subscription){ #insiders-subscription }
+
+Material for MkDocs always was and will be Open Source, available for free to
+individuals and organizations. As the project grew over time, we found that
+maintaining and managing the overhead that comes with growth became more
+challenging and time-consuming.
+
+In order to sustain the project and add new and useful features more frequently,
+we decided to create the [Insiders] edition, with early access to the latest and
+greatest features of Material for MkDocs. The subscription-based model of the
+Insiders edition allows us to dedicate more time and resources to the project,
+which benefits all 
+users of Material for MkDocs. Once our funding goals based on monthly 
+subscriptions are hit, the Insiders features of those^ funding goals are released 
+to the community edition, letting everyone benefit from them. 
+
+Maintaining both the community and Insiders editions is an ongoing process, and 
+we rely on our sponsors to support us on a monthly basis, which makes this whole 
+project possible.
+
+[__What features are included in the Insiders edition?__](#insiders-features){ #insiders-features }
+
+The Insiders edition includes more than 20 additional features. You can find an 
+overview of these features on our [Insiders page], which is updated when new
+features are added and released.
+
+  [Insiders]: ../insiders/index.md
+  [Insiders page]: ../insiders/index.md#whats-in-it-for-me
+
+[__How often is the Insiders edition updated?__](#insiders-updates){ #insiders-updates }
+
+We try to keep our open issue count low, fixing known bugs quickly. Both our
+repositories, the community and Insiders edition, are constantly updated with
+bug fixes and new features.
+
+## Sponsorship	
+
+[__Can I sponsor the project without a GitHub account?__](#sponsorship-account){ #sponsorship-account }
+
+Yes. You can support Material for MkDocs by sponsoring us on [Ko-fi], regardless
+of whether you have a GitHub account or not. However, please note that Insiders
+is provided as a private repository on GitHub. If after sponsoring, you'd like to
+gain access to the repository, you'll need to have a GitHub individual or bot
+account that can be added as a collaborator. If your organization doesn't use
+GitHub or/and host its repositories on other platforms, you can mirror the
+Insiders repository in your environment once you have access.
+
+[__Which sponsoring tier should I choose?__](#sponsorship-tier){ #sponsorship-tier }
+
+The sponsoring tiers are divided into non-commercial and commercial tiers. If 
+you are an individual or organization using Material for MkDocs for private or
+__non-commercial__ Open Source projects, you have two tiers to choose from, 
+depending on the number of sites you want to build. For companies using 
+Material for MkDocs, we offer three different __commercial__ tiers, from which 
+you can choose depending on your requirements.
+
+Also, please read what is considered [commercial use].
+
+  [commercial use]: #commercial-use
+
+[__Why are one-time sponsorships not granted access to Insiders?__](#sponsorship-one-time){ #sponsorship-one-time }
+
+Primarily due to technical reasons, that we're working on lifting in the future.
+We use GitHub webhooks to determine our current active sponsors. When you create
+or cancel your monthly subscription, GitHub sends events that we use to
+automatically add and remove collaborators.
+
+Note that [$15] is the minimum amount to be granted access to Insiders.
+
+  [$15]: https://github.com/sponsors/squidfunk/sponsorships?tier_id=210638
+
+[__How are sponsorship contributions used?__](#sponsorship-support){ #sponsorship-support }
+
+It's vital to recognize that the total sponsorship amount doesn't directly
+translate into the funds we have available for use. The way we allocate
+sponsorship amounts is detailed as follows:
+
+1.  __Taxes__: Since we provide a service to our sponsors, we're of course
+    legally obligated to pay sales tax. This requirement applies to all
+    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 }
+
+No, there are no limitations on the number of sponsors for any tier. You can
+sponsor the project at any tier regardless of how many other sponsors are
+already there.
+
+## Payment & billing	
+
+[__Is there a trial period for the Insiders edition?__](#insiders-trial){ #insiders-trial }
+
+No, we do not offer a trial period for the Insiders edition. However, if you're
+a company and are considering sponsoring on the commercial tier, but want to
+first give the Insiders edition a try, you can sponsor on the [$15] tier with a
+personal account for non-commercial evaluation purposes.
+
+Additionally, our subscription model allows you to cancel your sponsorship
+anytime. If you decide to cancel, your sponsorship will remain active until 
+the end of your billing cycle.
+
+[__What payment options do you accept?__](#insiders-payment){ #insiders-payment }
+
+We manage all our transactions and sponsorships through [GitHub Sponsors] and 
+[Ko-fi]. To become a sponsor of Material for MkDocs on GitHub, visit 
+[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, 
+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,
+please don't hesitate to reach out to sponsors@squidfunk.com.
+
+  [Ko-fi]: https://ko-fi.com/squidfunk
+  [GitHub Sponsors]: https://github.com/sponsors
+  [GitHub no longer supports PayPal]: https://github.blog/changelog/2023-01-23-github-sponsors-will-stop-supporting-paypal/
+  [our sponsors' page]: https://github.com/sponsors/squidfunk/
+
+[__Are discounts available for the Insiders edition, such as student discounts?__](#insiders-discounts){ #insiders-discounts }
+
+Unfortunately, we are not able to offer any discounts for the Material for 
+MkDocs Insiders program. To ensure that everyone can afford the Insiders program 
+and keep the barrier as low as possible, we have set prices as low as [$15] a
+month for non-commercial use.
+
+[__Do you offer free access to Insiders for Open Source projects?__](#insiders-open-source){ #insiders-open-source }
+
+No, we do not offer free access to our Material for MkDocs Insiders edition. 
+We understand that non-profit organizations may have limited budgets and may 
+need to prioritize their spending on other projects or organizations. However,
+it's important to note that Material for MkDocs is maintained by a small team, 
+investing a lot of time and resources into constantly improving this project. 
+Material for MkDocs and its core features are free to the community through our 
+Open Source model. Therefore, Material for MkDocs itself is already free.
+
+However, we do offer an affordable sponsorship tier starting at [$15] a month, 
+which is meant for individuals and non-profit organizations using Material for 
+MkDocs to build 1-2 sites for non-commercial purposes. This tier provides access 
+to all new features, benefiting you from our ongoing development efforts.
+
+[__Is Insiders free for those who contribute to this project?__](#insiders-contributors){ #insiders-contributors }
+
+Great question! We can not offer free access to "drive-by" contributors that 
+only fix minor issues like typos or add new languages. These contributions are 
+always welcome, but as we need to review them, they result in a higher time 
+investment from our side and don't compensate for this work. However, as this 
+project keeps growing, we always seek for individuals to support us. In return, 
+we offer financial compensation or/and Insiders access. If you are interested 
+and have experience in the technologies and paradigms listed below, please get
+in touch with us at sponsors@squidfunk.com:
+
+- Deep knowledge of CSS, HTML, TypeScript
+- Experience with progressive enhancement and responsive design
+- Experience with reactive programming with RxJS
+- Solid understanding of Python, MkDocs + ecosystem
+- Solid technical writing skills
+
+Additionally, we're working on a contributor program that will reward
+contributors that engage in the community by answering questions and helping
+users with access to Insiders.
+
+[__How can I set my billing to monthly or yearly?__](#insiders-billing-cycle){ #insiders-billing-cycle }
+
+You can sponsor Material for MkDocs on a monthly or yearly basis. Depending on 
+your billing cycle you automatically become a monthly or yearly sponsor. Your 
+[billing cycle] is an account-level setting that you can easily change in your 
+account. If, for some reason, you cannot make this change, you can create a 
+dedicated bot account with a yearly billing cycle on GitHub, which you only use 
+for sponsoring (some sponsors already do that). If you have any problems or 
+further questions, please contact us at sponsors@squidfunk.com.
+
+  [billing cycle]: https://docs.github.com/en/github/setting-up-and-managing-billing-and-payments-on-github/changing-the-duration-of-your-billing-cycle
+
+[__Can I get an invoice for my sponsorship payment?__](#insiders-invoice){ #insiders-invoice}
+
+Right now, we can't provide you with an invoice for your sponsoring transaction,
+as [GitHub Sponsors] handles all transactions for us. However, both payment
+platforms, [GitHub] and [Ko-Fi], automatically send you a payment receipt 
+via mail once the sponsorship is active.
+
+Furthermore, we are working on a solution to optimize access management and more
+features. If you are interested in this, please get in touch with us via mail at
+sponsors@squidfunk.com or turn on all notifications for MkDocs, and we will
+reach out as soon as we are live.
+
+  [GitHub]: https://github.com/sponsors/squidfunk/
+
+[__Can I switch between different sponsoring tiers?__](#insiders-switch-tiers){ #insiders-switch-tiers }
+
+Yes, you can switch between different sponsoring tiers at any time. Simply go 
+to the [GitHub Sponsors] page and change your sponsoring tier. Once you make 
+that change, you will immediately change to the new tier.
+
+If you change to a higher tier, the amount will be prorated according to your
+billing cycle.
+
+[__Can I sponsor the project for a specific feature or development goal?__](#insiders-goals){ #insiders-goals }
+
+While sponsoring specific goals directly is not possible, our sponsoring goals
+are connected to specific features or development goals aligned with the 
+project's roadmap. You can find an [overview of these sponsoring goals] and their 
+associated features on our website. Insider users have early access to all 
+already developed features, including those associated with higher funding goals 
+that will be reached at a later stage. If you're interested in accessing these 
+features, becoming a sponsor is the way to go. If you have a feature in mind 
+that you would like to see on the list, we encourage you to 
+[initiate a new discussion] to evaluate it with others.
+
+  [overview of these sponsoring goals]: ../insiders/index.md#goals
+  [initiate a new discussion]: https://github.com/squidfunk/mkdocs-material/discussions/new/chooses
+
+[__What happens if I reach my sponsoring limit for my current tier?__](#insiders-limit){ #insiders-limit }
+
+If you extend the number of sites that are in your current sponsoring limit, 
+please [upgrade your sponsorship] to a higher tier to continue using the 
+Insiders version and build more sites. The change will be effective immediately.
+
+  [upgrade your sponsorship]: https://docs.github.com/en/billing/managing-billing-for-github-sponsors/upgrading-a-sponsorship
+
+[__Do you offer refunds for sponsoring payments?__](#insiders-refunds){ #insiders-refunds }
+
+Unfortunately, we cannot offer any refund for sponsorship payments. 
+[GitHub Sponsors] and [Ko-Fi] manage all sponsoring transactions. Because of 
+that, we do not have any insights into the details of the funds and cannot access 
+them. If you have any payment issues, please get in touch with the GitHub 
+or Ko-Fi support team, as they can help you.
+
+## Access management	
+
+[__How do I gain access to the private Insiders repository?__](#access-account){ #access-account }
+
+If you sponsored with your __individual account__, you should have received an 
+email invitation to the private Material for MkDocs Insiders repository right 
+after you initiated your sponsorship. Simply accept the invitation within seven 
+days to gain access.
+
+If you sponsored using an __organization account__, please note we need 
+an individual account that we can list as a collaborator of the private Insiders 
+repository. After you initiate your sponsorship, please email us at 
+sponsors@squidfunk.com with the name of the individual or bot account. Once you 
+provide us with this information, we will add the account as a collaborator, and 
+after you accept the invitation, you will gain access to the repository.
+
+If you have yet to receive the email or the invitation link has expired, please 
+contact us, the maintainers, at sponsors@squidfunk.com. We're working on a
+solution that will allow you to manage collaborator status yourself.
+
+[__Why can't our whole organization get access to Insiders?__](#access-organization){ #access-organization }
+
+Currently, it is not possible to grant access to an organizational account, as 
+GitHub only allows for adding individual user accounts. We are working on a 
+solution ourselves to simplify access for organizations. For now, to ensure that 
+access is not tied to a particular individual, we recommend creating a bot 
+account, i.e., a GitHub account that does not belong to a specific individual 
+but is listed as the owner of the organizational account and using this account 
+for sponsorship.
+
+[__Do I need to fork the repository to use it?__](#access-fork){ #access-fork }
+
+It depends. If you are using the Insiders edition as an individual, you can work
+directly with the private repository, as you do not need to share the Insiders
+features with others. If you are working with a team, it is best to create a
+private fork using the individual account you listed as a collaborator of
+Material for MkDocs to grant access to all members of your organization to
+your fork.
+
+[__Can I share my Insiders access with others?__](#access-share){ #access-share }
+
+At the moment, it is not possible to directly share your collaborator status 
+for the private Insiders repository with other accounts. However, if you are 
+working with a team and would like them to access Insiders, you can share the 
+Insiders repository by utilizing options such as [cloning], [forking], or 
+[mirroring]. By doing so, you can start collaborating with your team members on 
+the new repository you have shared. This way, you can collectively benefit 
+from the Insiders features and work together on the project.
+
+  [cloning]: https://docs.github.com/en/repositories/creating-and-managing-repositories/cloning-a-repository
+  [forking]: https://docs.github.com/en/get-started/quickstart/fork-a-repo
+  [mirroring]: https://docs.github.com/en/repositories/creating-and-managing-repositories/duplicating-a-repository
+
+
+## Runtime & cancellation	
+
+[__How long is my sponsorship valid?__](#sponsorship-runtime){ #sponsorship-runtime }
+
+Your sponsorship is valid for as long as your monthly or yearly subscription
+is valid. If you choose to cancel your sponsorship, you will lose access to 
+the Insiders edition once your cancelation is active and will be automatically 
+removed by GitHub as a collaborator from the private repository. 
+
+[__How do I cancel my sponsorship?__](#sponsorship-cancellation){ #sponsorship-cancellation }
+
+To cancel your sponsorship, follow the [step-by-step guide] provided by GitHub. 
+If you sponsored using an organizational account, please ensure that you cancel 
+your sponsorship using the same organizational account rather than your 
+individual account.
+
+  [step-by-step guide]: https://docs.github.com/en/billing/managing-billing-for-github-sponsors/downgrading-a-sponsorship
+
+[__What happens when I cancel my sponsorship?__](#sponsorship-cancellation-effective){ #sponsorship-cancellation-effective }
+
+If you choose to cancel your subscription to Insiders, you will be 
+automatically removed by GitHub as a collaborator on the day your cancellation is 
+effective. From that day on, you will no longer receive future updates. However, 
+you are __welcome to continue using the latest version__ that was available to 
+you at the time of your cancellation for as long as you like.
+
+Please note that [GitHub deletes private forks], so you may want to take steps to ensure
+that you have a backup of the software if necessary and use the locally installed version.
+
+  [GitHub deletes private forks]: https://docs.github.com/en/account-and-profile/setting-up-and-managing-your-personal-account-on-github/managing-access-to-your-personal-repositories/removing-a-collaborator-from-a-personal-repository#deleting-forks-of-private-repositories
+
+## Licensing	
+
+[__What constitutes commercial use of the Insiders version?__](#commercial-use){ #commercial-use }
+
+Commercial use refers to any use of the software for a business or for-profit 
+purpose. This includes any use by a corporation or other organization, whether 
+or not they generate revenue directly from the software. We offer different 
+pricing tiers for commercial use, each tailored to the needs of different 
+businesses. It's important to note that internal use of the software within your 
+organization is also considered commercial use, as with all commercial software.
+
+[__What constitutes non-commercial use of the Insiders version?__](#non-commercial-use){ #non-commercial-use }
+
+Non-commercial use of our Material for MkDocs refers to private use. This
+includes individuals using the Insiders edition for private or purely
+non-commercial Open Source projects. We offer two different tiers for
+non-commercial use, depending on the number of sites you want to build.  
+
+[__What is your fair use policy?__](#fair-use-policy){ #fair-use-policy }
+
+Our fair use policy includes the following guidelines:
+
+- Please refrain from __distributing the source code__ of Insiders. While you 
+may use the software for public, private, or commercial projects and may 
+privately fork or mirror it, we ask that you keep the source code private. This 
+is important to our sponsorware strategy, which helps us fund ongoing 
+development and support of the software. If this guidelines is violated,
+everybody loses, as it will reduce the time of us maintainers we can set aside
+to push this project forward.
+
+- As our sponsoring tiers are based on the number of sites you want to build, 
+please make sure to [upgrade your sponsorship] once your current sponsoring tier 
+limit has been reached. 
+
+[__Does the Insiders version have a different license?__](#insiders-license){ #insiders-license }
+
+No. Whether you're an individual or a company, you may use Material for 
+MkDocs Insiders precisely under the same terms as Material for MkDocs, which are 
+given by the [MIT license].
+
+[MIT license]: ../license.md
+
+[__Can outside collaborators build and run the documentation locally without access to Insiders?__](#insiders-outside-collaborators){ #insiders-outside-collaborators }
+
+Yes. Insiders is compatible with Material for MkDocs. Almost all new features
+and configuration options are either backward-compatible or implemented behind
+feature flags. When working with outside collaborators, changing the general 
+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 feature in Insiders that non-Insiders users can't properly 
+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 
+build it with Insiders. When using built-in plugins exclusive to Insiders, it's 
+recommended to split configuration into a base `mkdocs.yml` and one with plugin 
+overrides via [configuration inheritance].
+
+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
+  [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 }
+
+If you have any questions and would like to contact us before starting your 
+sponsorship, we are happy to answer all your non-technical questions about the 
+Insiders program via email at sponsors@squidfunk.com.
+
+All technical questions should be asked openly on our [discussion board].
+
+  [discussion board]: https://github.com/squidfunk/mkdocs-material/discussions
+
+[__Is additional support available for Material for MkDocs Insiders users?__](#support-additional){ #support-additional }
+
+Yes, we provide non-technical support related to sponsoring at
+sponsors@squidfunk.com. For technical questions, please submit an issue openly 
+on our [issue tracker] or start a discussion on our [discussion board]. Issues 
+and discussions from our organizational sponsors, sponsoring on 
+__The Organization__ tier or higher will be prioritized.[^1]
+
+  [^1]:
+    Priority support means we will prioritize your issue, meaning we will look 
+    into it and do our best to solve your issue asap. However, the prioritized bug 
+    support does not mean that we can solve your issue before any others since 
+    some issues might take more time to solve.
+
+  [issue tracker]: https://github.com/squidfunk/mkdocs-material/issues
+
+[__How can I display my logo on the list of premium sponsors?__](#sponsorship-logo-placement){ #sponsorship-logo-placement }
+
+If your sponsorship tier includes logo placement, and you would like us to
+display your logo in the [list of premium sponsors] and have it linked to your
+site, please contact us via mail. Simply send us a horizontal SVG or PNG version
+of your logo making sure it displays the name of your company and the logo to
+sponsors@squidfunk.com. 
+
+  [list of premium sponsors]: https://github.com/squidfunk/mkdocs-material#user-content-premium-sponsors
+
+[__Is logo placement optional?__](#sponsorship-logo-placement-optional){ #sponsorship-logo-placement-optional }
+
+Yes, all of our commercial benefits, such as logo placement and backlinks, are 
+optional and can be opted in or out at any time. You can keep your sponsorship
+completely private.
+
+[__How can I report a bug in the Insiders version?__](#insiders-bugs){ #insiders-bugs }
+
+If you encounter a bug in the Insiders edition, we kindly request that you 
+report it on our [issue tracker] in the public community repository. When 
+submitting the bug report, please ensure that you do not include any private 
+Insiders' source code, as we want to uphold our fair use policy. 
+
+
+## Privacy	
+
+[__Will you sign an NDA for sponsorships?__](#nda){ #nda }
+
+Unfortunately, we cannot sign any NDA or vendor agreement form. As a small team
+working on Material for MkDocs, we have limited resources and cannot review 
+and sign agreements.
+
+[__Can I sponsor privately?__](#sponsorship-private){ #sponsorship-private }
+
+Yes, you can. GitHub gives you the option to set your sponsorship to [private] 
+when you set up your sponsorship. Additionally, we have a recommended workflow 
+for you: We suggest you create a new GitHub bot account. This bot account should 
+not be tied to a particular individual and should be privately listed as an 
+owner of your GitHub organization. This account can then be used to sponsor 
+Material for MkDocs privately. As a bot account, it will automatically be listed 
+as a collaborator of the private Insiders repository. You can clone, fork, or 
+mirror using this account. All information will be kept confidential; only the 
+bot account and us maintainers will have insights into his sponsorship. 
+
+  [private]: https://docs.github.com/en/sponsors/sponsoring-open-source-contributors/managing-your-sponsorship#managing-the-privacy-setting-for-your-sponsorship
+
+[__Are there any geographical restrictions on becoming a sponsor?__](#sponsorship-geo){ #sponsorship-geo }
+
+No, there are no geographical restrictions for becoming a sponsor. We welcome 
+sponsorships from individuals and organizations worldwide. As long as your 
+credit card is valid and accepted by GitHub or Ko-Fi, you are eligible to become 
+a sponsor and support the project, regardless of your location. 

docs/getting-started.md

@@ -1,9 +1,16 @@
 # Getting started
 
-Material for MkDocs is a theme for [MkDocs], a static site generator geared
+Material for MkDocs is a powerful documentation framework on top of [MkDocs],
-towards (technical) project documentation. If you're familiar with Python, you
+a static site generator for project documentation.[^1] If you're familiar with
-can install Material for MkDocs with [`pip`][pip], the Python package manager.
+Python, you can install Material for MkDocs with [`pip`][pip], the Python
-If not, we recommend using [`docker`][docker].
+package manager. If not, we recommend using [`docker`][docker].
+
+  [^1]:
+    In 2016, Material for MkDocs started out as a simple theme for MkDocs, but
+    over the course of several years, it's now much more than that – with the
+    many built-in plugins, settings, and countless customization abilities,
+    Material for MkDocs is now one of the simplest and most powerful frameworks
+    for creating documentation for your project.
 
   [MkDocs]: https://www.mkdocs.org
   [pip]: #with-pip
@@ -29,7 +36,7 @@ Material for MkDocs with:
     pip install mkdocs-material=="9.*" # (1)!
     ```
 
-    1.  Material for MkDocs uses [semantic versioning][^1], which is why it's a
+    1.  Material for MkDocs uses [semantic versioning][^2], which is why it's a
         good idea to limit upgrades to the current major version.
 
         This will make sure that you don't accidentally [upgrade to the next
@@ -47,7 +54,7 @@ Material for MkDocs with:
         pip install -r requirements.txt
         ```
 
-  [^1]:
+  [^2]:
     Note that improvements of existing features are sometimes released as
     patch releases, like for example improved rendering of content tabs, as
     they're not considered to be new features.
@@ -61,8 +68,8 @@ install those packages separately.
 
 :fontawesome-brands-youtube:{ style="color: #EE0F0F" }
 __[How to set up Material for MkDocs]__ by @james-willett – :octicons-clock-24:
-15m – Learn how to create and host a documentation site using Material for Docs
+15m – Learn how to create and host a documentation site using Material for
-on GitHub Pages in a step-by-step guide.
+MkDocs on GitHub Pages in a step-by-step guide.
 
   [How to set up Material for MkDocs]: https://www.youtube.com/watch?v=Q-YA_dA8C20
 
@@ -117,20 +124,37 @@ The following plugins are bundled with the Docker image:
 
     Material for MkDocs only bundles selected plugins in order to keep the size
     of the official image small. If the plugin you want to use is not included,
-    create a new `Dockerfile` and extend the official Docker image:
+    you can add them easily:
 
-    ``` Dockerfile
+    === "Material for MkDocs"
+
+        Create a `Dockerfile` and extend the official image:
+
+        ``` Dockerfile title="Dockerfile"
         FROM squidfunk/mkdocs-material
-    RUN pip install ...
+        RUN pip install mkdocs-macros-plugin
+        RUN pip install mkdocs-glightbox
         ```
 
-    Next, you can build the image with the following command:
+    === "Insiders"
+
+        Clone or fork the Insiders repository, and create a file called
+        `user-requirements.txt` in the root of the repository. Then, add the
+        plugins that should be installed to the file, e.g.:
+
+        ``` txt title="user-requirements.txt"
+        mkdocs-macros-plugin
+        mkdocs-glightbox
+        ```
+
+    Next, build the image with the following command:
 
     ```
     docker build -t squidfunk/mkdocs-material .
     ```
 
-    The new image can be used exactly like the official image.
+    The new image will have additional packages installed and can be used
+    exactly like the official image.
 
 ### with git
 
@@ -142,8 +166,7 @@ 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

docs/guides/creating-a-reproduction.md

@@ -22,12 +22,27 @@ just delete and recreate the environment. It's trivial to set up:
 
 -   Activate the environment with:
 
+    === ":material-apple: macOS"
+
         ``` sh
-    . venv/bin/activate # (1)!
+        . venv/bin/activate
         ```
 
-    1.  Your terminal should now print `(venv)` before the prompt, which is
+    === ":fontawesome-brands-windows: Windows"
-        how you know that you are inside an environment.
+
+        ``` sh
+        . venv/Scripts/activate
+        ```
+
+    === ":material-linux: Linux"
+
+        ``` sh
+        . venv/bin/activate
+        ```
+
+
+    Your terminal should now print `(venv)` before the prompt, which is how you
+    know that you are inside the virtual environment that you just created.
 
 -   Exit the environment with:
 
@@ -41,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
@@ -72,19 +87,19 @@ 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.
 
   [bug reporting guide]: ../contributing/reporting-a-bug.md#upgrade-to-latest-version
-  [minimal configuration]: ../../creating-your-site/#minimal-configuration
+  [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,172 @@
 
 ## 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
+- Improved compat in privacy plugin with third-party plugins
+- Fixed #5790: Typeset plugin ignores data-toc-label attribute
+- Fixed #5778: Interplay of privacy plugin with git-revision-date-localized
+- Fixed #5773: Info plugin erroring when community edition is in beta
+
+### 4.38.0 <small>July 29, 2023</small> { id="4.38.0" }
+
+- Added projects plugin for building nested projects
+- Updated privacy plugin to new MkDocs API
+
+### 4.37.1 <small>July 28, 2023</small> { id="4.37.1" }
+
+- Updated MkDocs to 1.5.1
+- Fixed deprecation warning in social plugin due to MkDocs upgrade
+- Fixed #5772: Privacy plugin fails due to API change in MkDocs
+
+### 4.37.0 <small>July 7, 2023</small> { id="4.37.0" }
+
+- Added support for overriding social cards settings per page
+- Added new social card `default/only/image` layout
+- Improved resilience of optimize and social plugin
+- Fixed rendering bugs for pruned navigation items
+- Fixed jumping of content tabs anchor links when instant loading is enabled
+- Fixed #5676: Optimize plugin doesn't check for `pngquant`
+
+### 4.36.1 <small>June 23, 2023</small> { id="4.36.1" }
+
+- Fixed #5618: Date comparison breaking for drafts in blog plugin
+
+### 4.36.0 <small>June 15, 2023</small> { id="4.36.0" }
+
+- Added support for instant prefetching to speed up slow connections
+- Improved stability of anchor link removal in built-in typeset plugin
+- Improved performance of regular expressions in typeset plugin
+- Removed unnecessary import test for `cairosvg` in optimize plugin
+- Fixed #5590: Regular expression for anchor link removal too greedy
+
+### 4.35.3 <small>June 1, 2023</small> { id="4.35.3" }
+
+- Fixed #5579: Abbreviations in headlines filtered by typeset plugin
+
+### 4.35.2 <small>May 29, 2023</small> { id="4.35.2" }
+
+- Fixed #5555: Blog plugin crashes when computing readtime for emojis
+
+### 4.35.1 <small>May 20, 2023</small> { id="4.35.1" }
+
+- Fixed internal handling of errors in social plugin
+
+### 4.35.0 <small>May 20, 2023</small> { id="4.35.0" }
+
+- Improve editing experience and stability of social plugin
+- Added support for custom layout syntax validation in social plugin
+- Added support for layer origin for easier placement in social plugin
+- Added support for in- and exclusion patterns in social plugin
+- Catch and print syntax errors in custom layouts
+
+### 4.34.1 <small>May 16, 2023</small> { id="4.34.1" }
+
+- Disable social plugin debug mode by default on mkdocs build
+- Added warning in social plugin debug mode when font style couldn't be found
+- Set default concurrency of built-in multi-threaded plugins to CPUs - 1
+- Fixed #5521: Social plugin triggers race condition when downloading fonts
+- Fixed #5515: Social plugin crashes when concurrency is set to 1
+
+### 4.34.0 <small>May 14, 2023</small> { id="4.34.0" }
+
+- Added support for new overflow mode to auto-fit text in social plugin
+- Reduced subtle rendering bugs in (code) annotations due to subpixel rounding
+- Improved print styles for (code) annotation lists
+- Improved performance of social plugin, now 3x as fast
+- Improved interop of typeset plugin with MkDocstrings
+- Fixed logo location for variants of default template in social plugin
+- Fixed #5446: Built-in typeset plugin picks up headings in code blocks
+
+### 4.33.2 <small>May 12, 2023</small> { id="4.33.2" }
+
+- Fixed #5508: Social plugin crashes trying to copy cards on Docker/Windows
+- Fixed #5507: Social plugin crashes on serve when layouts folder doesn't exist
+- Fixed #5505: Social plugin trying to resolve logo in wrong location
+- Fixed #5496: Annotations with nested lists incorrectly mounted
+- Fixed #5493: Social plugin crashes on Python 3.8
+
+### 4.33.1 <small>May 9, 2023</small> { id="4.33.1" }
+
+- Added support for SVG background images in social plugin
+
+### 4.33.0 <small>May 8, 2023</small> { id="4.33.0" }
+
+- Added support for custom layouts for social plugin
+- Added support for background images for social cards
+
+### 4.32.6 <small>April 22, 2023</small> { id="4.32.6" }
+
+- Fixed #5336: Interplay of blog plugin with git-revision-date-localized
+
+### 4.32.5 <small>April 7, 2023</small> { id="4.32.5" }
+
+- Fixed #5322: Navigation tabs hoist nested page icons
+
 ### 4.32.4 <small>March 24, 2023</small> { id="4.32.4" }
 
 - Fixed #5241: Built-in typeset plugin jams navigation for anchors in headings

docs/insiders/getting-started.md

@@ -79,13 +79,16 @@ docker login -u ${GH_USERNAME} -p ${GHCR_TOKEN} ghcr.io
 docker pull ghcr.io/${GH_USERNAME}/mkdocs-material-insiders
 ```
 
+Should you wish to add additional plugins to the insiders container image, follow the steps
+outlined in the [Getting Started guide](../getting-started.md#with-docker).
+
   [^2]:
     Earlier, Insiders provided a dedicated Docker image which was available to
     all sponsors. On March 21, 2021, the image was deprecated for the reasons
     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].
@@ -147,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:
-When using built-in plugins that are solely available via Insiders, it might be 
-necessary to split the `mkdocs.yml` configuration into a base configuration, and
-one with plugin overrides. Note that this is a limitation of MkDocs, which can
-be mitigated by using [configuration inheritance]:
-
-=== ":octicons-file-code-16: `mkdocs.insiders.yml`"
-
-    ``` yaml
-    INHERIT: mkdocs.yml
-    plugins:
   - search
   - social
-      - tags
-    ```
 
-=== ":octicons-file-code-16: `mkdocs.yml`"
+  # CI=1 mkdocs build
+  - group:
+      enabled: !ENV CI
+      plugins:
+        - git-revision-date-localized
+        - git-committers
 
-    ``` yaml
+  # INSIDERS=1 mkdocs build
-    # Configuration with everything except Insiders plugins
+  - group:
-    ```
+      enabled: !ENV INSIDERS
-
+      plugins:
-Now, when you're in an environment with access to Insiders (e.g. in your CI
+        - optimize
-pipeline), you can build your documentation project with the following lines:
+        - privacy
-
-```
-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

@@ -88,14 +88,18 @@ a handful of them, [thanks to our awesome sponsors]!
 ## What's in it for me?
 
 The moment you [become a sponsor][how to become a sponsor], you'll get __immediate
-access to 25 additional features__ that you can start using right away, and
+access to 23 additional features__ that you can __start using now__, and
 which are currently exclusively available to sponsors:
 
 <div class="mdx-columns" markdown>
 
-- [x] [Code range selection] :material-alert-decagram:{ .mdx-pulse title="Added on February 19, 2023" }
+- [x] [Projects plugin] :material-alert-decagram:{ .mdx-pulse title="Added on July 29, 2023" }
-- [x] [Code annotations: custom selectors] :material-alert-decagram:{ .mdx-pulse title="Added on February 19, 2023" }
+- [x] [Instant prefetching] :material-alert-decagram:{ .mdx-pulse title="Added on June 15, 2023" }
-- [x] [Privacy plugin: optimization support] :material-alert-decagram:{ .mdx-pulse title="Added on February 6, 2023" }
+- [x] [Social plugin: custom layouts] :material-alert-decagram:{ .mdx-pulse title="Added on May 8, 2023" }
+- [x] [Social plugin: background images] :material-alert-decagram:{ .mdx-pulse title="Added on May 8, 2023" }
+- [x] [Code range selection]
+- [x] [Code annotations: custom selectors]
+- [x] [Privacy plugin: optimization support]
 - [x] [Optimize plugin]
 - [x] [Navigation path] (Breadcrumbs)
 - [x] [Typeset plugin]
@@ -104,20 +108,14 @@ which are currently exclusively available to sponsors:
 - [x] [Tags plugin: allow list] + [custom sorting]
 - [x] [Blog plugin: custom index pages]
 - [x] [Blog plugin: related links]
-- [x] [Blog plugin]
-- [x] [Navigation status]
 - [x] [Meta plugin]
 - [x] [Tags plugin: additional indexes]
 - [x] [Document contributors]
 - [x] [Automatic light / dark mode]
 - [x] [Content tabs: anchor links]
-- [x] [Navigation pruning]
 - [x] [Tooltips]
-- [x] [Chinese search support]
 - [x] [Card grids]
 - [x] [Privacy plugin]
-- [x] [Annotations]
-- [x] [Navigation icons]
 
 </div>
 
@@ -184,18 +182,25 @@ You can cancel your sponsorship anytime.[^5]
 [![World Wide Technology]](https://wwt.com){ target=_blank title="World Wide Technology" }
 [![Coda]](https://coda.io){ target=_blank title="Coda" }
 [![Elastic]](https://elastic.co){ target=_blank title="Elastic" }
-[![Hyperledger]](https://www.hyperledger.org){ target=_blank title="Hyperledger Foundation" }
 [![IP Fabric]](https://ipfabric.io/){ target=_blank title="IP Fabric" }
 [![Apex.AI]](https://www.apex.ai/){ target=_blank title="Apex.AI" }
 [![Jitterbit]](https://jitterbit.com/){ target=_blank title="Jitterbit" }
 [![Sparkfun]](https://sparkfun.com/){ target=_blank title="Sparkfun Electronics" }
-[![Automation Technology]](https://automationtechnology.de/){ target=_blank title="Automation Technology" }
 [![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" }
+[![GetScreen.me]](https://getscreen.me/){ target=_blank title="GetScreen.me" }
+[![BotCity]](https://botcity.dev/){ target=_blank title="BotCity" }
+[![Springer Nature Technology]](https://www.springernature.com/gp){ target=_blank title="Springer Nature Technology" }
+[![Kolena]](https://kolena.io/){ target=_blank title="Kolena" }
+[![Evergiving]](https://www.evergiving.com/){ target=_blank title="Evergiving" }
+[![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>
 
@@ -213,18 +218,26 @@ You can cancel your sponsorship anytime.[^5]
   [World Wide Technology]: https://raw.githubusercontent.com/squidfunk/mkdocs-material/master/.github/assets/sponsors/sponsor-wwt.png
   [Coda]: https://raw.githubusercontent.com/squidfunk/mkdocs-material/master/.github/assets/sponsors/sponsor-coda.png
   [Elastic]: https://raw.githubusercontent.com/squidfunk/mkdocs-material/master/.github/assets/sponsors/sponsor-elastic.png
-  [Hyperledger]: https://raw.githubusercontent.com/squidfunk/mkdocs-material/master/.github/assets/sponsors/sponsor-hyperledger.png
   [IP Fabric]: https://raw.githubusercontent.com/squidfunk/mkdocs-material/master/.github/assets/sponsors/sponsor-ip-fabric.png
   [Apex.AI]: https://raw.githubusercontent.com/squidfunk/mkdocs-material/master/.github/assets/sponsors/sponsor-apex-ai.png
   [Jitterbit]: https://raw.githubusercontent.com/squidfunk/mkdocs-material/master/.github/assets/sponsors/sponsor-jitterbit.png
   [Sparkfun]: https://raw.githubusercontent.com/squidfunk/mkdocs-material/master/.github/assets/sponsors/sponsor-sparkfun.png
-  [Automation Technology]: https://raw.githubusercontent.com/squidfunk/mkdocs-material/master/.github/assets/sponsors/sponsor-automation-technology.png
   [Eccenca]: https://raw.githubusercontent.com/squidfunk/mkdocs-material/master/.github/assets/sponsors/sponsor-eccenca.png
   [Neptune]: https://raw.githubusercontent.com/squidfunk/mkdocs-material/master/.github/assets/sponsors/sponsor-neptune-ai.png
   [Cash App]: https://raw.githubusercontent.com/squidfunk/mkdocs-material/master/.github/assets/sponsors/sponsor-cashapp.png
   [RackN]: https://raw.githubusercontent.com/squidfunk/mkdocs-material/master/.github/assets/sponsors/sponsor-rackn.png
   [CivicActions]: https://raw.githubusercontent.com/squidfunk/mkdocs-material/master/.github/assets/sponsors/sponsor-civic-actions.png
   [bitcrowd]: https://raw.githubusercontent.com/squidfunk/mkdocs-material/master/.github/assets/sponsors/sponsor-bitcrowd.png
+  [GetScreen.me]: https://raw.githubusercontent.com/squidfunk/mkdocs-material/master/.github/assets/sponsors/sponsor-getscreenme.png
+  [BotCity]: https://raw.githubusercontent.com/squidfunk/mkdocs-material/master/.github/assets/sponsors/sponsor-botcity.png
+  [Springer Nature Technology]: https://raw.githubusercontent.com/squidfunk/mkdocs-material/master/.github/assets/sponsors/sponsor-sn-technology.png
+  [Kolena]: https://raw.githubusercontent.com/squidfunk/mkdocs-material/master/.github/assets/sponsors/sponsor-kolena.png
+  [Evergiving]: https://raw.githubusercontent.com/squidfunk/mkdocs-material/master/.github/assets/sponsors/sponsor-evergiving.png
+  [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 />
 
@@ -251,22 +264,6 @@ features prefixed with a checkmark symbol, denoting whether a feature is
 :octicons-check-circle-fill-24:{ style="color: var(--md-default-fg-color--lightest)" } planned, but not yet implemented. When the funding goal is hit, the features
 are released for general availability.
 
-#### $ 12,000 – Piri Piri
-
-- [x] [Blog plugin]
-- [x] [Chinese search support]
-- [x] [Annotations]
-- [x] [Navigation icons]
-- [x] [Navigation pruning]
-- [x] [Navigation status]
-
-  [Blog plugin]: ../setup/setting-up-a-blog.md
-  [Chinese search support]: ../blog/posts/chinese-search-support.md
-  [Annotations]: ../reference/annotations.md
-  [Navigation icons]: ../reference/index.md#setting-the-page-icon
-  [Navigation pruning]: ../setup/setting-up-navigation.md#navigation-pruning
-  [Navigation status]: ../reference/index.md#setting-the-page-status
-
 #### $ 14,000 – Goat's Horn
 
 - [x] [Privacy plugin]
@@ -292,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
@@ -307,21 +304,27 @@ are released for general availability.
 - [x] [Navigation path] (Breadcrumbs)
 - [x] [Privacy plugin: optimization support]
 - [x] [Privacy plugin: external links]
-- [ ] Privacy plugin: external link validation
+- [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.external_links
+  [Privacy plugin: external links]: ../setup/ensuring-data-privacy.md#+privacy.links
-  [Privacy plugin: optimization support]: ../setup/ensuring-data-privacy.md#+privacy.external_assets_include
+  [Privacy plugin: optimization support]: ../setup/ensuring-data-privacy.md#+privacy.assets_include
   [Navigation path]: ../setup/setting-up-navigation.md#navigation-path
-  [Instant previews]: https://twitter.com/squidfunk/status/1466794654213492743
+  [Instant prefetching]: ../setup/setting-up-navigation.md#instant-prefetching
 
 #### $ 24,000 – Blockpaprika
 
+- [x] [Projects plugin]
+- [x] [Social plugin: custom layouts]
+- [x] [Social plugin: background images]
 - [x] [Code range selection]
 - [x] [Code annotations: custom selectors]
 - [ ] Code line wrap button
 
+  [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
   [Code annotations: custom selectors]: ../reference/code-blocks.md#custom-selectors
 
@@ -331,6 +334,22 @@ This section lists all funding goals that were previously completed, which means
 that those features were part of Insiders, but are now generally available and
 can be used by all users.
 
+#### $ 12,000 – Piri Piri
+
+- [x] [Blog plugin]
+- [x] [Chinese search support]
+- [x] [Annotations]
+- [x] [Navigation icons]
+- [x] [Navigation pruning]
+- [x] [Navigation status]
+
+  [Blog plugin]: ../setup/setting-up-a-blog.md
+  [Chinese search support]: ../blog/posts/chinese-search-support.md
+  [Annotations]: ../reference/annotations.md
+  [Navigation icons]: ../reference/index.md#setting-the-page-icon
+  [Navigation pruning]: ../setup/setting-up-navigation.md#navigation-pruning
+  [Navigation status]: ../reference/index.md#setting-the-page-status
+
 #### $ 10,000 – Carolina Reaper
 
 - [x] [Brand new search plugin]
@@ -472,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,15 +34,18 @@ 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
-          - uses: actions/cache@v2
+          - run: echo "cache_id=$(date --utc '+%V')" >> $GITHUB_ENV # (3)!
+          - uses: actions/cache@v3
             with:
-              key: ${{ github.ref }}
+              key: mkdocs-material-${{ env.cache_id }}
               path: .cache
-          - run: pip install mkdocs-material # (3)!
+              restore-keys: |
+                mkdocs-material-
+          - run: pip install mkdocs-material # (4)!
           - run: mkdocs gh-deploy --force
     ```
 
@@ -51,7 +54,16 @@ contents:
     2.  At some point, GitHub renamed `master` to `main`. If your default branch
         is named `master`, you can safely remove `main`, vice versa.
 
-    3.  This is the place to install further [MkDocs plugins] or Markdown
+    3.  Store the `cache_id` environmental variable to access it later during cache
+        `key` creation. The name is case-sensitive, so be sure to align it with `${{ env.cache_id }}`.
+
+        - The `--utc` option makes sure that each workflow runner uses the same time zone.
+        - The `%V` format assures a cache update once a week.
+        - You can change the format to `%F` to have daily cache updates.
+
+        You can read the [manual page] to learn more about the formatting options of the `date` command.
+
+    4.  This is the place to install further [MkDocs plugins] or Markdown
         extensions with `pip` to be used during the build:
 
         ``` sh
@@ -77,14 +89,17 @@ 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
-          - uses: actions/cache@v2
+          - run: echo "cache_id=$(date --utc '+%V')" >> $GITHUB_ENV
+          - uses: actions/cache@v3
             with:
-              key: ${{ github.ref }}
+              key: mkdocs-material-${{ env.cache_id }}
               path: .cache
+              restore-keys: |
+                mkdocs-material-
           - run: apt-get install pngquant # (1)!
           - run: pip install git+https://${GH_TOKEN}@github.com/squidfunk/mkdocs-material-insiders.git
           - run: mkdocs gh-deploy --force
@@ -113,9 +128,10 @@ 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
 
 ### with MkDocs
 

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,13 +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-heart-fill-24:{ .mdx-heart } Sponsors only][Insiders]{ .mdx-insiders } ·
+<!-- md:version 9.2.0 -->
-[:octicons-tag-24: insiders-4.6.0][Insiders] ·
+<!-- md:flag experimental -->
-:octicons-beaker-24: 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
@@ -65,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.
 
-  [Insiders]: ../insiders/index.md
-
 #### 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
@@ -83,11 +81,11 @@ theme:
     ```
     ````
 
-### Code selection button :material-alert-decagram:{ .mdx-pulse title="Added on February 19, 2023" }
+### 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 :material-alert-decagram:{ .mdx-pulse title="Added on February 19, 2023" }
+#### 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>"`
@@ -358,27 +352,53 @@ argument placed right after the language shortcode. Note that line counts start
 at `1`, regardless of the starting line number specified as part of
 [`linenums`][Adding line numbers]:
 
-```` markdown title="Code block with highlighted lines"
+=== "Lines"
-``` py hl_lines="2 3"
+
-def bubble_sort(items):
+    ```` markdown title="Code block with highlighted lines"
+    ``` py hl_lines="2 3"
+    def bubble_sort(items):
         for i in range(len(items)):
             for j in range(len(items) - 1 - i):
                 if items[j] > items[j + 1]:
                     items[j], items[j + 1] = items[j + 1], items[j]
-```
+    ```
-````
+    ````
 
-<div class="result" markdown>
+    <div class="result" markdown>
 
-``` py linenums="1" hl_lines="2 3"
+    ``` py linenums="1" hl_lines="2 3"
-def bubble_sort(items):
+    def bubble_sort(items):
         for i in range(len(items)):
             for j in range(len(items) - 1 - i):
                 if items[j] > items[j + 1]:
                     items[j], items[j + 1] = items[j + 1], items[j]
-```
+    ```
 
-</div>
+    </div>
+
+=== "Line ranges"
+
+    ```` markdown title="Code block with highlighted line range"
+    ``` py hl_lines="3-5"
+    def bubble_sort(items):
+        for i in range(len(items)):
+            for j in range(len(items) - 1 - i):
+                if items[j] > items[j + 1]:
+                    items[j], items[j + 1] = items[j + 1], items[j]
+    ```
+    ````
+
+    <div class="result" markdown>
+
+    ``` py linenums="1" hl_lines="3-5"
+    def bubble_sort(items):
+        for i in range(len(items)):
+            for j in range(len(items) - 1 - i):
+                if items[j] > items[j + 1]:
+                    items[j], items[j + 1] = items[j + 1], items[j]
+    ```
+
+    </div>
 
   [Adding line numbers]: #adding-line-numbers
 
@@ -485,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
 
@@ -523,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 poenpyxl
-        ```
-
-        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