Improved path checks by making them more explicit

Bump authors plugin in Dockerfile

.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

@@ -1,4 +1,4 @@
-# Copyright (c) 2016-2022 Martin Donath <martin.donath@squidfunk.com>
+# Copyright (c) 2016-2023 Martin Donath <martin.donath@squidfunk.com>
 
 # Permission is hereby granted, free of charge, to any person obtaining a copy
 # of this software and associated documentation files (the "Software"), to
@@ -18,8 +18,10 @@
 # FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS
 # IN THE SOFTWARE.
 
+.cache
 .git
 .github
 docs
+material/.overrides
 node_modules
 src

.editorconfig

@@ -1,4 +1,4 @@
-# Copyright (c) 2016-2022 Martin Donath <martin.donath@squidfunk.com>
+# Copyright (c) 2016-2023 Martin Donath <martin.donath@squidfunk.com>
 
 # Permission is hereby granted, free of charge, to any person obtaining a copy
 # of this software and associated documentation files (the "Software"), to

.eslintignore

@@ -1,4 +1,4 @@
-# Copyright (c) 2016-2022 Martin Donath <martin.donath@squidfunk.com>
+# Copyright (c) 2016-2023 Martin Donath <martin.donath@squidfunk.com>
 
 # Permission is hereby granted, free of charge, to any person obtaining a copy
 # of this software and associated documentation files (the "Software"), to

.eslintrc

@@ -214,7 +214,7 @@
     ],
     "@typescript-eslint/no-empty-interface": "off",
     "@typescript-eslint/no-extraneous-class": "error",
-    "@typescript-eslint/no-misused-promises": "error",
+    "@typescript-eslint/no-misused-promises": "off",
     "@typescript-eslint/no-non-null-assertion": "off",
     "@typescript-eslint/no-parameter-properties": "off",
     "@typescript-eslint/no-floating-promises": "error",
@@ -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/FUNDING.yml

@@ -1,4 +1,4 @@
-# Copyright (c) 2016-2022 Martin Donath <martin.donath@squidfunk.com>
+# Copyright (c) 2016-2023 Martin Donath <martin.donath@squidfunk.com>
 
 # Permission is hereby granted, free of charge, to any person obtaining a copy
 # of this software and associated documentation files (the "Software"), to

.github/assets/logo.svg

@@ -42,7 +42,6 @@
             system-ui, -apple-system, 'Segoe UI', Roboto, Helvetica, Arial,
             sans-serif, 'Apple Color Emoji', 'Segoe UI Emoji';
           letter-spacing: -1px;
-          background: #FFFFFF;
           border-radius: 2px;
         }
 
@@ -62,14 +61,14 @@
           position: absolute;
           width: 100%;
           height: 100%;
-          background-image: linear-gradient(#1A1A1A, #5E5E5E);
+          background-image: linear-gradient(#22272e, #526cfe);
           border-radius: 100%;
           animation: backdrop infinite both 10s 1s cubic-bezier(0.7, 0, 0.3, 1);
         }
 
         h1 {
           margin: 24px 0 4px;
-          color: #1A1A1A;
+          color: #526cfe;
           font-weight: bold;
           font-size: 24px;
         }

.github/workflows/build.yml

@@ -1,4 +1,4 @@
-# Copyright (c) 2016-2022 Martin Donath <martin.donath@squidfunk.com>
+# Copyright (c) 2016-2023 Martin Donath <martin.donath@squidfunk.com>
 
 # Permission is hereby granted, free of charge, to any person obtaining a copy
 # of this software and associated documentation files (the "Software"), to
@@ -20,20 +20,25 @@
 
 name: build
 on:
-  - push
-  - pull_request
+  push:
+    branches:
+      - master
+  pull_request:
+  release:
+    types:
+      - published
 
 env:
-  NODE_VERSION: 14.x
+  NODE_VERSION: 18.x
+  PYTHON_VERSION: 3.x
 
 permissions:
   contents: read
 
 jobs:
-  build:
-    name: Build project
-    if: github.event.repository.fork == false
+  npm:
     runs-on: ubuntu-latest
+    if: github.event.repository.fork == false
     steps:
 
       - name: Checkout repository
@@ -48,8 +53,8 @@ jobs:
         uses: actions/cache@v3
         id: cache
         with:
-          path: node_modules
           key: ${{ runner.os }}-${{ hashFiles('**/package-lock.json') }}
+          path: node_modules
 
       - name: Set up Node.js dependencies
         if: steps.cache.outputs.cache-hit != 'true'
@@ -62,3 +67,79 @@ jobs:
         run: |
           npm run build
           git diff --name-only
+
+  docker:
+    runs-on: ubuntu-latest
+    if: github.event.repository.fork == true
+    steps:
+
+      - name: Checkout repository
+        uses: actions/checkout@v3
+
+      # - name: Set up QEMU
+      #   uses: docker/setup-qemu-action@v2
+
+      - name: Set up Docker Buildx
+        uses: docker/setup-buildx-action@v2
+
+      - name: Login to GitHub Container Registry
+        if: github.event_name == 'release'
+        uses: docker/login-action@v2
+        with:
+          registry: ghcr.io
+          username: ${{ github.repository_owner }}
+          password: ${{ secrets.GHCR_TOKEN }}
+
+      - name: Generate Docker tags and labels
+        id: meta
+        uses: docker/metadata-action@v4
+        with:
+          images: ghcr.io/${{ github.event.repository.full_name }}
+          tags: |
+            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
+        with:
+          context: .
+          load: true
+          tags: ${{ steps.meta.outputs.tags }}
+          labels: ${{ steps.meta.outputs.labels }}
+
+      - name: Check Docker image
+        working-directory: /tmp
+        env:
+          REPO_FULL_NAME: '${{ github.event.repository.full_name }}'
+        run: |
+          docker run --rm -i --user $(id -u):$(id -g) -e GH_TOKEN=${GH_TOKEN} -v ${PWD}:/docs ghcr.io/${REPO_FULL_NAME,,}:${{ steps.meta.outputs.version }} new .
+          docker run --rm -i --user $(id -u):$(id -g) -e GH_TOKEN=${GH_TOKEN} -v ${PWD}:/docs ghcr.io/${REPO_FULL_NAME,,}:${{ steps.meta.outputs.version }} build
+
+      - name: Set platforms
+        if: github.event_name == 'release'
+        run: |
+          echo "PLATFORMS=linux/amd64" >> $GITHUB_ENV
+        # echo "PLATFORMS=linux/amd64,linux/arm64,linux/arm/v7" >> $GITHUB_ENV
+
+      - name: Publish Docker image
+        uses: docker/build-push-action@v4
+        with:
+          context: .
+          platforms: ${{ env.PLATFORMS }}
+          push: ${{ github.event_name == 'release' }}
+          tags: ${{ steps.meta.outputs.tags }}
+          labels: ${{ steps.meta.outputs.labels }}
+
+      # - name: Check manifest
+      #   if: github.event_name == 'release'
+      #   run: |
+      #     docker buildx imagetools inspect ghcr.io/${{ github.event.repository.full_name }}:${{ steps.meta.outputs.version }}
+
+      # - name: Inspect image
+      #   if: github.event_name == 'release'
+      #   run: |
+      #     docker pull ghcr.io/${{ github.event.repository.full_name }}:${{ steps.meta.outputs.version }}
+      #     docker image inspect ghcr.io/${{ github.event.repository.full_name }}:${{ steps.meta.outputs.version }}

.github/workflows/publish.yml

@@ -1,69 +0,0 @@
-# Copyright (c) 2016-2022 Martin Donath <martin.donath@squidfunk.com>
-
-# Permission is hereby granted, free of charge, to any person obtaining a copy
-# of this software and associated documentation files (the "Software"), to
-# deal in the Software without restriction, including without limitation the
-# rights to use, copy, modify, merge, publish, distribute, sublicense, and/or
-# sell copies of the Software, and to permit persons to whom the Software is
-# furnished to do so, subject to the following conditions:
-
-# The above copyright notice and this permission notice shall be included in
-# all copies or substantial portions of the Software.
-
-# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-# IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-# FITNESS FOR A PARTICULAR PURPOSE AND NON-INFRINGEMENT. IN NO EVENT SHALL THE
-# AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-# LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
-# FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS
-# IN THE SOFTWARE.
-
-name: publish
-
-on:
-  create:
-    tags:
-      - ".+"
-
-env:
-  PYTHON_VERSION: 3.x
-
-permissions:
-  contents: read
-
-jobs:
-  publish:
-    name: Build and push Docker image
-    if: github.event.repository.fork == true
-    runs-on: ubuntu-latest
-    steps:
-
-      - name: Checkout repository
-        uses: actions/checkout@v3
-
-      - name: Lowercase repository name
-        run: echo "REPOSITORY_NAME=${GITHUB_REPOSITORY,,}" >> $GITHUB_ENV
-
-      - name: Login to GitHub Container Registry
-        uses: docker/login-action@v2
-        with:
-          registry: ghcr.io
-          username: ${{ github.repository_owner }}
-          password: ${{ secrets.GHCR_TOKEN }}
-
-      - name: Build Docker image
-        uses: docker/build-push-action@v3
-        with:
-          context: .
-          # platforms: linux/amd64,linux/arm64
-          tags: |
-            ghcr.io/${{ env.REPOSITORY_NAME }}:latest
-            ghcr.io/${{ env.REPOSITORY_NAME }}:${{ github.event.ref }}
-
-      - name: Check Docker image
-        run:
-          docker run --rm -i -v ${PWD}:/docs ghcr.io/${{ env.REPOSITORY_NAME }} build
-
-      - name: Publish Docker image
-        run: |
-          docker push --all-tags ghcr.io/${{ env.REPOSITORY_NAME }}

.gitignore

@@ -1,4 +1,4 @@
-# Copyright (c) 2016-2022 Martin Donath <martin.donath@squidfunk.com>
+# Copyright (c) 2016-2023 Martin Donath <martin.donath@squidfunk.com>
 
 # Permission is hereby granted, free of charge, to any person obtaining a copy
 # of this software and associated documentation files (the "Software"), to
@@ -23,19 +23,18 @@
 # -----------------------------------------------------------------------------
 
 # Dependencies
-/node_modules
-/__pycache__
-/venv
-/.venv
+node_modules
+__pycache__
+venv
+.venv
 
 # Build files
-/build
-/MANIFEST
-/site
+build
+site
 
 # Distribution files
-/dist
-/mkdocs_material.egg-info
+dist
+mkdocs_material.egg-info
 
 # Caches and logs
 *.cpuprofile
@@ -45,6 +44,10 @@
 .eslintcache
 __pycache__
 
+# Examples
+example
+example.zip
+
 # -----------------------------------------------------------------------------
 # General
 # -----------------------------------------------------------------------------

.stylelintignore

@@ -1,4 +1,4 @@
-# Copyright (c) 2016-2022 Martin Donath <martin.donath@squidfunk.com>
+# Copyright (c) 2016-2023 Martin Donath <martin.donath@squidfunk.com>
 
 # Permission is hereby granted, free of charge, to any person obtaining a copy
 # of this software and associated documentation files (the "Software"), to

.stylelintrc

@@ -1,6 +1,6 @@
 {
   "extends": [
-    "stylelint-config-rational-order",
+    "stylelint-config-recess-order",
     "stylelint-config-recommended",
     "stylelint-config-standard-scss"
   ],
@@ -9,6 +9,7 @@
   ],
   "rules": {
     "alpha-value-notation": "number",
+    "annotation-no-unknown": null,
     "at-rule-empty-line-before": [
       "always",
       {
@@ -72,6 +73,7 @@
     ],
     "linebreaks": "unix",
     "media-feature-name-no-unknown": null,
+    "media-feature-range-notation": null,
     "no-descending-specificity": null,
     "no-empty-first-line": true,
     "no-unknown-animations": true,

.vscode/launch.json

@@ -3,14 +3,14 @@
   "configurations": [
     {
       "name": "Application",
-      "type": "pwa-chrome",
+      "type": "chrome",
       "request": "launch",
       "runtimeArgs": [
         "--disable-features=Translate",
         "--incognito"
       ],
       "url": "http://localhost:8000/mkdocs-material/",
-      "webRoot": ".",
+      "webRoot": "${workspaceFolder}",
       "smartStep": true
     }
   ]

.vscode/settings.json

@@ -16,6 +16,7 @@
     "!ENV sequence",
     "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.slugs.uslugify",
     "tag:yaml.org,2002:python/name:pymdownx.superfences.fence_code_format"
   ]
 }

CHANGELOG

@@ -1,8 +1,793 @@
+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
+  * Updated Mermaid.js to version 9.4.3
+  * Fixed #5290: Footer previous/next labels cut-off for short page titles
+
+mkdocs-material-9.1.4+insiders-4.32.4 (2023-03-24)
+
+  * Fixed #5241: Built-in typeset plugin jams navigation for anchors in headings
+
+mkdocs-material-9.1.4 (2023-03-24)
+
+  * Fixed #5239: Instant loading breaks anchors in details (9.1.1 regression)
+  * Fixed #5211: Anchor following not working for Chinese (9.1.2 regression)
+
+mkdocs-material-9.1.3 (2023-03-14)
+
+  * Added Kurdish (Soranî) translations
+  * Updated Norwegian (Bokmål), Portuguese and Romanian translations
+  * Improved compatibility with mkdocs-jupyter plugin
+  * Fixed #5198: Built-in search plugin not filtering script and style tags
+  * Fixed #5176: Back-to-top + instant loading not working (9.1.1 regression)
+
+mkdocs-material-9.1.2+insiders-4.32.3 (2023-03-09)
+
+  * Fixed Docker image release workflow (9.1.0 regression)
+  * Fixed #5159: Missing underline for abbreviations (9.1.0 regression)
+
+mkdocs-material-9.1.2 (2023-03-09)
+
+  * Updated Icelandic, Korean and Swedish translations
+  * Fixed #5168: Mermaid text boxes overflow (9.0.13 regression)
+  * Fixed #5155: Table of contents not highlighting percent-encoded URLs
+
+mkdocs-material-9.1.1 (2023-03-05)
+
+  * Updated Czech and Thai translations
+  * Improved instant loading (scroll restoration, slow connections)
+  * Fixed #5023: Instant loading not allowing to go back to initial page
+  * Fixed #3797: Instant loading does not work with section anchors in Safari
+
+mkdocs-material-9.1.0+insiders-4.32.2 (2023-03-02)
+
+  * Fixed #5127: Privacy plugin not handling large number of occurrences
+  * Fixed #5126: Privacy plugin breaks when replacing specific emojis
+
+mkdocs-material-9.1.0 (2023-03-02)
+
+  * Docker image now available for amd64, arm64 and arm/v7
+  * Updated Chinese (Taiwanese) translations
+  * Generalized tag identifier implementation
+  * Fixed flickering of header shadow on load
+  * Fixed occasional flickering of announcement bar
+
+mkdocs-material-9.0.15 (2023-02-26)
+
+  * Updated Chinese (Traditional) translations
+  * Updated Hebrew translations
+
+mkdocs-material-9.0.14+insiders-4.32.1 (2023-02-23)
+
+  * Fixed code block spans interfering with copying
+  * Fixed #5077: Privacy plugin breaks image alt text encoding
+  * Fixed #5079: Privacy plugin removing rel=me on external links
+
+mkdocs-material-9.0.14 (2023-02-23)
+
+  * Fixed #5072: Rendering bug on navigation expand button in Firefox
+
+mkdocs-material-9.0.13+insiders-4.32.0 (2023-02-19)
+
+  * Added support for custom selectors for code annotations
+  * Added support for code line range selection for better sharing
+
+mkdocs-material-9.0.13+insiders-4.31.0 (2023-02-18)
+
+  * Added support for table of contents on blog index and archive pages
+  * Fixed #4512: Allow custom search field boosts (experimental)
+
+mkdocs-material-9.0.13 (2023-02-18)
+
+  * Updated Uzbek translations
+  * Switched back to pre-9.0.0 headline detection in content partial
+  * Fixed #5062: Version warning not readable when using slate scheme
+  * Fixed #5061: Improved discernibility of table row hover color
+  * Fixed #5034: Sequence actors in Mermaid diagrams not color-abiding
+  * Fixed #4919: Allow to hide version warning in multiple versions
+
+mkdocs-material-9.0.12+insiders-4.30.2 (2023-02-13)
+
+  * Fixed privacy plugin excludes not working (4.30.0 regression)
+
+mkdocs-material-9.0.12+insiders-4.30.1 (2023-02-12)
+
+  * Fixed privacy plugin not handling static templates e.g. 404.html
+
+mkdocs-material-9.0.12 (2023-02-09)
+
+  * Updated Catalan translations
+  * Fixed #4975: Mermaid entity relationship rendering diagrams bug
+  * Fixed #4924: Header title not reset when using instant loading
+
+mkdocs-material-9.0.11+insiders-4.30.0 (2023-02-06)
+
+  * Rewrite of privacy plugin for concurrency, now twice as fast
+  * Added support for explicit inclusion for privacy plugin
+  * Added optimization support for privacy plugin (+ optimize plugin)
+
+mkdocs-material-9.0.11 (2023-02-03)
+
+  * Added Mastodon verification for social links (rel=me)
+  * Updated Italian translations
+
+mkdocs-material-9.0.10 (2023-02-02)
+
+  * Updated Arabic translations
+  * Updated Korean translations
+  * Updated Hungarian translations
+  * Updated Russian translations
+  * Fixed #4977: Improved accessibility for content tabs
+  * Fixed #4960: Sometimes anchor following doesn't bring last item into view
+
+mkdocs-material-9.0.9 (2023-01-30)
+
+  * Updated Bulgarian translations
+  * Updated Chinese (Simplified) translations
+  * Updated Dutch translations
+  * Updated Hindi translations
+  * Updated Japanese translations
+  * Updated Polish translations
+
+mkdocs-material-9.0.8 (2023-01-29)
+
+  * Updated Croatian translations
+  * Updated French translations
+  * Updated Hungarian translations
+  * Updated Portuguese (Brasilian) translations
+  * Updated Spanish translations
+  * Updated Ukrainian translations
+  * Updated Urdu translations
+  * Updated Vietnamese translations
+
+mkdocs-material-9.0.7 (2023-01-28)
+
+  * Improved accessibility of sidebar navigation
+  * 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
+  * Fixed #4884: Search query terms can't be separated by colons
+
+mkdocs-material-9.0.6+insiders-4.29.0 (2023-01-21)
+
+  * Added built-in optimize plugin for automatically compressing images
+  * Switched reporting in built-in privacy plugin to info level
+
+mkdocs-material-9.0.6 (2023-01-19)
+
+  * Fixed #4883: Automatically disable info plugin when serving
+  * Fixed #4885: Search plugin crashes in some exotic cases (9.0.3 regression)
+
+mkdocs-material-9.0.5+insiders-4.28.1 (2023-01-17)
+
+  * Fixed built-in info plugin erroring for Insiders on version check
+  * Fixed #4865: Navigation paths render bug when there's no top-level section
+  * Fixed #4875: Added support for hiding navigation paths
+  * Improved navigation path to not render for a single item
+
+mkdocs-material-9.0.5+insiders-4.28.0 (2023-01-14)
+
+  * Added support for navigation path (breadcrumbs)
+
+mkdocs-material-9.0.5 (2023-01-14)
+
+  * Fixed #4842: Improved accessibility of search result list
+
+mkdocs-material-9.0.4 (2023-01-12)
+
+  * Fixed #4823: Improved contrast ratio in footer (9.0.2 regression)
+  * Fixed #4832: Set navigation items back to black (9.0.3 regression)
+  * Fixed #4843: Emojis broken due to maxcdn.com shutting down
+  * Upgraded Python Markdown Extensions to 9.9.1
+
+mkdocs-material-9.0.3+insiders-4.27.1 (2023-01-08)
+
+  * Fixed rendering of succeeding navigation items in typeset plugin
+  * Fixed #4795: Built-in typeset plugin changes MkDocs' title precedence
+  * Fixed #4724: Blog plugin not rendering integrate table of contents
+
+mkdocs-material-9.0.3 (2023-01-08)
+
+  * Improved discernibility of section index pages in navigation
+  * Improved collapsing of adjacent whitespace in search plugin
+  * Updated Indonesian translations
+  * Fixed view source of this page button when edit URL points to blob
+  * Fixed #4829: Search overlay does not close for active anchor result
+  * Fixed #4824: Search plugin crashes for h1-6 contained in other elements
+  * Fixed #4804: Nested navigation items not expandable with keyboard
+  * Fixed #4689: anchor tracking not working for anchors in tables
+  * Upgraded to Mermaid 9.3.0
+
+mkdocs-material-9.0.2 (2023-01-04)
+
+  * Fixed #4823: Improved contrast ratio in footer to meet WCAG guidelines
+  * Fixed #4819: Social plugin crashes when card generation is disabled
+  * Fixed #4817: Search plugin crashes on numeric page titles in nav
+
+mkdocs-material-9.0.1 (2023-01-03)
+
+  * Removed pipdeptree dependency for built-in info plugin
+  * Fixed appearance of linked tags when hovered (9.0.0 regression)
+  * Fixed #4810: Abbreviations run out of screen on touch devices
+  * Fixed #4813: View source and edit button links are the same
+
+mkdocs-material-9.0.0 (2023-01-02)
+
+  Additions and improvements
+
+  * Added support for rich search previews
+  * Added support for tokenizer lookahead
+  * Added support for better search highlighting
+  * Added support for excluding content from search
+  * Added support for configurable search pipeline
+  * Added support for offline search via offline plugin
+  * Added support for multiple instances of built-in tags plugin
+  * Added support for removing copy-to-clipboard button
+  * Added support for removing footer navigation
+  * Added support for button to view the source of a page
+  * Improved readability of query string for search sharing
+  * Improved stability of search plugin when using --dirtyreload
+  * Improved search result group button, now sticky and stable
+  * Updated Norwegian translations
+  * Updated MkDocs to 1.4.2
+
+  Removals
+
+  * Removed deprecated alternative admonition qualifiers
+  * Removed :is() selectors (in output) for easier overriding
+  * Removed .title suffix on translations
+  * Removed legacy method for providing page title in feedback URL
+  * Removed support for indexing only titles in search
+  * Removed support for custom search transforms
+  * Removed support for custom search workers
+  * Removed temporary snow feature (easter egg)
+
+  Fixes
+
+  * Fixed Norwegian and Korean language code
+  * Fixed detection of composition events in search interface
+  * Fixed search plugin not using title set via front matter
+  * Fixed search highlighting of tags
+  * Fixed search sharing URL using post transformed string
+  * Fixed theme-color meta tag getting out-of-sync with palette toggle
+  * Fixed prev/next page keyboard navigation when footer is not present
+  * Fixed overflowing navigation tabs not being scrollable
+  * Fixed inclusion of code block line numbers from search
+
+mkdocs-material-8.5.11+insiders-4.27.0 (2022-12-20)
+
+  * Added built-in typeset plugin to preserve formatting in sidebars
+  * Added URL and table of contents support for blog categories
+
+mkdocs-material-8.5.11 (2022-11-30)
+
+  * Let it snow, see https://twitter.com/squidfunk/status/1597939243090788352
+
+mkdocs-material-8.5.10+insiders-4.26.6 (2022-11-28)
+
+  * Fixed #4683: Tags plugin crashes when a tag is empty
+
+mkdocs-material-8.5.10+insiders-4.26.5 (2022-11-27)
+
+  * Fixed #4632: Post excerpt title link doesn't point to top of the page
+
+mkdocs-material-8.5.10+insiders-4.26.4 (2022-11-27)
+
+  * Fixed redundant file extension when using privacy plugin
+
+mkdocs-material-8.5.10+insiders-4.26.3 (2022-11-15)
+
+  * Fixed #4637: Attachments w/o titles in related links error in blog plugin
+  * Fixed #4631: Remote favicons not downloaded and inlined by privacy plugin
+
+mkdocs-material-8.5.10 (2022-11-11)
+
+  * Adjusted CSS to better allow for custom primary and accent colors
+  * Fixed #4620: Primary color is not applied (8.5.9 regression)
+
+mkdocs-material-8.5.9 (2022-11-08)
+
+  * Fixed #4600: Illegible link colors for black and white primary colors
+  * Fixed #4594: Need to set schema to change link color
+
+mkdocs-material-8.5.8+insiders-4.26.2 (2022-11-03)
+
+  * Updated MkDocs to 1.4.2
+  * Added support for tag compare functions when sorting on index pages
+  * Fixed footnotes being rendered in post excerpts without separators
+  * Fixed error in blog plugin when toc extension is not enabled
+  * Fixed issues with invalid asset paths and linked post titles
+  * Fixed #4572: Privacy plugin fails when symlinks cannot be created
+  * Fixed #4545: Blog plugin doesn't automatically link headline to post
+  * Fixed #4542: Blog plugin doesn't allow for multiple instances
+  * Fixed #4532: Blog plugin doesn't allow for mixed use of date and datetime
+
+mkdocs-material-8.5.8 (2022-11-03)
+
+  * Added support for always showing settings in cookie consent
+  * Fixed #4571: Buttons invisible if primary color is white or black
+  * Fixed #4517: Illegible note in sequence diagram when using slate scheme
+
+mkdocs-material-8.5.7+insiders-4.26.1 (2022-10-22)
+
+  * Improved reporting of configuration errors in tags plugin
+  * Fixed #4515: Privacy plugin fails when site URL is not defined
+  * Fixed #4514: Privacy plugin doesn't fetch Google fonts (4.26.0 regression)
+
+mkdocs-material-8.5.7 (2022-10-22)
+
+  * Deprecated additional admonition qualifiers to reduce size of CSS
+  * Fixed #4511: Search boost does not apply to sections
+
+mkdocs-material-8.5.6+insiders-4.26.0 (2022-10-18)
+
+  * Refactored privacy plugin to prepare for new features
+  * Added support for rel=noopener links in privacy plugin
+  * Resolve encoding issues with blog and privacy plugin
+
+mkdocs-material-8.5.6+insiders-4.25.5 (2022-10-16)
+
+  * Updated MkDocs to 1.4.1
+  * Added namespace prefix to built-in plugins
+  * Updated content and header partial
+
+mkdocs-material-8.5.6+insiders-4.25.4 (2022-10-09)
+
+  * Fixed other path issues for standalone blogs (4.24.2 regression)
+
+mkdocs-material-8.5.6+insiders-4.25.3 (2022-10-09)
+
+  * Fixed #4457: Posts not collected for standalone blog (4.24.2 regression)
+
+mkdocs-material-8.5.6+insiders-4.25.2 (2022-10-04)
+
+  * Fixed #4452: Blog and tags plugin crash when specifying slugify function
+
+mkdocs-material-8.5.6+insiders-4.25.1 (2022-10-03)
+
+  * Updated mkdocs-rss-plugin in Dockerfile to fix MkDocs compat errors
+
+mkdocs-material-8.5.6+insiders-4.25.0 (2022-10-02)
+
+  * Added support for navigation subtitles
+  * Added support for defining an allow list for built-in tags plugin
+  * Added support for custom slugify functions for built-in tags plugin
+  * Improved stability of search plugin when using --dirtyreload
+
+mkdocs-material-8.5.6 (2022-10-02)
+
+  * Modernized appearance of admonitions (with fallback, see docs)
+  * Improved appearance of inline code blocks in admonition titles
+
+mkdocs-material-8.5.5+insiders-4.24.2 (2022-10-01)
+
+  * Updated MkDocs to 1.4
+  * Fixed compatibility issues with MkDocs 1.4
+  * Fixed incorrectly generated paths in privacy plugin
+  * Fixed blog index page not showing navigation when using meta plugin
+
+mkdocs-material-8.5.5 (2022-10-01)
+
+  * Updated MkDocs to 1.4
+  * Fixed compatibility issues with MkDocs 1.4
+  * Fixed #4430: build error when enabling consent without repository URL
+
+mkdocs-material-8.5.4+insiders-4.24.1 (2022-09-30)
+
+  * Fixed #4430: build error when enabling consent without repository URL
+
+mkdocs-material-8.5.4 (2022-09-30)
+
+  * Fixed expand icons shift on sidebar overflow (using scrollbar-gutter)
+  * Fixed #4429: Text in sequence diagrams overflows in Firefox
+
+mkdocs-material-8.5.3+insiders-4.24.0 (2022-09-27)
+
+  * Added support for custom content on index pages (blog)
+  * Added support for keeping content on paginated index pages (blog)
+  * Added support for limiting categories in post excerpts (blog)
+  * Added support for simple override of templates via front matter (blog)
+  * Added icon in navigation for pages with encrypted content
+  * Fixed #4396: Front matter of index pages not inherited by pagination (blog)
+  * Improved performance by building post excerpts once (blog)
+
+mkdocs-material-8.5.3+insiders-4.23.6 (2022-09-22)
+
+  * Fixed #4389: Blog posts in first week of year in wrong archive
+  * Fixed (= switched) footer previous and next links for blog posts
+
+mkdocs-material-8.5.3 (2022-09-20)
+
+  * Fixed build error when enabling cookie consent without analytics
+  * Fixed #4381: Code blocks render ligatures for some fonts
+
+mkdocs-material-8.5.2+insiders-4.23.5 (2022-09-18)
+
+  * Fixed #4367: Improved blog plugin date handling for MultiMarkdown syntax
+  * Fixed #4374: Fixed invalid URLs of related links to other blog posts
+
+mkdocs-material-8.5.2 (2022-09-18)
+
+  * Updated Mermaid.js to version 9.1.7
+  * Fixed overly large headlines in search results (8.5.0 regression)
+  * Fixed #4358: Navigation sections appear as clickable (8.5.0 regression)
+  * Fixed #4356: GitHub repository statistics fetched before cookie consent
+
+mkdocs-material-8.5.1 (2022-09-15)
+
+  * Fixed #4366: Removed dependencies with native extensions
+
+mkdocs-material-8.5.0+insiders-4.23.4 (2022-09-14)
+
+  * Fixed #4365: Recursion error in blog plugin due to deepcopy
+  * Fixed path errors for blog plugin on Windows
+  * Fixed publishing workflow in forked repositories
+
+mkdocs-material-8.5.0+insiders-4.23.3 (2022-09-13)
+
+  * Fixed previous and next page links for drafts of blog posts
+
+mkdocs-material-8.5.0 (2022-09-13)
+
+  * Added support for social cards
+  * Added support for code annotation anchor links (deep linking)
+  * Added support for code annotation comment stripping (syntax modifier)
+  * Added support for sidebars scrolling automatically to active item
+  * Added support for anchor following table of contents (= auto scroll)
+  * Added support for tag icons
+
+mkdocs-material-8.4.4+insiders-4.23.2 (2022-09-13)
+
+  * Fixed #4348: Blog plugin crashes on custom nav title
+  * Fixed blog plugin crashing when category contained only drafts
+  * Fixed rendering of content from blog index file
+
+mkdocs-material-8.4.4+insiders-4.23.1 (2022-09-12)
+
+  * Fixed #4345: Blog plugin errors with default settings
+
+mkdocs-material-8.4.4+insiders-4.23.0 (2022-09-12)
+
+  * Added blogging support via built-in blog plugin
+
+mkdocs-material-8.4.4 (2022-09-12)
+
+  * Moved comments integration to separate partial (comments.html)
+
+mkdocs-material-8.4.3+insiders-4.22.1 (2022-09-07)
+
+  * Fixed #4217: Tooltips in data tables render in wrong position
+
+mkdocs-material-8.4.3 (2022-09-07)
+
+  * Added Simple Icons to bundled icons (+2,300 icons)
+  * Added support for changing edit icon
+  * Moved page actions to separate partial (actions.html)
+  * Fixed #4291: Version switching doesn't stay on page when anchors are used
+  * Fixed #4327: Links in data tables do not receive link styling
+
+mkdocs-material-8.4.2 (2022-08-27)
+
+  * Updated Slovenian translations
+  * Fixed #4277: Feedback widget hidden after navigation with instant loading
+  * Fixed numeric tags in front matter breaking search functionality
+
+mkdocs-material-8.4.1+insiders-4.22.0 (2022-08-21)
+
+  * Added support for navigation status
+
+mkdocs-material-8.4.1 (2022-08-21)
+
+  * Updated Croatian and Hebrew translations
+
+mkdocs-material-8.4.0+insiders-4.21.1 (2022-08-13)
+
+  * Fixed #4176: Broken image when avatar is served by Gravatar
+  * Fixed #4212: Deferred search initialization for file:// locations
+
+mkdocs-material-8.4.0 (2022-08-13)
+
+  * Added support for cookie consent
+  * Added support for feedback widget (Was this page helpful?)
+  * Added support for dismissible announcement bar
+  * Added Armenian, Lithuanian, Tagalog, and Urdu translations
+
+mkdocs-material-8.3.9+insiders-4.21.0 (2022-07-17)
+
+  * Added meta plugin: set front matter for all pages in a folder
+  * Fixed #4114: Tags plugin fails if only tags_extra_files is set
+
+mkdocs-material-8.3.9+insiders-4.20.1 (2022-07-11)
+
+  * Fixed #4105: Tags plugin fails if tags_file is not set (4.20.0 regression)
+
+mkdocs-material-8.3.9+insiders-4.20.0 (2022-07-07)
+
+  * Added support for additional tags indexes
+  * Fixed #4100: Tag icons not shown in tags index
+
+mkdocs-material-8.3.9+insiders-4.19.2 (2022-07-04)
+
+  * Fixed #4051: Privacy plugin fails if symlinking isn't allowed on Windows
+
+mkdocs-material-8.3.9 (2022-07-04)
+
+  * Updated Taiwanese translations for search
+  * Allow ids for content tabs with special characters (for mkdocstrings)
+  * Fixed #4083: home not clickable when using versioning (8.3.5 regression)
+
+mkdocs-material-8.3.8+insiders-4.19.1 (2022-06-25)
+
+  * Added mkdocs-git-committers-plugin to Dockerfile
+  * Added mkdocs-git-revision-date-localized-plugin to Dockerfile
+
+mkdocs-material-8.3.8+insiders-4.19.0 (2022-06-24)
+
+  * Added support for document contributors
+  * Updated French translations for cookie consent
+
+mkdocs-material-8.3.8 (2022-06-24)
+
+  * Fixed #4053: Limit width of videos to content area
+  * Fixed empty tags in front matter breaking search
+
+mkdocs-material-8.3.7 (2022-06-22)
+
+  * Fixed search being stuck initializing when using tags (8.3.4 regression)
+
+mkdocs-material-8.3.6+insiders-4.18.2 (2022-06-16)
+
+  * Fixed #4026: Fixed tooltips not mounted for nested navigation links
+
+mkdocs-material-8.3.6 (2022-06-16)
+
+  * Fixed #4028: Links not clickable when using versioning (8.3.5 regression)
+
+mkdocs-material-8.3.5+insiders-4.18.1 (2022-06-14)
+
+  * Fixed #3990: Chinese search highlighting not working on non-boundaries
+
+mkdocs-material-8.3.5 (2022-06-14)
+
+  * Fixed #4012: Stay on page not working for alias of active version
+
+mkdocs-material-8.3.4+insiders-4.18.0 (2022-06-11)
+
+  * Added support for automatic dark/light mode
+  * Fixed #4009: Privacy plugin uses invalid paths for file cache on Windows
+
+mkdocs-material-8.3.4 (2022-06-11)
+
+  * Fixed #4004: Tags with multiple words not searchable
+
+mkdocs-material-8.3.3 (2022-06-07)
+
+  * Fixed #4000: Mermaid diagrams too dark in dark mode (8.3.0 regression)
+
+mkdocs-material-8.3.2+insiders-4.17.2 (2022-06-05)
+
+  * Added support for custom jieba dictionaries (Chinese search)
+
+mkdocs-material-8.3.2+insiders-4.17.1 (2022-06-05)
+
+  * Added support for cookie consent reject button
+  * Added support for cookie consent custom button ordering
+  * Fixed #3988: Content tab not focused after alternating anchor links
+
+mkdocs-material-8.3.2 (2022-06-05)
+
+  * Fixed #3987: Custom admonition icons don't work when defining color palette
+
+mkdocs-material-8.3.1+insiders-4.17.0 (2022-06-04)
+
+  * Added support for content tabs anchor links (deep linking)
+  * Fixed #3975: Detect composition events in search interface (Chinese)
+  * Fixed #3980: Search plugin doesn't use title set via front matter
+
+mkdocs-material-8.3.1 (2022-06-04)
+
+  * Bump required Jinja version to 3.0.2
+  * Removed unnecessary conditions in templates
+  * Fixed scroll offset when content tabs are brought into view
+  * Fixed #3977: Content tabs snapping oddly in Firefox
+  * Fixed #3983: Missing condition in footer partial (8.3.0 regression)
+
+mkdocs-material-8.3.0 (2022-06-02)
+
+  * Added support for custom admonition icons
+  * Added support for linking of content tabs
+  * Added support for boosting pages in search
+  * Added support for hiding footer navigation
+  * Added previous/next indicators to content tabs
+  * Improved typeset link colors in light and dark modes
+
+mkdocs-material-8.2.16+insiders-4.16.2 (2022-05-28)
+
+  * Fixed #3961: Nested sections triggered build error for navigation tabs
+
+mkdocs-material-8.2.16+insiders-4.16.1 (2022-05-28)
+
+  * Switched feedback widget rating titles to tooltips
+  * Improved contrast of link colors for light/dark color schemes
+  * Fixed #3950: Sticky navigation tabs rendering broken (4.15.2 regression)
+  * Fixed #3958: Links invisible when using white primary color
+
+mkdocs-material-8.2.16 (2022-05-28)
+
+  * Fixed #3957: Only animate code annotations when visible (save CPU cycles)
+
+mkdocs-material-8.2.15+insiders-4.16.0 (2022-05-25)
+
+  * Added support for navigation pruning
+  * Fixed search results for non-segmented characters (4.15.2 regression)
+
+mkdocs-material-8.2.15+insiders-4.15.2 (2022-05-22)
+
+  * Removed workaround for abbr on touch devices (superseded by tooltips)
+  * Fixed #3915: Improved Chinese search query segmentation
+  * Fixed #3938: Fixed tooltips position for navigation titles with ellipsis
+
 mkdocs-material-8.2.15+insiders-4.15.1 (2022-05-14)
 
+  * Improved performance of element focus observables
   * Fixed #3531: Added prev/next buttons to content tabs
   * Fixed tooltip positioning when host element is hidden
-  * Improved performance of element focus obervables
 
 mkdocs-material-8.2.15 (2022-05-14)
 
@@ -131,7 +916,7 @@ mkdocs-material-8.2.3 (2022-02-27)
 mkdocs-material-8.2.2 (2022-02-26)
 
   * Added automatic removal of query parameter when search is closed
-  * Fixed #3599: Anchors always overriden when using navigation tracking
+  * Fixed #3599: Anchors always overridden when using navigation tracking
 
 mkdocs-material-8.2.1+insiders-4.9.1 (2022-02-21)
 
@@ -311,7 +1096,7 @@ mkdocs-material-8.0.4 (2021-12-04)
 
 mkdocs-material-8.0.3+insiders-4.2.0 (2021-12-02)
 
-  * Added support for dismissable announcement bar
+  * Added support for dismissible announcement bar
   * Added support for named placeholders in feedback widget
 
 mkdocs-material-8.0.3 (2021-12-02)
@@ -347,7 +1132,7 @@ mkdocs-material-8.0.0 (2021-11-28)
   * Removed deprecated prebuilt search index support
   * Removed deprecated web app manifest – use customization
   * Removed extracopyright variable – use new copyright partial
-  * Removed Disqus integation – use customization
+  * Removed Disqus integration – use customization
   * Switched to :is() selectors for simple selector lists
   * Switched autoprefixer from last 4 years to last 2 years
   * Improved CSS overall to match modern standards
@@ -361,7 +1146,7 @@ mkdocs-material-7.3.6+insiders-3.2.3 (2021-11-20)
 
   * Updated Swedish and French translations
   * Removed support for .mermaid-experimental class (now .mermaid)
-  * Fixed #3202: Cookie consent not dismissable on file:// locations
+  * Fixed #3202: Cookie consent not dismissible on file:// locations
   * Fixed #3216: Cookie consent not dismissed when invoked via anchor
   * Fixed #3232: Mermaid.js sometimes runs twice (race condition)
 

CONTRIBUTING.md

@@ -1,7 +1,7 @@
 # Contributing
 
-Interested in contributing to the Material for MkDocs? Want to report a bug?
-Have a question? Before you do, please read the following guidelines.
+Interested in contributing to the Material for MkDocs? Have a question? Want to 
+report a bug? Before you do, please read the following guidelines.
 
 ## Submission context
 
@@ -26,7 +26,7 @@ a Pull Request with a fix. However, before doing so, please read the
 
 You can request a new feature by submitting an issue to our GitHub Repository.
 If you would like to implement a new feature, please submit an issue with a
-proposal for your work first, to be sure that it is of use for everyone, as
+proposal for your work first to be sure that it is of use to everyone, as
 Material for MkDocs is highly opinionated. Please consider what kind of change
 it is:
 
@@ -40,21 +40,51 @@ it is:
   the `master`, as it's always a matter of opinion whether if benefits the
   overall functionality of the project.
 
+### Missing translations?
+
+Material for MkDocs supports 60+ languages with the help of community
+contributions. When new features are added, sometimes, new translations are
+necessary as well. It's impossible for the maintainers of the project to update
+all translations (we just don't speak 60+ languages), so we have to rely on
+our contributors to update translations incrementally. This process is pretty
+simple, so if you find a translation missing in your language, follow these
+guidelines:
+
+1.  Fork the repository.
+
+2.  Open up the [translation file for your language] as well as the
+    [English translations], as they are always up-to-date. Compare them
+    side-by-side and add the missing translations. __Important__: only add the
+    translations that are different from the defaults, e.g. if your language
+    is left-to-right, don't add the `direction` translation, as English is
+    left-to-right as well. The following translations are for technical
+    purposes and should not be updated, so if they're missing from your
+    language, it's for good reason:
+
+    - `search.config.lang`
+    - `search.config.pipeline`
+    - `search.config.separator`
+
+3.  Create a PR (see below) with your changes.
+
+  [translation file for your language]: 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
+
 ## Submission guidelines
 
 ### Submitting an issue
 
 Before you submit an issue, please search the issue tracker, maybe an issue for
-your problem already exists and the discussion might inform you of workarounds
+your problem already exists, and the discussion might inform you of workarounds
 readily available.
 
-We want to fix all the issues as soon as possible, but before fixing a bug we
-need to reproduce and confirm it. In order to reproduce bugs we will
+We want to fix all the issues as soon as possible, but before fixing a bug, we
+need to reproduce and confirm it. In order to reproduce bugs, we will
 systematically ask you to provide a minimal reproduction scenario using the
 custom issue template. Please stick to the issue template.
 
-Unfortunately we are not able to investigate / fix bugs without a minimal
-reproduction scenario, so if we don't hear back from you we may close the issue.
+Unfortunately, we are not able to investigate / fix bugs without a minimal
+reproduction scenario, so if we don't hear back from you, we may close the issue.
 
 ### Submitting a Pull Request (PR)
 
@@ -66,9 +96,9 @@ go ahead.
     make your changes in a separate git branch and add descriptive messages to
     your commits.
 
-2.  **Build**: Before submitting a pull requests, [build the theme]. This is
-    a mandatory requirement for your PR to get accepted, as the theme should at
-    all times be installable through GitHub.
+2.  **Build**: Before submitting a pull request, [build the theme]. This is
+    a mandatory requirement for your PR to get accepted, as the theme should be 
+    installable through GitHub at all times.
 
 3.  **Pull Request**: After building the theme, commit the compiled output,
     push your branch to GitHub and send a PR to `mkdocs-material:master`. If we

Dockerfile

@@ -1,4 +1,4 @@
-# Copyright (c) 2016-2022 Martin Donath <martin.donath@squidfunk.com>
+# Copyright (c) 2016-2023 Martin Donath <martin.donath@squidfunk.com>
 
 # Permission is hereby granted, free of charge, to any person obtaining a copy
 # of this software and associated documentation files (the "Software"), to
@@ -18,13 +18,13 @@
 # FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS
 # IN THE SOFTWARE.
 
-FROM python:3.9.2-alpine3.13
+FROM python:3.11-alpine3.18
 
 # Build-time flags
 ARG WITH_PLUGINS=true
 
 # Environment variables
-ENV PACKAGES=/usr/local/lib/python3.9/site-packages
+ENV PACKAGES=/usr/local/lib/python3.11/site-packages
 ENV PYTHONDONTWRITEBYTECODE=1
 
 # Set build directory
@@ -32,11 +32,10 @@ WORKDIR /tmp
 
 # Copy files necessary for build
 COPY material material
-COPY MANIFEST.in MANIFEST.in
 COPY package.json package.json
+COPY pyproject.toml pyproject.toml
 COPY README.md README.md
-COPY requirements.txt requirements.txt
-COPY setup.py setup.py
+COPY *requirements.txt ./
 
 # Perform build and cleanup artifacts and caches
 RUN \
@@ -59,13 +58,24 @@ RUN \
     libxml2-dev \
     libxslt-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-redirects>=1.0"; \
+      "mkdocs-git-committers-plugin-2==1.1.1" \
+      "mkdocs-git-revision-date-localized-plugin==1.2.0" \
+      "mkdocs-minify-plugin==0.5.0" \
+      "mkdocs-redirects==1.2.0" \
+      "mkdocs-rss-plugin==1.6.0" \
+      "pillow>=9.0" \
+      "cairosvg>=2.5"; \
+  fi \
+&& \
+  if [ -e user-requirements.txt ]; then \
+    pip install -U -r user-requirements.txt; \
   fi \
 && \
   apk del .build \
@@ -84,6 +94,10 @@ RUN \
     -path "*/__pycache__/*" \
     -exec rm -f {} \;
 
+# Trust directory, required for git >= 2.35.2
+RUN git config --global --add safe.directory /docs &&\
+    git config --global --add safe.directory /site
+
 # Set working directory
 WORKDIR /docs
 

LICENSE

@@ -1,4 +1,4 @@
-Copyright (c) 2016-2022 Martin Donath <martin.donath@squidfunk.com>
+Copyright (c) 2016-2023 Martin Donath <martin.donath@squidfunk.com>
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to

MANIFEST.in

@@ -1,11 +0,0 @@
-recursive-include material *.js *.css *.map *.html *.svg *.png *.yml
-recursive-include material *.ttf *.woff *.woff2 LICENSE*
-recursive-exclude material/overrides *
-recursive-exclude site *
-recursive-exclude src *
-recursive-exclude * __pycache__
-recursive-exclude * *.py[co]
-include LICENSE
-include package.json
-include README.md
-include requirements.txt

README.md

@@ -39,7 +39,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">
@@ -58,45 +58,105 @@
 </p>
 
 <h2></h2>
+<p id="premium-sponsors">&nbsp;</p>
+<p align="center"><strong>Silver sponsors</strong></p>
+<p align="center">
+  <a href="https://fastapi.tiangolo.com/" target=_blank><img
+    src="https://raw.githubusercontent.com/squidfunk/mkdocs-material/master/.github/assets/sponsors/sponsor-fastapi.png" height="120"
+  /></a>
+</p>
 <p>&nbsp;</p>
-<p id="premium-sponsors" align="center"><strong>Special thanks</strong> to our <strong>premium sponsors</strong>:</p>
-<p>&nbsp;</p>
+<p align="center"><strong>Bronze sponsors</strong></p>
 <p align="center">
   <a href="https://cirrus-ci.org/" target=_blank><img
-    src="https://raw.githubusercontent.com/squidfunk/mkdocs-material/master/.github/assets/sponsors/sponsor-cirrus-ci.png" height="65"
+    src="https://raw.githubusercontent.com/squidfunk/mkdocs-material/master/.github/assets/sponsors/sponsor-cirrus-ci.png" height="58"
   /></a>
   <a href="https://docs.baslerweb.com/" target=_blank><img
-    src="https://raw.githubusercontent.com/squidfunk/mkdocs-material/master/.github/assets/sponsors/sponsor-basler.png" height="65"
-  /></a>
-  <a href="https://hummingbot.io/" target=_blank><img
-    src="https://raw.githubusercontent.com/squidfunk/mkdocs-material/master/.github/assets/sponsors/sponsor-hummingbot.png" height="65"
+    src="https://raw.githubusercontent.com/squidfunk/mkdocs-material/master/.github/assets/sponsors/sponsor-basler.png" height="58"
   /></a>
   <a href="https://kx.com/" target=_blank><img
-    src="https://raw.githubusercontent.com/squidfunk/mkdocs-material/master/.github/assets/sponsors/sponsor-kx.png" height="65"
+    src="https://raw.githubusercontent.com/squidfunk/mkdocs-material/master/.github/assets/sponsors/sponsor-kx.png" height="58"
   /></a>
   <a href="https://www.manticoregames.com/" target=_blank><img
-    src="https://raw.githubusercontent.com/squidfunk/mkdocs-material/master/.github/assets/sponsors/sponsor-manticore-games.png" height="65"
-  /></a>
-  <a href="https://www.accounttechnologies.com/" target=_blank><img
-    src="https://raw.githubusercontent.com/squidfunk/mkdocs-material/master/.github/assets/sponsors/sponsor-account-technologies.png" height="65"
+    src="https://raw.githubusercontent.com/squidfunk/mkdocs-material/master/.github/assets/sponsors/sponsor-manticore-games.png" height="58"
   /></a>
   <a href="https://orion-docs.prefect.io/" target=_blank><img
-    src="https://raw.githubusercontent.com/squidfunk/mkdocs-material/master/.github/assets/sponsors/sponsor-prefect.png" height="65"
+    src="https://raw.githubusercontent.com/squidfunk/mkdocs-material/master/.github/assets/sponsors/sponsor-prefect.png" height="58"
   /></a>
   <a href="https://datadoghq.com/" target=_blank><img
-    src="https://raw.githubusercontent.com/squidfunk/mkdocs-material/master/.github/assets/sponsors/sponsor-datadog.png" height="65"
+    src="https://raw.githubusercontent.com/squidfunk/mkdocs-material/master/.github/assets/sponsors/sponsor-datadog.png" height="58"
   /></a>
   <a href="https://www.zenoss.com/" target=_blank><img
-    src="https://raw.githubusercontent.com/squidfunk/mkdocs-material/master/.github/assets/sponsors/sponsor-zenoss.png" height="65"
+    src="https://raw.githubusercontent.com/squidfunk/mkdocs-material/master/.github/assets/sponsors/sponsor-zenoss.png" height="58"
   /></a>
-  <a href="https://www.elli.eco/en/home" target=_blank><img
-    src="https://raw.githubusercontent.com/squidfunk/mkdocs-material/master/.github/assets/sponsors/sponsor-elli.png" height="65"
-  /></a>
-  <a href="https://solutions.rstudio.com" target=_blank><img
-    src="https://raw.githubusercontent.com/squidfunk/mkdocs-material/master/.github/assets/sponsors/sponsor-rstudio.png" height="65"
+  <a href="https://docs.posit.co" target=_blank><img
+    src="https://raw.githubusercontent.com/squidfunk/mkdocs-material/master/.github/assets/sponsors/sponsor-posit.png" height="58"
   /></a>
   <a href="https://n8n.io" target=_blank><img
-    src="https://raw.githubusercontent.com/squidfunk/mkdocs-material/master/.github/assets/sponsors/sponsor-n8n.png" height="65"
+    src="https://raw.githubusercontent.com/squidfunk/mkdocs-material/master/.github/assets/sponsors/sponsor-n8n.png" height="58"
+  /></a>
+  <a href="https://www.dogado.de" target=_blank><img
+    src="https://raw.githubusercontent.com/squidfunk/mkdocs-material/master/.github/assets/sponsors/sponsor-dogado.png" height="58"
+  /></a>
+  <a href="https://wwt.com" target=_blank><img
+    src="https://raw.githubusercontent.com/squidfunk/mkdocs-material/master/.github/assets/sponsors/sponsor-wwt.png" height="58"
+  /></a>
+  <a href="https://coda.io" target=_blank><img
+    src="https://raw.githubusercontent.com/squidfunk/mkdocs-material/master/.github/assets/sponsors/sponsor-coda.png" height="58"
+  /></a>
+  <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://ipfabric.io/" target=_blank><img
+    src="https://raw.githubusercontent.com/squidfunk/mkdocs-material/master/.github/assets/sponsors/sponsor-ip-fabric.png" height="58"
+  /></a>
+  <a href="https://www.apex.ai/" target=_blank><img
+    src="https://raw.githubusercontent.com/squidfunk/mkdocs-material/master/.github/assets/sponsors/sponsor-apex-ai.png" height="58"
+  /></a>
+  <a href="https://jitterbit.com/" target=_blank><img
+    src="https://raw.githubusercontent.com/squidfunk/mkdocs-material/master/.github/assets/sponsors/sponsor-jitterbit.png" height="58"
+  /></a>
+  <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://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
+    src="https://raw.githubusercontent.com/squidfunk/mkdocs-material/master/.github/assets/sponsors/sponsor-cashapp.png" height="58"
+  /></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>
+  <a href="https://civicactions.com/" target=_blank><img
+    src="https://raw.githubusercontent.com/squidfunk/mkdocs-material/master/.github/assets/sponsors/sponsor-civic-actions.png" height="58"
+  /></a>
+  <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>
 </p>
 <p>&nbsp;</p>
@@ -135,7 +195,7 @@ documentation works for everyone.
 
 ### Open Source
 
-Trust 10,000+ users – choose a mature and actively maintained solution built
+Trust 20,000+ users – choose a mature and actively maintained solution built
 with state-of-the-art Open Source technologies. Keep ownership of your content
 without fear of vendor lock-in. Licensed under MIT.
 
@@ -165,7 +225,6 @@ For detailed installation instructions, configuration options, and a demo, visit
 
 [Atlassian](https://atlassian.github.io/data-center-helm-charts/),
 [AWS](https://aws.github.io/copilot-cli/),
-[Binance](https://docs.binance.org/),
 [Bloomberg](https://bloomberg.github.io/selekt/),
 [CERN](http://abpcomputing.web.cern.ch/),
 [Datadog](https://datadoghq.dev/integrations-core/),
@@ -173,6 +232,7 @@ For detailed installation instructions, configuration options, and a demo, visit
 [Hewlett Packard](https://hewlettpackard.github.io/squest/),
 [ING](https://ing-bank.github.io/baker/),
 [Intel](https://open-amt-cloud-toolkit.github.io/docs/),
+[JetBrains](https://jetbrains.github.io/projector-client/mkdocs/),
 [LinkedIn](https://linkedin.github.io/school-of-sre/),
 [Microsoft](https://microsoft.github.io/code-with-engineering-playbook/),
 [Mozilla](https://mozillafoundation.github.io/engineering-handbook/),
@@ -203,15 +263,17 @@ For detailed installation instructions, configuration options, and a demo, visit
 [Pydantic](https://pydantic-docs.helpmanual.io/),
 [Renovate](https://docs.renovatebot.com/),
 [Traefik](https://docs.traefik.io/),
+[Trivy](https://github.com/aquasecurity/trivy)
 [Vapor](https://docs.vapor.codes/),
 [ZeroNet](https://zeronet.io/docs/),
+[WebKit](https://docs.webkit.org/),
 [WTF](https://wtfutil.com/)
 
 ## License
 
 **MIT License**
 
-Copyright (c) 2016-2022 Martin Donath
+Copyright (c) 2016-2023 Martin Donath
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to

docs/alternatives.md

@@ -1,7 +1,3 @@
----
-template: overrides/main.html
----
-
 # Alternatives
 
 There are tons of static site generators and themes out there and choosing the
@@ -29,9 +25,9 @@ __Challenges__
 - More time needed to get up and running
 
 While [Docusaurus] is one of the best choices when it comes to documentation
-sites that output a single page applications, there are many more solutions,
+sites that output a single page application, there are many more solutions,
 including [Docz], [Gatsby], [Vuepress] and [Docsify] that approach
-this problem similarily.
+this problem similarly.
 
   [Docusaurus]: https://docusaurus.io/
   [React]: https://reactjs.org/

docs/blog/.authors.yml

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

docs/blog/.meta.yml

@@ -0,0 +1,3 @@
+comments: true
+hide:
+  - feedback

docs/blog/index.md

@@ -1,145 +1 @@
----
-template: overrides/main.html
-title: Blog
-search:
-  exclude: true
----
-
-<style>
-  .md-sidebar--secondary:not([hidden]) {
-    visibility: hidden;
-  }
-</style>
-
 # Blog
-
-## [Chinese search support – 中文搜索​支持]
-
-__Insiders adds experimental Chinese language support for the [built-in search 
-plugin] – a feature that has been requested for a long time given the large
-number of Chinese users.__
-
-<aside class="mdx-author" markdown>
-![@squidfunk][@squidfunk avatar]
-
-<span>__Martin Donath__ · @squidfunk</span>
-<span>
-:octicons-calendar-24: May 5, 2022 ·
-:octicons-clock-24: 5 min read ·
-[:octicons-tag-24: 8.2.13+insiders-4.14.0][insiders-4.14.0]
-</span>
-</aside>
-
----
-
-After the United States and Germany, the third-largest country of origin of
-Material for MkDocs users is China. For a long time, the built-in search plugin
-didn't allow for proper segmentation of Chinese characters, mainly due to 
-missing support in [lunr-languages] which is used for search tokenization and 
-stemming. The latest Insiders release adds long-awaited Chinese language support 
-for the built-in search plugin, something that has been requested by many users.
-
-  [:octicons-arrow-right-24: Continue reading][Chinese search support – 中文搜索​支持]
-
-  [built-in search plugin]: ../setup/setting-up-site-search.md#built-in-search-plugin
-  [@squidfunk avatar]: https://avatars.githubusercontent.com/u/932156
-  [insiders-4.14.0]: ../insiders/changelog.md#4.14.0
-  [lunr-languages]: https://github.com/MihaiValentin/lunr-languages
-  [Chinese search support – 中文搜索​支持]: 2022/chinese-search-support.md
-
-## [The past, present and future]
-
-__2021 was a fantastic year for this project as we shipped many new awesome
-features, saw significant user growth and leveraged GitHub Sponsors to make the
-project sustainable.__
-
-<aside class="mdx-author" markdown>
-![@squidfunk][@squidfunk avatar]
-
-<span>__Martin Donath__ · @squidfunk</span>
-<span>
-:octicons-calendar-24: December 27, 2021 ·
-:octicons-clock-24: 10 min read
-</span>
-</aside>
-
----
-
-Today, together, MkDocs and Material for MkDocs are among the most popular
-options when it comes to choosing a static site generator and theme for your
-technical documentation project. Material for MkDocs ensures that your
-content is always perfectly presented to your audience, regardless of screen
-resolution or device capabilities. It has evolved to a framework for technical
-writing, offering many features, some of which are yet to be found in other
-static site generators. However, we're far from the end, as 2022 is going to
-bring some interesting new capabilities.
-
-  [:octicons-arrow-right-24: Continue reading][The past, present and future]
-
-  [The past, present and future]: 2021/the-past-present-and-future.md
-
-## [Excluding content from search]
-
-__The latest Insiders release brings three new simple ways to exclude dedicated
-parts of a document from the search index, allowing for more fine-grained
-control.__
-
-<aside class="mdx-author" markdown>
-![@squidfunk][@squidfunk avatar]
-
-<span>__Martin Donath__ · @squidfunk</span>
-<span>
-:octicons-calendar-24: September 26, 2021 ·
-:octicons-clock-24: 5 min read ·
-[:octicons-tag-24: 7.3.0+insiders-3.1.1][insiders-3.1.1]
-</span>
-</aside>
-
----
-
-Two weeks ago, Material for MkDocs Insiders shipped a brand new search plugin,
-yielding massive improvements in usability, but also in speed and size of the
-search index. Interestingly, as discussed in the previous blog article, we only
-scratched the surface of what's now possible. This release brings some useful
-features that enhance the writing experience, allowing for more fine-grained
-control of what pages, sections and blocks of a Markdown file should be indexed
-by the built-in search functionality.
-
-[:octicons-arrow-right-24: Continue reading][Excluding content from search]
-
-  [Excluding content from search]: 2021/excluding-content-from-search.md
-  [insiders-3.1.1]: ../insiders/changelog.md#3.1.1
-
-## [Search: better, faster, smaller]
-
-__This is the story of how we managed to completely rebuild client-side search,
-delivering a significantly better user experience while making it faster and
-smaller at the same time.__
-
-<aside class="mdx-author" markdown>
-![@squidfunk][@squidfunk avatar]
-
-<span>__Martin Donath__ · @squidfunk</span>
-<span>
-:octicons-calendar-24: September 13, 2021 ·
-:octicons-clock-24: 15 min read ·
-[:octicons-tag-24: 7.2.6+insiders-3.0.0][insiders-3.0.0]
-</span>
-</aside>
-
----
-
-The search of Material for MkDocs is by far one of its best and most-loved
-assets: multilingual, offline-capable, and most importantly: _all client-side_.
-It provides a solution to empower the users of your documentation to find what
-they're searching for instantly without the headache of managing additional
-servers. However, even though several iterations have been made, there's still
-some room for improvement, which is why we rebuilt the search plugin and
-integration from the ground up. This article shines some light on the internals
-of the new search, why it's much more powerful than the previous version, and
-what's about to come.
-
-[:octicons-arrow-right-24: Continue reading][Search: better, faster, smaller]
-
-  [Search: better, faster, smaller]: 2021/search-better-faster-smaller.md
-  [insiders-3.0.0]: ../insiders/changelog.md#3.0.0

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

@@ -0,0 +1,247 @@
+---
+date: 2022-09-12
+authors: [squidfunk]
+description: >
+  Our new blog is built with the brand new built-in blog plugin. You can build
+  a blog alongside your documentation or standalone
+categories:
+  - Blog
+links:
+  - Getting started with Insiders: insiders/getting-started.md#requirements
+  - setup/setting-up-a-blog.md#built-in-blog-plugin
+---
+
+# Blog support just landed
+
+__Hey there! You're looking at our new blog, built with the brand new
+[built-in blog plugin]. With this plugin, you can easily build a blog alongside
+your documentation or standalone.__
+
+Proper support for blogging, as requested by many users over the past few years,
+was something that was desperately missing from Material for MkDocs' feature set.
+While everybody agreed that blogging support was a blind spot, it was not
+obvious whether MkDocs could be extended in a way to allow for blogging as we
+know it from [Jekyll] and friends. The [built-in blog plugin] proves that it is,
+after all, possible to build a blogging engine on top of MkDocs, in order to
+create a technical blog alongside your documentation, or as the main thing.
+
+<!-- more -->
+
+_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
+  [Jekyll]: https://jekyllrb.com/
+
+## Quick start
+
+### Setting up Insiders
+
+Before we can start bootstrapping a blog and [write our first post], we need to
+set up [Insiders], since the [built-in blog plugin] is currently reserved to
+sponsors. Without the funds this project receives through sponsorships, this
+plugin wouldn't exist. Three steps are necessary:
+
+1.  [Subscribe to a monthly sponsorship]
+2.  [Create a personal access token]
+3.  [Install Insiders]
+
+  [write our first post]: #writing-your-first-post
+  [Insiders]: ../../insiders/index.md
+  [Subscribe to a monthly sponsorship]: ../../insiders/index.md#how-to-become-a-sponsor
+  [Create a personal access token]: ../../insiders/getting-started.md#requirements
+  [Install Insiders]: ../../insiders/getting-started.md#installation
+
+### Creating a standalone blog
+
+After Insiders is installed, you can bootstrap a new project using the `mkdocs`
+executable:
+
+```
+mkdocs new .
+```
+
+This will create the following structure:
+
+``` { .sh .no-copy }
+.
+├─ docs/
+│  └─ index.md
+└─ mkdocs.yml
+```
+
+#### Configuration
+
+In this article, we're going to build a standalone blog, which means that the
+blog lives at the root of your project. For this reason, open `mkdocs.yml`,
+and replace its contents with:
+
+``` yaml
+site_name: My Blog
+theme:
+  name: material
+  features:
+    - navigation.sections
+plugins:
+  - meta
+  - blog:
+      blog_dir: . # (1)!
+  - search
+  - tags
+nav:
+  - index.md
+```
+
+1.  This is the important part – we're hosting the blog at the root of the
+    project, and not in a subdirectory. For more information, see the
+    [`blog_dir`][blog_dir] configuration option.
+
+  [blog_dir]: ../../setup/setting-up-a-blog.md#+blog.blog_dir
+
+#### Blog setup
+
+The blog index page lives in `docs/index.md`. This page was pre-filled by
+MkDocs with some content, so we're going to replace it with what we need to
+bootstrap the blog:
+
+``` markdown
+# Blog
+```
+
+That's it.
+
+### Writing your first post
+
+Now that we have set up the [built-in blog plugin], we can start writing our
+first post. All blog posts are written with the [exact same Markdown flavor] as
+already included with Material for MkDocs. First, create a folder called `posts`
+with a file called `hello-world.md`:
+
+``` { .sh .no-copy }
+.
+├─ docs/
+│  ├─ posts/
+│  │  └─ hello-world.md # (1)!
+│  └─ index.md
+└─ mkdocs.yml
+```
+
+1.  If you'd like to arrange posts differently, you're free to do so. The URLs
+    are built from the format specified in [`post_url_format`][post slugs] and
+    the titles and dates of posts, no matter how they are organized
+    inside the `posts` directory.
+
+Then, open up `hello-world.md`, and add the following lines:
+
+``` yaml
+---
+draft: true # (1)!
+date: 2022-01-31
+categories:
+  - Hello
+  - World
+---
+
+# Hello world!
+
+Lorem ipsum dolor sit amet, consectetur adipiscing elit. Pellentesque nec
+maximus ex. Sed consequat, nulla quis malesuada dapibus, elit metus vehicula
+erat, ut egestas tellus eros at risus. In hac habitasse platea dictumst.
+Phasellus id lacus pulvinar erat consequat pretium. Morbi malesuada arcu mauris
+Nam vel justo sem. Nam placerat purus non varius luctus. Integer pretium leo in
+sem rhoncus, quis gravida orci mollis. Proin id aliquam est. Vivamus in nunc ac
+metus tristique pellentesque. Suspendisse viverra urna in accumsan aliquet.
+
+<!-- more -->
+
+Donec volutpat, elit ac volutpat laoreet, turpis dolor semper nibh, et dictum
+massa ex pulvinar elit. Curabitur commodo sit amet dolor sed mattis. Etiam
+tempor odio eu nisi gravida cursus. Maecenas ante enim, fermentum sit amet
+molestie nec, mollis ac libero. Vivamus sagittis suscipit eros ut luctus.
+
+Nunc vehicula sagittis condimentum. Cras facilisis bibendum lorem et feugiat.
+In auctor accumsan ligula, at consectetur erat commodo quis. Morbi ac nunc
+pharetra, pellentesque risus in, consectetur urna. Nulla id enim facilisis
+arcu tincidunt pulvinar. Vestibulum laoreet risus scelerisque porta congue.
+In velit purus, dictum quis neque nec, molestie viverra risus. Nam pellentesque
+tellus id elit ultricies, vel finibus erat cursus.
+```
+
+1.  If you mark a post as a [draft], a red marker appears next to the post date 
+    on index pages. When the site is built, drafts are not included in the 
+    output. [This behavior can be changed], e.g. for rendering drafts when 
+    building deploy previews.
+
+When you spin up the [live preview server], you should be greeted by your first
+post! You'll also realize, that [archive] and [category] indexes have been
+automatically generated for you:
+
+  ![Blog]
+
+However, this is just the start. The [built-in blog plugin] packs a lot of
+functionality needed in day-to-day blogging. Visit the documentation of the
+plugin to learn about the following topics:
+
+<div class="mdx-columns" markdown>
+
+- [Adding an excerpt]
+- [Adding authors]
+- [Adding categories]
+- [Adding tags]
+- [Adding related links]
+- [Linking from and to posts]
+- [Setting the reading time]
+- [Setting defaults]
+
+</div>
+
+Additionally, the [built-in blog plugin] has dozens of [configuration options]
+which allow for fine-tuning the output. You can configure post slugs, general
+behavior and much more.
+
+  [exact same Markdown flavor]: ../../reference/index.md
+  [post slugs]: ../../setup/setting-up-a-blog.md#+blog.post_url_format
+  [draft]: ../../setup/setting-up-a-blog.md#drafts
+  [This behavior can be changed]: ../../setup/setting-up-a-blog.md#+blog.draft
+  [live preview server]: ../../creating-your-site.md#previewing-as-you-write
+  [archive]: ../../setup/setting-up-a-blog.md#archive
+  [category]: ../../setup/setting-up-a-blog.md#categories
+  [Blog]: blog-support-just-landed/blog.png
+  [Blog post]: blog-support-just-landed/blog-post.png
+  [Adding an excerpt]: ../../setup/setting-up-a-blog.md#adding-an-excerpt
+  [Adding authors]: ../../setup/setting-up-a-blog.md#adding-authors
+  [Adding categories]: ../../setup/setting-up-a-blog.md#adding-categories
+  [Adding tags]: ../../setup/setting-up-a-blog.md#adding-tags
+  [Adding related links]: ../../setup/setting-up-a-blog.md#adding-related-links
+  [Linking from and to posts]: ../../setup/setting-up-a-blog.md#linking-from-and-to-posts
+  [Setting the reading time]: ../../setup/setting-up-a-blog.md#setting-the-reading-time
+  [Setting defaults]: ../../setup/setting-up-a-blog.md#setting-defaults
+  [configuration options]: ../../setup/setting-up-a-blog.md#configuration
+
+## What's next?
+
+Getting basic blogging support out the door was quite a challenge – the
+[built-in blog plugin] is probably the biggest release this year and already
+packs a lot of functionality. However, Material for MkDocs is used in many
+different contexts, which is why we'd expect to iterate, as always.
+
+Some ideas already proposed by users:
+
+- __Blog series__: Authors should be able to create so called blog series and
+  assign posts to a blog series using simple identifiers. For each post that is
+  part of a series, a list with links to all other posts should be included in
+  the post's content.
+
+- __Author indexes__: Besides [archive] and [category] indexes, authors should 
+  be able to create per-author indexes, which list all posts linked to an
+  author. Additionally, a profile should be created for each author and linked
+  from posts.
+
+- __Social share buttons__: It should be easy to share blog posts via social
+  media or other ways. For this reason, it should be possible to automatically
+  include social sharing buttons with each post.
+
+What's still missing from the brand new [built-in blog plugin]? Feel free to
+share your ideas in the comments. Together, we can build one of the best modern
+engines for technical blogging!

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

@@ -1,11 +1,16 @@
 ---
-template: overrides/blog.html
+date: 2022-05-05
+authors: [squidfunk]
 title: Chinese search support
 description: >
   Insiders adds Chinese language support for the built-in search plugin – a 
   feature that has been requested many times
-hide:
-  - feedback
+categories:
+  - Search
+links:
+  - blog/posts/search-better-faster-smaller.md
+  - setup/setting-up-site-search.md#chinese-language-support
+  - insiders/index.md#how-to-become-a-sponsor
 ---
 
 # Chinese search support – 中文搜索​支持
@@ -14,30 +19,15 @@ __Insiders adds experimental Chinese language support for the [built-in search
 plugin] – a feature that has been requested for a long time given the large
 number of Chinese users.__
 
-<aside class="mdx-author" markdown>
-![@squidfunk][@squidfunk avatar]
-
-<span>__Martin Donath__ · @squidfunk</span>
-<span>
-:octicons-calendar-24: May 5, 2022 ·
-:octicons-clock-24: 5 min read ·
-[:octicons-tag-24: 8.2.13+insiders-4.14.0][insiders-4.14.0]
-</span>
-</aside>
-
-  [built-in search plugin]: ../../setup/setting-up-site-search.md#built-in-search-plugin
-  [@squidfunk avatar]: https://avatars.githubusercontent.com/u/932156
-  [insiders-4.14.0]: ../../insiders/changelog.md#4.14.0
-
----
-
 After the United States and Germany, the third-largest country of origin of
-Material for MkDocs users is China. For a long time, the built-in search plugin
+Material for MkDocs users is China. For a long time, the [built-in search plugin]
 didn't allow for proper segmentation of Chinese characters, mainly due to 
-missing support in [lunr-languages] which is used for search tokenization and 
-stemming. The latest Insiders release adds long-awaited Chinese language support 
+missing support in [lunr-languages] which is used for search tokenization and
+stemming. The latest Insiders release adds long-awaited Chinese language support
 for the built-in search plugin, something that has been requested by many users.
 
+<!-- more -->
+
 _Material for MkDocs終於​支持​中文​了！文本​被​正確​分割​並且​更​容易​找到。_
 { style="display: inline" }
 
@@ -45,23 +35,25 @@ _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
   [lunr-languages]: https://github.com/MihaiValentin/lunr-languages
 
 ## Configuration
 
 Chinese language support for Material for MkDocs is provided by [jieba], an
-excellent Chinese text segmentation library. If [jieba] is installed, the 
-built-in search plugin automatically detects Chinese characters and runs them 
+excellent Chinese text segmentation library. If [jieba] is installed, the
+built-in search plugin automatically detects Chinese characters and runs them
 through the segmenter. You can install [jieba] with:
 
 ```
 pip install jieba
 ```
 
-The next step is only required if you specified the [separator] configuration
-in `mkdocs.yml`. Text is segmented with [zero-width whitespace] characters, so
-it renders exactly the same in the search modal. Adjust `mkdocs.yml` so that
-the [separator] includes the `\u200b` character:
+The next step is only required if you specified the [`separator`][separator] 
+configuration in `mkdocs.yml`. Text is segmented with [zero-width whitespace] 
+characters, so it renders exactly the same in the search modal. Adjust
+`mkdocs.yml` so that the [`separator`][separator] includes the `\u200b`
+character:
 
 ``` yaml
 plugins:

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

@@ -1,12 +1,15 @@
 ---
-template: overrides/blog.html
+date: 2021-09-26
+authors: [squidfunk]
 description: >
   Three new simple ways to exclude dedicated parts of a document from the search
   index, allowing for more fine-grained control
-search:
-  exclude: true
-hide:
-  - feedback
+categories:
+  - Search
+links:
+  - blog/posts/search-better-faster-smaller.md
+  - setup/setting-up-site-search.md#search-exclusion
+  - insiders/index.md#how-to-become-a-sponsor
 ---
 
 # Excluding content from search
@@ -15,22 +18,6 @@ __The latest Insiders release brings three new simple ways to exclude
 dedicated parts of a document from the search index, allowing for more
 fine-grained control.__
 
-<aside class="mdx-author" markdown>
-![@squidfunk][@squidfunk avatar]
-
-<span>__Martin Donath__ · @squidfunk</span>
-<span>
-:octicons-calendar-24: September 26, 2021 ·
-:octicons-clock-24: 5 min read ·
-[:octicons-tag-24: 7.3.0+insiders-3.1.1][insiders-3.1.1]
-</span>
-</aside>
-
-  [@squidfunk avatar]: https://avatars.githubusercontent.com/u/932156
-  [insiders-3.1.1]: ../../insiders/changelog.md#3.1.1
-
----
-
 Two weeks ago, Material for MkDocs Insiders shipped a [brand new search
 plugin], yielding [massive improvements in usability], but also in [speed
 and size] of the search index. Interestingly, as discussed in the previous
@@ -39,6 +26,8 @@ release brings some useful features that enhance the writing experience,
 allowing for more fine-grained control of what pages, sections and blocks of a
 Markdown file should be indexed by the built-in search functionality.
 
+<!-- more -->
+
 _The following section discusses existing solutions for excluding pages and
 sections from the search index. If you immediately want to learn what's new,
 skip to the [section just after that][what's new]._
@@ -124,7 +113,7 @@ directive to the front matter of the respective Markdown file. The good thing
 is that the author now only has to check the top of the document to learn
 whether it is excluded or not:
 
-``` sh
+``` yaml
 ---
 search:
   exclude: true
@@ -137,11 +126,11 @@ search:
 ### Excluding sections
 
 If a section should be excluded, the author can use the [Attribute Lists]
-extension to add a __pragma__ called `{ data-search-exclude }` at the end of a
+extension to add a __pragma__ called `data-search-exclude` at the end of a
 heading. The pragma is not included in the final HTML, as search pragmas are
 filtered by the search plugin before the page is rendered:
 
-=== ":octicons-file-code-16: docs/page.md"
+=== ":octicons-file-code-16: `docs/page.md`"
 
     ``` markdown
     # Document title
@@ -155,7 +144,7 @@ filtered by the search plugin before the page is rendered:
     The content of this section is excluded
     ```
 
-=== ":octicons-codescan-16: search_index.json"
+=== ":octicons-codescan-16: `search_index.json`"
 
     ``` json
     {
@@ -181,7 +170,7 @@ If even more fine-grained control is desired, the __pragma__ can be added to
 any [block-level element] or [inline-level element] that is officially
 supported by the [Attribute Lists] extension:
 
-=== ":octicons-file-code-16: docs/page.md"
+=== ":octicons-file-code-16: `docs/page.md`"
 
     ``` markdown
     # Document title
@@ -192,7 +181,7 @@ supported by the [Attribute Lists] extension:
     { data-search-exclude }
     ```
 
-=== ":octicons-codescan-16: search_index.json"
+=== ":octicons-codescan-16: `search_index.json`"
 
     ``` json
     {

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

@@ -1,12 +1,16 @@
 ---
-template: overrides/blog.html
+date: 2021-09-13
+authors: [squidfunk]
+readtime: 15
 description: >
   How we rebuilt client-side search, delivering a better user experience while
   making it faster and smaller at the same time
-search:
-  exclude: true
-hide:
-  - feedback
+categories:
+  - Search
+  - Performance
+links:
+  - setup/setting-up-site-search.md#built-in-search-plugin
+  - insiders/index.md#how-to-become-a-sponsor
 ---
 
 # Search: better, faster, smaller
@@ -15,22 +19,6 @@ __This is the story of how we managed to completely rebuild client-side search,
 delivering a significantly better user experience while making it faster and
 smaller at the same time.__
 
-<aside class="mdx-author" markdown>
-![@squidfunk][@squidfunk avatar]
-
-<span>__Martin Donath__ · @squidfunk</span>
-<span>
-:octicons-calendar-24: September 13, 2021 ·
-:octicons-clock-24: 15 min read ·
-[:octicons-tag-24: 7.2.6+insiders-3.0.0][insiders-3.0.0]
-</span>
-</aside>
-
-  [@squidfunk avatar]: https://avatars.githubusercontent.com/u/932156
-  [insiders-3.0.0]: ../../insiders/changelog.md#3.0.0
-
----
-
 The [search] of Material for MkDocs is by far one of its best and most-loved
 assets: [multilingual], [offline-capable], and most importantly: _all
 client-side_. It provides a solution to empower the users of your documentation
@@ -41,6 +29,8 @@ plugin and integration from the ground up. This article shines some light on the
 internals of the new search, why it's much more powerful than the previous
 version, and what's about to come.
 
+<!-- more -->
+
 _The next section discusses the architecture and issues of the current search
 implementation. If you immediately want to learn what's new, skip to the
 [section just after that][what's new]._
@@ -78,7 +68,7 @@ the original Markdown file:
 
 ??? example "Expand to inspect example"
 
-    === ":octicons-file-code-16: docs/page.md"
+    === ":octicons-file-code-16: `docs/page.md`"
 
         ```` markdown
         # Example
@@ -108,7 +98,7 @@ the original Markdown file:
         * Profit!
         ````
 
-    === ":octicons-codescan-16: search_index.json"
+    === ":octicons-codescan-16: `search_index.json`"
 
         ``` json
         {
@@ -197,8 +187,8 @@ the following steps are taken:
     remain. Linking is necessary, as search results are grouped by page.
 
 2.  __Tokenization__: The `title` and `text` values of each section are split
-    into tokens by using the [separator] as configured in `mkdocs.yml`.
-    Tokenization itself is carried out by
+    into tokens by using the [`separator`][separator] as configured in
+    `mkdocs.yml`. Tokenization itself is carried out by
     [lunr's default tokenizer][default tokenizer], which doesn't allow for
     lookahead or separators spanning multiple characters.
 
@@ -216,7 +206,7 @@ more magic involved, e.g., search results are [post-processed] and [rescored] to
 account for some shortcomings of [lunr], but in general, this is how data gets
 into and out of the index.
 
-  [separator]: ../../setup/setting-up-site-search.md#separator
+  [separator]: ../../setup/setting-up-site-search.md#search-separator
   [default tokenizer]: https://github.com/olivernn/lunr.js/blob/aa5a878f62a6bba1e8e5b95714899e17e8150b38/lunr.js#L413-L456
   [post-processed]: https://github.com/squidfunk/mkdocs-material/blob/ec7ccd2b2d15dd033740f388912f7be7738feec2/src/assets/javascripts/integrations/search/_/index.ts#L249-L272
   [rescored]: https://github.com/squidfunk/mkdocs-material/blob/ec7ccd2b2d15dd033740f388912f7be7738feec2/src/assets/javascripts/integrations/search/_/index.ts#L274-L275
@@ -421,9 +411,9 @@ On to the next step in the process: __tokenization__.
 ### Tokenizer lookahead
 
 The [default tokenizer] of [lunr] uses a regular expression to split a given
-string by matching each character against the [separator] as defined in
-`mkdocs.yml`. This doesn't allow for more complex separators based on
-lookahead or multiple characters.
+string by matching each character against the [`separator`][separator] as
+defined in `mkdocs.yml`. This doesn't allow for more complex separators based
+on lookahead or multiple characters.
 
 Fortunately, __our new search implementation provides an advanced tokenizer__
 that doesn't have these shortcomings and supports more complex regular
@@ -439,14 +429,14 @@ characters at which the string should be split, the following three sections
 explain the remainder of the regular expression.[^4]
 
   [^4]:
-    As a fun fact: the [separator default value] of the search plugin being
-    `[\s\-]+` always has been kind of irritating, as it suggests that multiple
-    characters can be considered being a separator. However, the `+` is
-    completely irrelevant, as regular expression groups involving multiple
-    characters were never supported by
+    As a fun fact: the [`separator`][separator] [default value] of the search
+    plugin being `[\s\-]+` always has been kind of irritating, as it suggests
+    that multiple characters can be considered being a separator. However, the
+    `+` is completely irrelevant, as regular expression groups involving
+    multiple characters were never supported by
     [lunr's default tokenizer][default tokenizer].
 
-  [separator default value]: https://www.mkdocs.org/user-guide/configuration/#separator
+  [default value]: https://www.mkdocs.org/user-guide/configuration/#separator
 
 #### Case changes
 

docs/blog/posts/the-past-present-and-future.md

@@ -1,12 +1,11 @@
 ---
-template: overrides/blog.html
+date: 2021-12-27
+authors: [squidfunk]
 description: >
   2021 was a fantastic year for this project as we shipped many new awesome
   features and made this project sustainable
-search:
-  exclude: true
-hide:
-  - feedback
+categories:
+  - General
 ---
 
 # The past, present and future
@@ -15,20 +14,6 @@ __2021 was a fantastic year for this project as we shipped many new awesome
 features, saw significant user growth and leveraged GitHub Sponsors to make the
 project sustainable.__
 
-<aside class="mdx-author" markdown>
-![@squidfunk][@squidfunk avatar]
-
-<span>__Martin Donath__ · @squidfunk</span>
-<span>
-:octicons-calendar-24: December 27, 2021 ·
-:octicons-clock-24: 10 min read
-</span>
-</aside>
-
-  [@squidfunk avatar]: https://avatars.githubusercontent.com/u/932156
-
----
-
 Today, together, [MkDocs] and Material for MkDocs are among the most popular
 options when it comes to choosing a static site generator and theme for your
 technical documentation project. Material for MkDocs ensures that your
@@ -38,6 +23,8 @@ writing, offering many features, some of which are yet to be found in other
 static site generators. However, we're far from the end, as 2022 is going to
 bring some interesting new capabilities.
 
+<!-- more -->
+
 _This article showcases all features that were added in 2021 and gives an
 outlook on what's going to drop in 2022. Additionally, it provides some context
 on the history of the project._
@@ -132,7 +119,7 @@ are still exclusively available to sponsors as part of [Insiders]:
 - [Boosting pages in search]
 - [Brand new search plugin]
 - [Code annotations]
-- [Code annotations: anchor links]
+- Code annotations: anchor links
 - [Code annotations: strip comments]
 - [Code block titles]
 - [Code block line anchors]
@@ -180,14 +167,13 @@ __55__ times, `mkdocs-material-insiders` was shipped __72__ times.
   [Boosting pages in search]: ../../setup/setting-up-site-search.md#search-boosting
   [Brand new search plugin]: search-better-faster-smaller.md
   [Code annotations]: ../../reference/code-blocks.md#adding-annotations
-  [Code annotations: anchor links]: ../../reference/code-blocks.md#anchor-links
   [Code annotations: strip comments]: ../../reference/code-blocks.md#stripping-comments
   [Code block titles]: ../../reference/code-blocks.md#adding-a-title
   [Code block line anchors]: ../../setup/extensions/python-markdown-extensions.md#anchor-linenums
   [Color palette toggle]: ../../setup/changing-the-colors.md#color-palette-toggle
   [Content tabs: improved support]: ../../reference/content-tabs.md
   [Content tabs: auto-linking]: ../../reference/content-tabs.md#linked-content-tabs
-  [Cookie consent]: ../../setup/ensuring-data-privacy.md#native-cookie-consent
+  [Cookie consent]: ../../setup/ensuring-data-privacy.md#cookie-consent
   [Custom admonition icons]: ../../reference/admonitions.md#admonition-icons
   [Dark mode support for images]: ../../reference/images.md#light-and-dark-mode
   [Dismissable announcement bar]: ../../setup/setting-up-the-header.md#mark-as-read

docs/browser-support.md

@@ -1,11 +1,7 @@
----
-template: overrides/main.html
----
-
 # Browser support
 
 Material for MkDocs goes at great lengths to support the largest possible range
-of browsers while retaining the simplemost possibilities for customization via
+of browsers while retaining the simplest possibilities for customization via
 modern CSS features like [custom properties] and [mask images].
 
   [custom properties]: https://caniuse.com/css-variables
@@ -15,8 +11,8 @@ modern CSS features like [custom properties] and [mask images].
 
 The following table lists all browsers for which Material for MkDocs offers full
 support, so it can be assumed that all features work without degradation. If you
-find a feature not to be working in a browser in the supported version range,
-please [open an issue]:
+find that something doesn't look right in a browser which is in the supported
+version range, please [open an issue]:
 
 <figure markdown>
 

docs/contributing/index.md

@@ -0,0 +1,58 @@
+# Contributing
+
+Material for MkDocs is an actively maintained and constantly improved project 
+that caters to a diverse user base with varying backgrounds and needs. In order
+to effectively address the needs of all our users, evaluate requests, and fix 
+bugs, a lot of work from us maintainers is required.
+
+## How to contribute
+
+We have invested quite a lot of time in creating better templates for our
+[issue tracker], optimizing the processes for our users to report bugs, request
+features or changes, contribute to the project, or exchange with our community. 
+This section of the documentation explains each process.
+
+  [issue tracker]: https://github.com/squidfunk/mkdocs-material/issues
+
+### Creating an issue
+
+<div class="grid cards" markdown>
+
+-   :material-bug:{ .lg .middle } __Something is not working?__
+
+    ---
+
+    Report a bug in Material for MkDocs by creating an issue and a reproduction
+
+    [:octicons-arrow-right-24: Report a bug][report a bug]
+
+-   :material-file-document:{ .lg .middle } __Missing information in our docs?__
+
+    ---
+
+    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?__
+
+    ---
+
+    Propose a change or 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?__
+
+    ---
+
+    Ask questions on our discussion board and get in touch with our community
+
+    [:octicons-arrow-right-24: Ask a question][ask a question]
+
+</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

docs/contributing/reporting-a-bug.md

@@ -0,0 +1,314 @@
+# Reporting a bug
+
+Material for MkDocs is an actively maintained project that we constantly strive
+to improve. With a project of this size and complexity, bugs may occur. If you
+think you have discovered a bug, you can help us by submitting an issue in our
+public [issue tracker] by following this guide.
+
+  [issue tracker]: https://github.com/squidfunk/mkdocs-material/issues
+
+## Before creating an issue
+
+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.__
+
+### Upgrade to latest version
+
+Chances are that the bug you discovered was already fixed in a subsequent
+version. Thus, before reporting an issue, ensure that you're running the
+[latest version] of Material for MkDocs. Please consult our [upgrade guide] to
+learn how to upgrade to the latest version.
+
+!!! warning "Bug fixes are not backported"
+
+    Please understand that only bugs that occur in the latest version of
+    Material for MkDocs will be addressed. Also, to reduce duplicate efforts,
+    fixes cannot be backported to earlier versions.
+
+### Remove customizations
+
+If you're using [customizations] like [additional CSS], [JavaScript], or
+[theme extension], please remove them from `mkdocs.yml` before reporting a bug.
+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]
+  - [`extra_css`][extra_css]
+  - [`extra_javascript`][extra_javascript]
+
+If, after removing those settings, the bug is gone, the bug is likely caused by
+your customizations. A good idea is to add them back gradually to narrow down
+the root cause of the problem. If you did a major version upgrade, make sure you
+adjusted all partials you have overridden.
+
+!!! warning "Customizations mentioned in our documentation"
+
+    A handful of the features Material for MkDocs offers can only be implemented
+    with customizations. If you find a bug in any of the customizations [that
+    our documentation explicitly mentions], you are, of course, encouraged to
+    report it.
+
+__Don't be shy to ask on our [discussion board] for help if you run into
+problems.__
+
+  [latest version]: ../changelog/index.md
+  [upgrade guide]: ../upgrade.md
+  [Customizations]: ../customization.md
+  [additional CSS]: ../customization.md#additional-css
+  [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
+  [extra_css]: https://www.mkdocs.org/user-guide/configuration/#extra_css
+  [extra_javascript]: https://www.mkdocs.org/user-guide/configuration/#extra_javascript
+  [discussion board]: https://github.com/squidfunk/mkdocs-material/discussions
+  [StackOverflow]: https://stackoverflow.com
+  [that our documentation explicitly mentions]: ?q="extends+base"
+
+### Search for solutions
+
+At this stage, we know that the problem persists in the latest version and is
+not caused by any of your customizations. However, the problem might result from
+a small typo or a syntactical error in a configuration file, e.g., `mkdocs.yml`.
+
+Now, before you go through the trouble of creating a bug report that is answered
+and closed right away with a link to the relevant documentation section or
+another already reported or closed issue or discussion, you can save time for
+us and yourself by doing some research:
+
+1.  [Search our documentation] and look for the relevant sections that could
+    be related to your problem. If found, make sure that you configured
+    everything correctly.[^1]
+
+  [^1]:
+    When adding lines to `mkdocs.yml`, make sure you are preserving the
+    indentation as mentioned in the documentation since YAML is a
+    whitespace-sensitive language. Many reported issues turn out to be
+    configuration errors.
+
+1.  [Search our issue tracker][issue tracker], as another user might already
+    have reported the same problem, and there might even be a known workaround
+    or fix for it. Thus, no need to create a new issue.
+
+2.  [Search our discussion board][discussion board] to learn if other users
+    are struggling with similar problems and work together with our great
+    community towards a solution. Many problems are solved here.
+
+__Keep track of all <u>search terms</u> and <u>relevant links</u>, you'll need
+them in the bug report.__[^2]
+
+  [^2]:
+    We might be using terminology in our documentation different from yours,
+    but mean the same. When you include the search terms and related links
+    in your bug report, you help us to adjust and improve the documentation.
+
+---
+
+At this point, when you still haven't found a solution to your problem, we
+encourage you to create an issue because it's now very likely that you
+stumbled over something we don't know yet. Read the following section to learn
+how to create a complete and helpful bug report.
+
+  [Search our documentation]: ?q=
+
+## Issue template
+
+We have created a new issue template to make the bug reporting process as simple
+as possible and more efficient for the community and us. It is the result of
+our experience answering and fixing more than 1,600 issues (and counting) and
+consists of the following parts:
+
+- [Title]
+- [Context] <small>optional</small>
+- [Description]
+- [Related links]
+- [Reproduction]
+- [Steps to reproduce]
+- [Browser] <small>optional</small>
+- [Checklist]
+
+  [Title]: #title
+  [Context]: #context
+  [Description]: #description
+  [Related links]: #related-links
+  [Reproduction]: #reproduction
+  [Steps to reproduce]: #steps-to-reproduce
+  [Browser]: #browser
+  [Checklist]: #checklist
+
+### Title
+
+A good title is short and descriptive. It should be a one-sentence executive
+summary of the issue, so the impact and severity of the bug you want to report
+can be inferred from the title.
+
+| <!-- --> | Example  |
+| -------- | -------- | 
+| :material-check:{ style="color: #4DB6AC" } __Clear__ | Built-in `typeset` plugin changes precedence of nav title over `h1`
+| :material-close:{ style="color: #EF5350" } __Wordy__ | The built-in `typeset` plugin changes the precedence of the nav title over the document headline
+| :material-close:{ style="color: #EF5350" } __Unclear__ | Title does not work
+| :material-close:{ style="color: #EF5350" } __Generic__ | Please help
+
+### Context <small>optional</small> { #context }
+
+Before describing the bug, you can provide additional context for us to
+understand what you are trying to achieve. Explain the circumstances
+in which you're using Material for MkDocs, and what you _think_ might be
+relevant. Don't write about the bug here.
+
+> __Why this might be helpful__: some errors only manifest in specific settings,
+> environments or edge cases, for example, when your documentation contains
+> thousands of documents.
+
+### Description
+
+Now, to the bug you want to report. Provide a clear, focused, specific, and
+concise summary of the bug you encountered. Explain why you think this is a bug
+that should be reported to Material for MkDocs, and not to one of its
+dependencies.[^3] Adhere to the following principles:
+
+  [^3]:
+    Sometimes, users report bugs on our [issue tracker] that are caused by one
+    of our upstream dependencies, including [MkDocs], [Python Markdown],
+    [Python Markdown Extensions] or third-party plugins. A good rule of thumb is
+    to change the [`theme.name`][theme.name] to `mkdocs` or `readthedocs` and
+    check if the problem persists. If it does, the problem is likely not
+    related to Material for MkDocs and should be reported upstream. When in
+    doubt, use our [discussion board] to ask for help.
+
+-   __Explain the <u>what</u>, not the <u>how</u>__ – don't explain
+    [how to reproduce the bug][Steps to reproduce] here, we're getting there.
+    Focus on articulating the problem and its impact as clearly as possible.
+
+-   __Keep it short and concise__ – if the bug can be precisely explained in one
+    or two sentences, perfect. Don't inflate it – maintainers and future users
+    will be grateful for having to read less.
+
+-   __One bug at a time__ – if you encounter several unrelated bugs, please
+    create separate issues for them. Don't report them in the same issue, as
+    this makes attribution difficult.
+
+---
+
+:material-run-fast: __Stretch goal__ – if you found a workaround or a way to fix
+the bug, you can help other users temporarily mitigate the problem before
+we maintainers can fix the bug in our code base.
+
+> __Why we need this__: in order for us to understand the problem, we
+> need a clear description of it and quantify its impact, which is essential
+> for triage and prioritization.
+
+  [MkDocs]: https://www.mkdocs.org
+  [Python Markdown]: https://python-markdown.github.io/extensions/
+  [Python Markdown Extensions]: https://facelessuser.github.io/pymdown-extensions/
+  [theme.name]: https://www.mkdocs.org/user-guide/configuration/#theme
+
+### Related links
+
+Of course, prior to reporting a bug, you have read our documentation and
+[could not find a working solution][search for solutions]. Please share links
+to all sections of our documentation that might be relevant to the bug, as it
+helps us gradually improve it.
+
+Additionally, since you have searched our [issue tracker] and [discussion board]
+before reporting an issue, and have possibly found several issues or
+discussions, include those as well. Every link to an issue or discussion creates
+a backlink, guiding us maintainers and other users in the future.
+
+---
+
+:material-run-fast: __Stretch goal__ – if you also include the search terms you
+used when [searching for a solution][search for solutions] to your problem, you
+make it easier for us maintainers to improve the documentation.
+
+> __Why we need this__: related links help us better understand what you were
+> trying to achieve and whether sections of our documentation need to be
+> adjusted, extended, or overhauled.
+
+  [search for solutions]: #search-for-solutions
+
+### 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
+the bug and quickly find its root cause. It's a proven fact that issues with
+concise and small reproductions can be fixed much faster.
+
+[:material-bug:&nbsp; Create a reproduction][Create reproduction]{ .md-button .md-button--primary }
+
+---
+
+After you have created the reproduction, you should have a .zip file, ideally not
+larger than 1 MB. Just drag and drop the .zip file into this field, which 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
+> invest a lot of time into trying to recreate the right conditions to even
+> inspect the bug, let alone fix it.
+
+!!! warning "Don't share links to repositories"
+
+    While we know that it is a good practice among developers to include a link
+    to a repository with the bug report, we currently don't support those in our
+    process. The reason is that the reproduction which is automatically
+    produced by the [built-in info plugin] contains all of the necessary
+    environment information that is often forgotten to be included.
+    
+    Additionally, there are many non-technical users of Material for MkDocs that
+    have trouble creating repositories.
+
+  [Create reproduction]: ../guides/creating-a-reproduction.md
+  [built-in info plugin]: ../guides/creating-a-reproduction.md#creating-a-zip-file
+
+### Steps to reproduce
+
+At this point, you provided us with enough information to understand the bug,
+and you gave us a reproduction that we could run and inspect. However, when we
+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
+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.
+
+> __Why we need this__: we must know how to navigate your reproduction in order
+> to observe the bug, as some bugs only occur at certain viewports or in
+> specific conditions.
+
+### Browser <small>optional</small> { #browser }
+
+If you're reporting a bug that only happens 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.
+
+> __Why we need this__: some bugs only occur in specific browsers or versions.
+> Since now, almost all browsers are evergreen, we usually don't need to know the
+> version in which it occurs, but we might ask for it later. When in doubt, add
+> the browser version as the first step in the field above.
+
+  [previewing]: http://localhost:8000/mkdocs-material/creating-your-site/#previewing-as-you-write
+  [building]: http://localhost:8000/mkdocs-material/creating-your-site/#building-your-site
+
+### Checklist
+
+Thanks for following the guide and creating a high-quality and complete bug
+report – you are almost done. This section ensures that you have read this guide
+and have worked to the best of your knowledge to provide us with everything we 
+need to know to help you.
+
+__We'll take it from here.__
+
+## Incomplete issues
+
+Please understand that we reserve the right to close incomplete issues which
+do not contain minimal reproductions or do not adhere to the quality standards
+and requirements mentioned in this document. Issues can be reopened when the
+missing information has been provided.

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

@@ -0,0 +1,89 @@
+# Reporting a docs issue
+
+In the past seven years, our documentation has grown to more than 60 pages. With
+a site being this large, inconsistencies can occur. If you find an inconsistency
+or see room for clarification or improvement, please submit an issue to
+our public [issue tracker] by following this guide.
+
+  [issue tracker]: https://github.com/squidfunk/mkdocs-material/issues
+
+## Issue template
+
+Reporting a documentation issue is usually less involved than reporting a bug,
+as we don't need a [reproduction]. Please thoroughly read the following guide
+before 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
+
+A good title should be a short, one-sentence description of the issue, contain
+all relevant information and, in particular, keywords to simplify the search in
+the issue tracker.
+
+| <!-- --> | Example  |
+| -------- | -------- | 
+| :material-check:{ style="color: #4DB6AC" } __Clear__ | Clarify social cards setup on Windows
+| :material-close:{ style="color: #EF5350" } __Unclear__ | Missing information in the docs
+| :material-close:{ style="color: #EF5350" } __Generic__ | Please help
+
+### 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:
+
+-   __Keep it short and concise__ – if the inconsistency or issue can be 
+    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 several unrelated inconsistencies,
+    please create separate issues for them. Don't report them in the same issue – it makes attribution difficult.
+
+> __Why we need this__: in order for us to understand the problem, we need a
+> clear description of it and quantify its impact, which is essential for triage
+> and prioritization.
+
+### 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 and
+other possibly related sections. Make sure to use anchor links (permanent links) 
+where possible, as it simplifies discovery.
+
+> __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.
+
+### Proposed change <small>optional</small> { #proposed-change }
+
+Now that you have provided us with the description and links to the
+documentation sections, you can help us, maintainers, and the community by
+proposing an improvement. You can sketch out rough ideas or write a concrete
+proposal. This field is optional but very helpful.
+
+> __Why we need this__: improvement proposal can be beneficial for other users 
+> who encounter the same issue, as they offer solutions before we maintainers
+> can update the documentation.
+
+### Checklist
+
+Thanks for following the guide and creating a high-quality and complete issue 
+report – you are almost done. This section ensures that you have read this guide
+and have worked to the best of your knowledge to provide us with every piece of
+information we need to improve our documentation.
+
+__We'll take it from here.__

docs/contributing/requesting-a-change.md

@@ -0,0 +1,204 @@
+# Requesting a change
+
+Material for MkDocs is a powerful tool for creating beautiful and functional
+project documentation. With more than 20,000 users, we understand that our
+project serves a wide range of use cases, which is why we have created the
+following guide.
+
+---
+
+Put yourself in our shoes – with a project of this size, it can be challenging
+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.
+
+This guide is our best effort to explain the criteria and reasoning behind our
+decisions when evaluating change requests and considering them for
+implementation. 
+
+  [issue tracker]: https://github.com/squidfunk/mkdocs-material/issues
+
+## Before creating an issue
+
+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.__
+
+  [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
+to note that change requests are not intended for reporting bugs, as 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
+
+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
+
+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 }
+
+  [discussion board]: https://github.com/squidfunk/mkdocs-material/discussions
+  [Start a discussion]: https://github.com/squidfunk/mkdocs-material/discussions
+
+## Issue template
+
+Now that you have taken the time to do the necessary preliminary work and ensure 
+that your idea meets our requirements, you are invited to create a change
+request. The following guide will walk you through all the necessary steps to 
+help you submit a comprehensive and useful issue:
+
+- [Title]
+- [Context] <small>optional</small>
+- [Description]
+- [Related links]
+- [Use cases]
+- [Visuals] <small>optional</small>
+- [Checklist]
+
+  [Title]: #title
+  [Context]: #context
+  [Description]: #description
+  [Related links]: #related-links
+  [Use cases]: #use-cases
+  [Visuals]: #visuals
+  [Checklist]: #checklist
+
+### 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 
+be inferred from the title.
+
+| <!-- --> | Example  |
+| -------- | -------- | 
+| :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
+
+### Context <small>optional</small> { #context }
+
+Before describing your idea, you can provide additional context for us to
+understand what you are trying to achieve. Explain the circumstances
+in which you're using Material for MkDocs, and what you _think_ might be
+relevant. Don't write about the change request here.
+
+> __Why this might be helpful__: some ideas might only benefit specific
+> settings, environments, or edge cases, for example, when your documentation
+> contains thousands of documents. With a little context, change requests
+> can be prioritized more accurately.
+
+### Description
+
+Next, provide a detailed and clear description of your idea. Explain why your 
+idea is relevant to Material for MkDocs and must be implemented here, and not
+in one of its dependencies:[^1]
+
+  [^1]:
+    Sometimes, users suggest ideas on our [issue tracker] that concern one of
+    our upstream dependencies, including [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.
+    Focus on describing the proposed change request as precisely as possible.
+
+-   __Keep it short and concise__ – be brief and to the point when describing 
+    your idea, there is no need to over-describe it. Maintainers and future
+    users will be grateful for having to read less.
+
+-   __One idea at a time__ – if you have multiple ideas that don't belong 
+together, please open separate change requests for each of those ideas.
+
+---
+
+:material-run-fast: __Stretch goal__ – if you have a customization or another
+way to add the proposed change, you can help other users by sharing it here
+before we maintainers can add it to our code base.
+
+> __Why we need this__: To understand and evaluate your proposed change, we
+> need to have a clear understanding of your idea. By providing a detailed and 
+> precise description, you can help save you and us time spent discussing
+> further clarification of your idea in the comments.
+
+  [MkDocs]: https://www.mkdocs.org
+  [Python Markdown]: https://python-markdown.github.io/extensions/
+  [Python Markdown Extensions]: https://facelessuser.github.io/pymdown-extensions/
+  [theme.name]: https://www.mkdocs.org/user-guide/configuration/#theme
+
+### Related links
+
+Please provide any relevant links to issues, discussions, or documentation 
+sections related to your change request. If you (or someone else) already
+discussed this idea with the community on our discussion board, please include 
+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.
+
+### Use cases
+
+Explain how your change request would work from an author's and user's
+perspective – what's the expected impact, and why does it benefit not only you
+but other users? How many of them? Furthermore, would it potentially break
+existing functionality?
+
+> __Why we need this__: Understanding the use cases and benefits of an idea is 
+> crucial in evaluating its potential impact and usefulness for the project and 
+> its users. This information helps us to understand the expected value of the 
+> idea and how it aligns with the goals of the project.
+
+### Visuals <small>optional</small> { #visuals }
+
+We now have a clear and detailed description of your idea, including information 
+on its potential use cases and relevant links for context. If you have any 
+visuals, such as sketches, screenshots, mockups, or external assets, you may 
+present them in this section.
+
+__You can drag and drop the files here or include links to external assets.__
+
+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 
+> better understand and envision your idea. Screenshots, sketches, or mockups 
+> can create an additional level of detail and clarity that text alone may not 
+> be able to convey. Also, seeing how your idea has been implemented in other 
+> projects can help us understand its potential impact and feasibility in 
+> Material for MkDocs, which helps us maintainers evaluate and triage 
+> change requests.
+
+### Checklist
+
+Thanks for following the change request guide and creating a high-quality 
+change request. This section ensures that you have read this guide and have
+worked to the best of your knowledge to provide us with every piece of 
+information to review your idea for Material for MkDocs.
+
+__We'll take it from here.__

docs/creating-your-site.md

@@ -1,7 +1,3 @@
----
-template: overrides/main.html
----
-
 # Creating your site
 
 After you've [installed] Material for MkDocs, you can bootstrap your project 
@@ -28,7 +24,7 @@ Alternatively, if you're running Material for MkDocs from within Docker, use:
 
 This will create the following structure:
 
-```
+``` { .sh .no-copy }
 .
 ├─ docs/
 │  └─ index.md
@@ -41,56 +37,14 @@ This will create the following structure:
 
 ### Minimal configuration
 
-Simply add the following lines to `mkdocs.yml` to enable the theme. Note that
-since there are several [installation methods], minimal configuration might be
-slightly different:
+Simply add the following lines to `mkdocs.yml` to enable the theme:
 
-=== ":fontawesome-brands-python: pip"
-
-    ``` yaml
-    theme:
-      name: material
-    ```
-
-=== ":fontawesome-brands-docker: docker"
-
-    ``` yaml
-    theme:
-      name: material
-    ```
-
-=== ":fontawesome-brands-git-alt: git"
-
-    ``` yaml
-    theme:
-      name: null
-      custom_dir: mkdocs-material/material
-
-      # 404 page
-      static_templates:
-        - 404.html
-
-      # Necessary for search to work properly
-      include_search_page: false
-      search_index_only: true
-
-      # Default values, taken from mkdocs_theme.yml
-      language: en
-      font:
-        text: Roboto
-        code: Roboto Mono
-      favicon: assets/favicon.png
-      icon:
-        logo: logo
-    ```
-
-    When you clone from GitHub, you must list all of the themes' defaults
-    explicitly, because [`mkdocs_theme.yml`][mkdocs_theme.yml] is not
-    loaded automatically as described in the [custom theme guide].
+``` yaml
+theme:
+  name: material
+```
 
   [installation methods]: getting-started.md#installation
-  [mkdocs_theme.yml]: https://github.com/squidfunk/mkdocs-material/blob/master/src/mkdocs_theme.yml
-  [custom theme guide]: https://www.mkdocs.org/user-guide/custom-themes/#creating-a-custom-theme
 
 ???+ tip "Recommended: [configuration validation and auto-complete]"
 
@@ -108,10 +62,20 @@ slightly different:
             {
               "yaml.schemas": {
                 "https://squidfunk.github.io/mkdocs-material/schema.json": "mkdocs.yml"
-              }
+              },
+              "yaml.customTags": [ // (1)!
+                "!ENV scalar",
+                "!ENV sequence",
+                "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"
+              ]
             }
             ```
 
+            1.  This setting is necessary if you plan to use [icons and emojis],
+                or Visual Studio Code will show errors on certain lines.
+
     === "Other"
 
         1.  Ensure your editor of choice has support for YAML schema validation.
@@ -135,6 +99,7 @@ slightly different:
   [extension]: https://github.com/squidfunk/mkdocs-material/tree/master/docs/schema/extensions
   [plugin]: https://github.com/squidfunk/mkdocs-material/tree/master/docs/schema/plugins
   [$ref]: https://json-schema.org/understanding-json-schema/structuring.html#ref
+  [icons and emojis]: reference/icons-emojis.md
 
 ### Advanced configuration
 
@@ -153,18 +118,20 @@ and much more:
 - [Setting up site search]
 - [Setting up site analytics]
 - [Setting up social cards]
+- [Setting up a blog]
 - [Setting up tags]
 - [Setting up versioning]
 - [Setting up the header]
 - [Setting up the footer]
 - [Adding a git repository]
 - [Adding a comment system]
+- [Building an optimized site]
 - [Building for offline usage]
 
 </div>
 
 Furthermore, see the list of supported [Markdown extensions] that are natively
-integrated with Material for MkDocs, delivering a low-effort and unprecedented 
+integrated with Material for MkDocs, delivering an unprecedented low-effort
 technical writing experience.
 
   [Changing the colors]: setup/changing-the-colors.md
@@ -176,6 +143,7 @@ technical writing experience.
   [Setting up site search]: setup/setting-up-site-search.md
   [Setting up site analytics]: setup/setting-up-site-analytics.md
   [Setting up social cards]: setup/setting-up-social-cards.md
+  [Setting up a blog]: setup/setting-up-a-blog.md
   [Setting up tags]: setup/setting-up-tags.md
   [Setting up versioning]: setup/setting-up-versioning.md
   [Setting up the header]: setup/setting-up-the-header.md
@@ -183,6 +151,7 @@ technical writing experience.
   [Adding a git repository]: setup/adding-a-git-repository.md
   [Adding a comment system]: setup/adding-a-comment-system.md
   [Building for offline usage]: setup/building-for-offline-usage.md
+  [Building an optimized site]: setup/building-an-optimized-site.md
   [Markdown extensions]: setup/extensions/index.md
 
 ## Previewing as you write
@@ -254,5 +223,12 @@ need for operating a database or server, as it is completely self-contained.
 The site can be hosted on [GitHub Pages], [GitLab Pages], a CDN of your choice
 or your private web space.
 
+!!! note "Enterprise support"
+
+    If you're using Material for MkDocs in your organization and need
+    assistance, e.g., to __reduce build times__, __improve performance__ or
+    ensure compliance, [__get in touch__](mailto:contact@squidfunk.com)
+    to discuss our __enterprise support__ offerings. We're happy to help!
+
   [GitHub Pages]: publishing-your-site.md#github-pages
   [GitLab pages]: publishing-your-site.md#gitlab-pages

docs/customization.md

@@ -1,7 +1,3 @@
----
-template: overrides/main.html
----
-
 # Customization
 
 Project documentation is as diverse as the projects themselves and Material for
@@ -23,7 +19,7 @@ If you want to tweak some colors or change the spacing of certain elements,
 you can do this in a separate style sheet. The easiest way is by creating a
 new style sheet file in the `docs` directory:
 
-``` sh
+``` { .sh .no-copy }
 .
 ├─ docs/
 │  └─ stylesheets/
@@ -43,7 +39,7 @@ extra_css:
 If you want to integrate another syntax highlighter or add some custom logic to
 your theme, create a new JavaScript file in the `docs` directory:
 
-``` sh
+``` { .sh .no-copy }
 .
 ├─ docs/
 │  └─ javascripts/
@@ -91,7 +87,7 @@ of the original theme, as any file in the `overrides` directory will replace the
 file with the same name which is part of the original theme. Besides, further
 assets may also be put in the `overrides` directory:
 
-``` sh
+``` { .sh .no-copy }
 .
 ├─ .icons/                             # Bundled icon sets
 ├─ assets/
@@ -103,25 +99,36 @@ assets may also be put in the `overrides` directory:
 │  │  ├─ analytics/                    # Analytics integrations
 │  │  └─ analytics.html                # Analytics setup
 │  ├─ languages/                       # Translation languages
+│  ├─ actions.html                     # Actions
+│  ├─ comments.html                    # Comment system (empty by default)
+│  ├─ consent.html                     # Consent
 │  ├─ content.html                     # Page content
 │  ├─ copyright.html                   # Copyright and theme information
+│  ├─ feedback.html                    # Was this page helpful?
 │  ├─ footer.html                      # Footer bar
 │  ├─ header.html                      # Header bar
+│  ├─ icons.html                       # Custom icons
 │  ├─ language.html                    # Translation setup
 │  ├─ logo.html                        # Logo in header and sidebar
 │  ├─ nav.html                         # Main navigation
 │  ├─ nav-item.html                    # Main navigation item
-│  ├─ palette.html                     # Color palette
+│  ├─ pagination.html                  # Pagination (used for blog)
+│  ├─ post.html                        # Blog post excerpt
 │  ├─ search.html                      # Search interface
 │  ├─ social.html                      # Social links
 │  ├─ source.html                      # Repository information
 │  ├─ source-file.html                 # Source file information
 │  ├─ tabs.html                        # Tabs navigation
 │  ├─ tabs-item.html                   # Tabs navigation item
+│  ├─ tags.html                        # Tags
 │  ├─ toc.html                         # Table of contents
 │  └─ toc-item.html                    # Table of contents item
 ├─ 404.html                            # 404 error page
 ├─ base.html                           # Base template
+├─ blog.html                           # Blog index page
+├─ blog-archive.html                   # Blog archive index page
+├─ blog-category.html                  # Blog category index page
+├─ blog-post.html                      # Blog post page
 └─ main.html                           # Default page
 ```
 
@@ -135,7 +142,7 @@ and location in the `overrides` directory. For example, to replace the original
 `footer.html` partial, create a new `footer.html` partial in the `overrides`
 directory:
 
-``` sh
+``` { .sh .no-copy }
 .
 ├─ overrides/
 │  └─ partials/
@@ -153,7 +160,7 @@ template blocks, which are defined inside the templates and wrap specific
 features. In order to set up block overrides, create a `main.html` file inside
 the `overrides` directory:
 
-``` sh
+``` { .sh .no-copy }
 .
 ├─ overrides/
 │  └─ main.html
@@ -170,6 +177,21 @@ Then, e.g. to override the site title, add the following lines to `main.html`:
 {% endblock %}
 ```
 
+If you intend to __add__ something to a block rather than to replace it
+altogether with new content, use `{{ super() }}` inside the block to include the 
+original block content. This is particularly useful when adding third-party
+scripts to your docs, e.g.
+
+``` html
+{% extends "base.html" %}
+
+{% block scripts %}
+  <!-- Add scripts that need to run before here -->
+  {{ super() }}
+  <!-- Add scripts that need to run afterwards here -->
+{% endblock %}
+```
+
 The following template blocks are provided by the theme:
 
 | Block name        | Purpose                                         |
@@ -177,6 +199,7 @@ The following template blocks are provided by the theme:
 | `analytics`       | Wraps the Google Analytics integration          |
 | `announce`        | Wraps the announcement bar                      |
 | `config`          | Wraps the JavaScript application config         |
+| `container`       | Wraps the main content container                |
 | `content`         | Wraps the main content                          |
 | `extrahead`       | Empty block to add custom meta tags             |
 | `fonts`           | Wraps the font definitions                      |
@@ -280,3 +303,10 @@ This triggers the production-level compilation and minification of all style
 sheets and JavaScript files. After the command exits, the compiled files are
 located in the `material` directory. When running `mkdocs build`, you should
 now see your changes to the original theme.
+
+!!! note "Enterprise support"
+
+    If you're using Material for MkDocs in your organization and need
+    assistance, e.g., to __reduce build times__, __improve performance__ or
+    ensure compliance, [__get in touch__](mailto:contact@squidfunk.com)
+    to discuss our __enterprise support__ offerings. We're happy to help!

docs/faq/sponsoring.md

@@ -0,0 +1,470 @@
+# 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 is my sponsorship contribution used to support the project?__](#sponsorship-support){ #sponsorship-support }
+
+Your sponsorship contribution directly supports the development and 
+maintenance of the project, by buying us maintainers time. It allows us to
+dedicate more time and resources to enhance the project's features and
+functionality. The additional funding helps us prioritize improvements and
+updates, benefiting Insiders users and the wider community. We also actively
+contribute to other upstream projects, fostering collaboration and giving
+back to the Open Source ecosystem.
+
+[__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, 
+ou 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 features in Insiders that non-Insiders users can't properly 
+preview are [Annotations] and [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
+  [Annotations]: ../reference/annotations.md?h=anno#annotations
+  [Card grids]: ../reference/grids.md?h=grids#using-card-grids
+
+
+## Support	
+
+[__How can I contact support if I have questions about becoming a sponsor?__ ](#support-contact){ #support-contact }
+
+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,13 +1,9 @@
----
-template: overrides/main.html
----
-
 # Getting started
 
 Material for MkDocs is a theme for [MkDocs], a static site generator geared
 towards (technical) project documentation. If you're familiar with Python, you
 can install Material for MkDocs with [`pip`][pip], the Python package manager.
-If not, we recommended using [`docker`][docker].
+If not, we recommend using [`docker`][docker].
 
   [MkDocs]: https://www.mkdocs.org
   [pip]: #with-pip
@@ -18,8 +14,8 @@ If not, we recommended using [`docker`][docker].
 ### with pip <small>recommended</small> { #with-pip data-toc-label="with pip" }
 
 Material for MkDocs is published as a [Python package] and can be installed with
-`pip`, ideally by using a [virtual environment]. If not, scroll down and expand
-the help box. Install with:
+`pip`, ideally by using a [virtual environment]. Open up a terminal and install
+Material for MkDocs with:
 
 === "Latest"
 
@@ -27,17 +23,17 @@ the help box. Install with:
     pip install mkdocs-material
     ```
 
-=== "8.x"
+=== "9.x"
 
     ``` sh
-    pip install mkdocs-material=="8.*" # (1)!
+    pip install mkdocs-material=="9.*" # (1)!
     ```
 
     1.  Material for MkDocs uses [semantic versioning][^1], 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
-        major version], which may include breaking changes that silently break
+        major version], which may include breaking changes that silently corrupt
         your site. Additionally, you can use `pip freeze` to create a lockfile,
         so builds are reproducible at all times:
 
@@ -63,6 +59,15 @@ 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 
+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
+
+---
+
 __Tip__: If you don't have prior experience with Python, we recommend reading 
 [Using Python's pip to Manage Your Projects' Dependencies], which is a really
 good introduction on the mechanics of Python package management and helps you
@@ -80,8 +85,8 @@ troubleshoot if you run into errors.
 ### with docker
 
 The official [Docker image] is a great way to get up and running in a few
-minutes, as it comes with all dependencies pre-installed. Pull the image for the 
-`latest` version with:
+minutes, as it comes with all dependencies pre-installed. Open up a terminal
+and pull the image with:
 
 === "Latest"
 
@@ -89,10 +94,10 @@ minutes, as it comes with all dependencies pre-installed. Pull the image for the
     docker pull squidfunk/mkdocs-material
     ```
 
-=== "8.x"
+=== "9.x"
 
     ```
-    docker pull squidfunk/mkdocs-material:8
+    docker pull squidfunk/mkdocs-material:9
     ```
 
 The `mkdocs` executable is provided as an entry point and `serve` is the 
@@ -112,11 +117,12 @@ 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:
+    create a `user-requirements.txt` file in the repository root with the packages
+    you want to install additionally, e.g.:
 
-    ``` Dockerfile
-    FROM squidfunk/mkdocs-material
-    RUN pip install ...
+    ``` txt title="user-requirements.txt"
+    mkdocs-macros-plugin==0.7.0
+    mkdocs-glightbox>=0.3.1
     ```
 
     Next, you can build the image with the following command:
@@ -125,20 +131,8 @@ The following plugins are bundled with the Docker image:
     docker build -t squidfunk/mkdocs-material .
     ```
 
-    The new image can be used exactly like the official image.
-
-!!! info ":material-apple: Apple Silicon (M1) and :fontawesome-brands-raspberry-pi: Raspberry Pi"
-
-    The official Docker image is only available for `linux/amd64`. We recommend
-    the [third-party image] by @afritzler if you want to run Material for MkDocs
-    via Docker on `arm64` or `armv7`, as it is automatically built on every
-    release:
-
-    ```
-    docker pull ghcr.io/afritzler/mkdocs-material
-    ```
-
-  [third-party image]: https://github.com/afritzler/mkdocs-material
+    The new image will have additional packages installed and can be used
+    exactly like the official image.
 
 ### with git
 
@@ -150,11 +144,18 @@ 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`. When cloning
-from `git`, you must install all required dependencies yourself:
+The theme will reside in the folder `mkdocs-material/material`. After cloning
+from `git`, you must install all required dependencies with:
 
 ```
 pip install -e mkdocs-material
 ```
 
+!!! note "Enterprise support"
+
+    If you're using Material for MkDocs in your organization and need
+    assistance, e.g., to __reduce build times__, __improve performance__ or
+    ensure compliance, [__get in touch__](mailto:contact@squidfunk.com)
+    to discuss our __enterprise support__ offerings. We're happy to help!
+
   [GitHub]: https://github.com/squidfunk/mkdocs-material