Merge branch 'master' into docs/math

docs/changelog/index.md

@@ -2,6 +2,38 @@
 
 ## Material for MkDocs
 
+### 9.1.14 <small>May 20, 2023</small> { id="9.1.14" }
+
+- Updated Armenian and Greek translations
+
+### 9.1.13 <small>May 16, 2023</small> { id="9.1.13" }
+
+- Fixed #5517: Social plugin crashes for some fonts (e.g. Open Sans)
+
+### 9.1.12 <small>May 12, 2023</small> { id="9.1.12" }
+
+- Updated Bengali (Bangla) translations
+- Fixed #5503: Docker image publish errors on uppercase characters
+- Fixed #5407: Auto-pause media when in hidden content tabs
+
+### 9.1.11 <small>May 8, 2023</small> { id="9.1.11" }
+
+- Fixed #5487: Social plugin crashes without options (9.1.10 regression)
+
+### 9.1.10 <small>May 8, 2023</small> { id="9.1.10" }
+
+- Added `cards_layout_options` setting for social cards
+- Deprecated `cards_color` and `cards_font` setting for social cards
+
+### 9.1.9 <small>May 2, 2023</small> { id="9.1.9" }
+
+- Added Telugu, Kannada and Sanskrit translations
+- Fixed #5428: Fixed margins for light/dark mode images in figures
+- Fixed #5420: Social plugin crashing for some specific Google Fonts
+- Fixed #5160: Instant loading makes code annotations jump (9.1.1 regression)
+- Fixed #4920: Social plugin not loading logo from custom icon set
+- Fixed social plugin crashing when only code font is specified
+
 ### 9.1.8 <small>April 24, 2023</small> { id="9.1.8" }
 
 - Fixed #5417: Theme breaks when `palette` is not defined (9.1.7 regression)

docs/getting-started.md

@@ -61,8 +61,8 @@ install those packages separately.
 
 :fontawesome-brands-youtube:{ style="color: #EE0F0F" }
 __[How to set up Material for MkDocs]__ by @james-willett – :octicons-clock-24:
-15m – Learn how to create and host a documentation site using Material for Docs
-on GitHub Pages in a step-by-step guide.
+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
 

docs/insiders/changelog.md

@@ -2,6 +2,53 @@
 
 ## Material for MkDocs Insiders
 
+### 4.35.1 <small>May 20, 2023</small> { id="4.35.1" }
+
+- Fixed internal handling of errors in social plugin
+
+### 4.35.0 <small>May 20, 2023</small> { id="4.35.0" }
+
+- Improve editing experience and stability of social plugin
+- Added support for custom layout syntax validation in social plugin
+- Added support for layer origin for easier placement in social plugin
+- Added support for in- and exclusion patterns in social plugin
+- Catch and print syntax errors in custom layouts
+
+### 4.34.1 <small>May 16, 2023</small> { id="4.34.1" }
+
+- Disable social plugin debug mode by default on mkdocs build
+- Added warning in social plugin debug mode when font style couldn't be found
+- Set default concurrency of built-in multi-threaded plugins to CPUs - 1
+- Fixed #5521: Social plugin triggers race condition when downloading fonts
+- Fixed #5515: Social plugin crashes when concurrency is set to 1
+
+### 4.34.0 <small>May 14, 2023</small> { id="4.34.0" }
+
+- Added support for new overflow mode to auto-fit text in social plugin
+- Reduced subtle rendering bugs in (code) annotations due to subpixel rounding
+- Improved print styles for (code) annotation lists
+- Improved performance of social plugin, now 3x as fast
+- Improved interop of typeset plugin with MkDocstrings
+- Fixed logo location for variants of default template in social plugin
+- Fixed #5446: Built-in typeset plugin picks up headings in code blocks
+
+### 4.33.2 <small>May 12, 2023</small> { id="4.33.2" }
+
+- Fixed #5508: Social plugin crashes trying to copy cards on Docker/Windows
+- Fixed #5507: Social plugin crashes on serve when layouts folder doesn't exist
+- Fixed #5505: Social plugin trying to resolve logo in wrong location
+- Fixed #5496: Annotations with nested lists incorrectly mounted
+- Fixed #5493: Social plugin crashes on Python 3.8
+
+### 4.33.1 <small>May 9, 2023</small> { id="4.33.1" }
+
+- Added support for SVG background images in social plugin
+
+### 4.33.0 <small>May 8, 2023</small> { id="4.33.0" }
+
+- Added support for custom layouts for social plugin
+- Added support for background images for social cards
+
 ### 4.32.6 <small>April 22, 2023</small> { id="4.32.6" }
 
 - Fixed #5336: Interplay of blog plugin with git-revision-date-localized

docs/insiders/index.md

@@ -88,14 +88,16 @@ a handful of them, [thanks to our awesome sponsors]!
 ## What's in it for me?
 
 The moment you [become a sponsor][how to become a sponsor], you'll get __immediate
-access to 25 additional features__ that you can start using right away, and
+access to 27 additional features__ that you can start using right away, and
 which are currently exclusively available to sponsors:
 
 <div class="mdx-columns" markdown>
 
+- [x] [Social plugin: custom layouts] :material-alert-decagram:{ .mdx-pulse title="Added on May 8, 2023" }
+- [x] [Social plugin: background images] :material-alert-decagram:{ .mdx-pulse title="Added on May 8, 2023" }
 - [x] [Code range selection] :material-alert-decagram:{ .mdx-pulse title="Added on February 19, 2023" }
-- [x] [Code annotations: custom selectors] :material-alert-decagram:{ .mdx-pulse title="Added on February 19, 2023" }
-- [x] [Privacy plugin: optimization support] :material-alert-decagram:{ .mdx-pulse title="Added on February 6, 2023" }
+- [x] [Code annotations: custom selectors]
+- [x] [Privacy plugin: optimization support]
 - [x] [Optimize plugin]
 - [x] [Navigation path] (Breadcrumbs)
 - [x] [Typeset plugin]
@@ -256,10 +258,6 @@ features prefixed with a checkmark symbol, denoting whether a feature is
 :octicons-check-circle-fill-24:{ style="color: var(--md-default-fg-color--lightest)" } planned, but not yet implemented. When the funding goal is hit, the features
 are released for general availability.
 
-> [In February, we lost $1,3k in monthly funding because GitHub removed PayPal support][Twitter]
-
-  [Twitter]: https://twitter.com/squidfunk/status/1643539228574269443
-
 #### $ 12,000 – Piri Piri
 
 - [x] [Blog plugin]
@@ -320,17 +318,21 @@ are released for general availability.
 
   [Optimize plugin]: ../setup/building-an-optimized-site.md#built-in-optimize-plugin
   [Typeset plugin]: ../reference/index.md#built-in-typeset-plugin
-  [Privacy plugin: external links]: ../setup/ensuring-data-privacy.md#+privacy.external_links
-  [Privacy plugin: optimization support]: ../setup/ensuring-data-privacy.md#+privacy.external_assets_include
+  [Privacy plugin: external links]: ../setup/ensuring-data-privacy.md#+privacy.links
+  [Privacy plugin: optimization support]: ../setup/ensuring-data-privacy.md#+privacy.assets_include
   [Navigation path]: ../setup/setting-up-navigation.md#navigation-path
   [Instant previews]: https://twitter.com/squidfunk/status/1466794654213492743
 
 #### $ 24,000 – Blockpaprika
 
+- [x] [Social plugin: custom layouts]
+- [x] [Social plugin: background images]
 - [x] [Code range selection]
 - [x] [Code annotations: custom selectors]
 - [ ] Code line wrap button
 
+  [Social plugin: custom layouts]: ../setup/setting-up-social-cards.md#customization
+  [Social plugin: background images]: ../setup/setting-up-social-cards.md#+social.cards_layout_params.background_image
   [Code range selection]: ../reference/code-blocks.md#code-selection-button
   [Code annotations: custom selectors]: ../reference/code-blocks.md#custom-selectors
 

docs/publishing-your-site.md

@@ -38,11 +38,14 @@ contents:
           - uses: actions/setup-python@v4
             with:
               python-version: 3.x
-          - uses: actions/cache@v2
+          - run: echo "cache_id=$(date --utc '+%V')" >> $GITHUB_ENV # (3)!
+          - uses: actions/cache@v3
             with:
-              key: ${{ github.ref }}
+              key: mkdocs-material-${{ env.cache_id }}
               path: .cache
-          - run: pip install mkdocs-material # (3)!
+              restore-keys: |
+                mkdocs-material-
+          - run: pip install mkdocs-material # (4)!
           - run: mkdocs gh-deploy --force
     ```
 
@@ -51,7 +54,16 @@ contents:
     2.  At some point, GitHub renamed `master` to `main`. If your default branch
         is named `master`, you can safely remove `main`, vice versa.
 
-    3.  This is the place to install further [MkDocs plugins] or Markdown
+    3.  Store the `cache_id` environmental variable to access it later during cache
+        `key` creation. The name is case-sensitive, so be sure to align it with `${{ env.cache_id }}`.
+
+        - The `--utc` option makes sure that each workflow runner uses the same time zone.
+        - The `%V` format assures a cache update once a week. 
+        - You can change the format to `%F` to have daily cache updates. 
+
+        You can read the [manual page] to learn more about the formatting options of the `date` command.
+
+    4.  This is the place to install further [MkDocs plugins] or Markdown
         extensions with `pip` to be used during the build:
 
         ``` sh
@@ -81,10 +93,13 @@ contents:
           - uses: actions/setup-python@v4
             with:
               python-version: 3.x
-          - uses: actions/cache@v2
+          - run: echo "cache_id=$(date --utc '+%V')" >> $GITHUB_ENV
+          - uses: actions/cache@v3
             with:
-              key: ${{ github.ref }}
+              key: mkdocs-material-${{ env.cache_id }}
               path: .cache
+              restore-keys: |
+                mkdocs-material-
           - run: apt-get install pngquant # (1)!
           - run: pip install git+https://${GH_TOKEN}@github.com/squidfunk/mkdocs-material-insiders.git
           - run: mkdocs gh-deploy --force
@@ -116,6 +131,7 @@ Your documentation should shortly appear at `<username>.github.io/<repository>`.
   [built-in optimize plugin]: setup/building-an-optimized-site.md#built-in-optimize-plugin
   [GitHub secrets]: https://docs.github.com/en/actions/configuring-and-managing-workflows/creating-and-storing-encrypted-secrets
   [publishing source branch]: https://docs.github.com/en/pages/getting-started-with-github-pages/configuring-a-publishing-source-for-your-github-pages-site
+  [manual page]: https://man7.org/linux/man-pages/man1/date.1.html
 
 ### with MkDocs
 

docs/reference/images.md

@@ -172,7 +172,37 @@ hash fragment to the image URL:
 
 </div>
 
+!!! warning "Requirements when using [custom color schemes]"
+
+    The built-in [color schemes] define the aforementioned hash fragments, but
+    if you're using [custom color schemes], you'll also have to add the
+    following selectors to your scheme, depending on whether it's a light or
+    dark scheme:
+
+    === "Custom light scheme"
+
+        ``` css
+        [data-md-color-scheme="custom-light"] img[src$="#only-dark"]
+        [data-md-color-scheme="custom-light"] img[src$="#gh-dark-mode-only"] {
+          display: none; /* Hide dark images in light mode */
+        }
+        ```
+
+    === "Custom dark scheme"
+
+        ``` css
+        [data-md-color-scheme="custom-dark"] img[src$="#only-light"],
+        [data-md-color-scheme="custom-dark"] img[src$="#gh-light-mode-only"] {
+          display: none; /* Hide light images in dark mode */
+        }
+        ```
+
+    Remember to change `#!css "custom-light"` and `#!css "custom-dark"` to the
+    name of your scheme.
+
   [Light and dark mode support]: https://github.com/squidfunk/mkdocs-material/releases/tag/8.1.1
   [color palette toggle]: ../setup/changing-the-colors.md#color-palette-toggle
   [Zelda light world]: ../assets/images/zelda-light-world.png#only-light
   [Zelda dark world]: ../assets/images/zelda-dark-world.png#only-dark
+  [color schemes]: ../setup/changing-the-colors.md#color-scheme
+  [custom color schemes]: ../setup/changing-the-colors.md#custom-color-schemes

docs/schema/assets/icons.json

@@ -9470,6 +9470,8 @@
     "octicons/device-desktop-24",
     "octicons/device-mobile-16",
     "octicons/device-mobile-24",
+    "octicons/devices-16",
+    "octicons/devices-24",
     "octicons/diamond-16",
     "octicons/diamond-24",
     "octicons/diff-16",
@@ -9707,6 +9709,8 @@
     "octicons/person-fill-24",
     "octicons/pin-16",
     "octicons/pin-24",
+    "octicons/pin-slash-16",
+    "octicons/pin-slash-24",
     "octicons/play-16",
     "octicons/play-24",
     "octicons/plug-16",
@@ -9884,6 +9888,7 @@
     "octicons/webhook-16",
     "octicons/workflow-16",
     "octicons/workflow-24",
+    "octicons/x-12",
     "octicons/x-16",
     "octicons/x-24",
     "octicons/x-circle-16",
@@ -9947,6 +9952,7 @@
     "simple/aeromexico",
     "simple/aerospike",
     "simple/aew",
+    "simple/affine",
     "simple/affinity",
     "simple/affinitydesigner",
     "simple/affinityphoto",
@@ -10078,6 +10084,7 @@
     "simple/aqua",
     "simple/aral",
     "simple/arangodb",
+    "simple/arcgis",
     "simple/archicad",
     "simple/archiveofourown",
     "simple/archlinux",
@@ -10164,6 +10171,7 @@
     "simple/beijingsubway",
     "simple/bem",
     "simple/bentley",
+    "simple/bento",
     "simple/betfair",
     "simple/bigbasket",
     "simple/bigbluebutton",
@@ -10250,6 +10258,7 @@
     "simple/canonical",
     "simple/canva",
     "simple/capacitor",
+    "simple/cardano",
     "simple/carrefour",
     "simple/carthrottle",
     "simple/carto",
@@ -10366,6 +10375,7 @@
     "simple/consul",
     "simple/contactlesspayment",
     "simple/containerd",
+    "simple/contao",
     "simple/contentful",
     "simple/conventionalcommits",
     "simple/convertio",
@@ -10570,6 +10580,7 @@
     "simple/eslint",
     "simple/esphome",
     "simple/espressif",
+    "simple/esri",
     "simple/etcd",
     "simple/ethereum",
     "simple/ethiopianairlines",
@@ -11255,6 +11266,7 @@
     "simple/monero",
     "simple/moneygram",
     "simple/mongodb",
+    "simple/mongoose",
     "simple/monica",
     "simple/monkeytie",
     "simple/monogames",
@@ -11557,6 +11569,7 @@
     "simple/prezi",
     "simple/prime",
     "simple/primevideo",
+    "simple/printables",
     "simple/prisma",
     "simple/prismic",
     "simple/privateinternetaccess",
@@ -11701,6 +11714,7 @@
     "simple/riseup",
     "simple/roamresearch",
     "simple/roblox",
+    "simple/robloxstudio",
     "simple/robotframework",
     "simple/rocketdotchat",
     "simple/rocksdb",
@@ -11728,6 +11742,7 @@
     "simple/rubygems",
     "simple/rubyonrails",
     "simple/rubysinatra",
+    "simple/ruff",
     "simple/runkeeper",
     "simple/runkit",
     "simple/rust",
@@ -12335,6 +12350,7 @@
     "simple/zhihu",
     "simple/zig",
     "simple/zigbee",
+    "simple/zilch",
     "simple/zillow",
     "simple/zincsearch",
     "simple/zingat",

docs/schema/plugins/privacy.json

@@ -24,62 +24,60 @@
             "concurrency": {
               "title": "Concurrency (number of CPUs)",
               "markdownDescription": "https://squidfunk.github.io/mkdocs-material/setup/ensuring-data-privacy/#+privacy.concurrency",
-              "type": "number"
+              "type": "number",
+              "default": 1
             },
-            "external_assets": {
-              "title": "External assets",
-              "markdownDescription": "https://squidfunk.github.io/mkdocs-material/setup/ensuring-data-privacy/#+privacy.external_assets",
-              "oneOf": [
-                {
-                  "title": "Bundle external assets",
-                  "enum": ["bundle"]
-                },
-                {
-                  "title": "Report external assets as warnings",
-                  "enum": ["report"]
-                }
-              ],
-              "default": "bundle"
-            },
-            "external_assets_dir": {
-              "title": "External assets download directory",
-              "markdownDescription": "https://squidfunk.github.io/mkdocs-material/setup/ensuring-data-privacy/#+privacy.external_assets_dir",
-              "type": "string",
-              "default": "assets/external"
-            },
-            "external_assets_include": {
-              "title": "External assets to include",
-              "markdownDescription": "https://squidfunk.github.io/mkdocs-material/setup/ensuring-data-privacy/#+privacy.external_assets_include",
-              "type": "array",
-              "items": {
-                "title": "External assets matching this pattern will be downloaded",
-                "markdownDescription": "https://squidfunk.github.io/mkdocs-material/setup/ensuring-data-privacy/#+privacy.external_assets_include",
-                "pattern": ".*"
-              },
-              "uniqueItems": true,
-              "minItems": 1
-            },
-            "external_assets_exclude": {
-              "title": "External assets to exclude",
-              "markdownDescription": "https://squidfunk.github.io/mkdocs-material/setup/ensuring-data-privacy/#+privacy.external_assets_exclude",
-              "type": "array",
-              "items": {
-                "title": "External assets matching this pattern will not be downloaded",
-                "markdownDescription": "https://squidfunk.github.io/mkdocs-material/setup/ensuring-data-privacy/#+privacy.external_assets_exclude",
-                "pattern": ".*"
-              },
-              "uniqueItems": true,
-              "minItems": 1
-            },
-            "external_links": {
-              "title": "External links",
-              "markdownDescription": "https://squidfunk.github.io/mkdocs-material/setup/ensuring-data-privacy/#+privacy.external_links",
+            "assets": {
+              "title": "Process external assets",
+              "markdownDescription": "https://squidfunk.github.io/mkdocs-material/setup/ensuring-data-privacy/#+privacy.assets",
               "type": "boolean",
               "default": true
             },
-            "external_links_attr_map": {
+            "assets_fetch": {
+              "title": "Download external assets",
+              "markdownDescription": "https://squidfunk.github.io/mkdocs-material/setup/ensuring-data-privacy/#+privacy.assets_fetch",
+              "type": "boolean",
+              "default": true
+            },
+            "assets_fetch_dir": {
+              "title": "Download external assets to this directory",
+              "markdownDescription": "https://squidfunk.github.io/mkdocs-material/setup/ensuring-data-privacy/#+privacy.assets_fetch_dir",
+              "type": "string",
+              "default": "assets/external"
+            },
+            "assets_include": {
+              "title": "External assets to include",
+              "markdownDescription": "https://squidfunk.github.io/mkdocs-material/setup/ensuring-data-privacy/#+privacy.assets_include",
+              "type": "array",
+              "items": {
+                "title": "External assets matching this pattern will be downloaded",
+                "markdownDescription": "https://squidfunk.github.io/mkdocs-material/setup/ensuring-data-privacy/#+privacy.assets_include",
+                "pattern": ".*"
+              },
+              "uniqueItems": true,
+              "minItems": 1
+            },
+            "assets_exclude": {
+              "title": "External assets to exclude",
+              "markdownDescription": "https://squidfunk.github.io/mkdocs-material/setup/ensuring-data-privacy/#+privacy.assets_exclude",
+              "type": "array",
+              "items": {
+                "title": "External assets matching this pattern will not be downloaded",
+                "markdownDescription": "https://squidfunk.github.io/mkdocs-material/setup/ensuring-data-privacy/#+privacy.assets_exclude",
+                "pattern": ".*"
+              },
+              "uniqueItems": true,
+              "minItems": 1
+            },
+            "links": {
+              "title": "Process external links",
+              "markdownDescription": "https://squidfunk.github.io/mkdocs-material/setup/ensuring-data-privacy/#+privacy.links",
+              "type": "boolean",
+              "default": true
+            },
+            "links_attr_map": {
               "title": "Custom attributes to add to external links",
-              "markdownDescription": "https://squidfunk.github.io/mkdocs-material/setup/ensuring-data-privacy/#+privacy.external_links_attr_map",
+              "markdownDescription": "https://squidfunk.github.io/mkdocs-material/setup/ensuring-data-privacy/#+privacy.links_attr_map",
               "type": "object",
               "patternProperties": {
                 "^[\\w_]+$": {
@@ -87,9 +85,9 @@
                 }
               }
             },
-            "external_links_noopener": {
+            "links_noopener": {
               "title": "Behavior for external links that open in new windows",
-              "markdownDescription": "https://squidfunk.github.io/mkdocs-material/setup/ensuring-data-privacy/#+privacy.external_links_noopener",
+              "markdownDescription": "https://squidfunk.github.io/mkdocs-material/setup/ensuring-data-privacy/#+privacy.links_noopener",
               "type": "boolean",
               "default": true
             }

docs/schema/plugins/social.json

@@ -15,51 +15,120 @@
           "markdownDescription": "https://squidfunk.github.io/mkdocs-material/setup/setting-up-social-cards/#built-in-social-plugin",
           "type": "object",
           "properties": {
+            "enabled": {
+              "title": "Enable plugin",
+              "markdownDescription": "https://squidfunk.github.io/mkdocs-material/setup/setting-up-social-cards/#+social.enabled",
+              "type": "boolean",
+              "default": true
+            },
+            "concurrency": {
+              "title": "Concurrency (number of CPUs)",
+              "markdownDescription": "https://squidfunk.github.io/mkdocs-material/setup/setting-up-social-cards/#+social.concurrency",
+              "type": "number",
+              "default": 1
+            },
             "cards": {
-              "title": "Social card generation",
+              "title": "Social cards",
               "markdownDescription": "https://squidfunk.github.io/mkdocs-material/setup/setting-up-social-cards/#+social.cards",
               "type": "boolean",
               "default": true
             },
-            "cards_color": {
-              "title": "Social card color palette",
-              "markdownDescription": "https://squidfunk.github.io/mkdocs-material/setup/setting-up-social-cards/#+social.cards_color",
-              "type": "object",
-              "properties": {
-                "fill": {
-                  "title": "Background fill color",
-                  "markdownDescription": "https://squidfunk.github.io/mkdocs-material/setup/setting-up-social-cards/#+social.cards_color",
-                  "type": "string"
-                },
-                "text": {
-                  "title": "Foreground text color",
-                  "markdownDescription": "https://squidfunk.github.io/mkdocs-material/setup/setting-up-social-cards/#+social.cards_color",
-                  "type": "string"
-                }
-              },
-              "additionalProperties": false,
-              "required": [
-                "fill",
-                "text"
-              ]
-            },
-            "cards_font": {
-              "$ref": "../assets/fonts.json"
-            },
             "cards_dir": {
-              "title": "Social card directory",
+              "title": "Social cards directory",
               "markdownDescription": "https://squidfunk.github.io/mkdocs-material/setup/setting-up-social-cards/#+social.cards_dir",
               "type": "string",
               "default": "assets/images/social"
+            },
+            "cards_layout_dir": {
+              "title": "Social cards layout directory",
+              "markdownDescription": "https://squidfunk.github.io/mkdocs-material/setup/setting-up-social-cards/#+social.cards_layout_dir",
+              "type": "string",
+              "default": "layouts"
+            },
+            "cards_layout": {
+              "title": "Social cards layout",
+              "markdownDescription": "https://squidfunk.github.io/mkdocs-material/setup/setting-up-social-cards/#+social.cards_layout",
+              "default": "default",
+              "enum": [
+                "default",
+                "default/accent",
+                "default/invert",
+                "default/variant"
+              ]
+            },
+            "cards_layout_options": {
+              "title": "Social cards layout options",
+              "markdownDescription": "https://squidfunk.github.io/mkdocs-material/setup/setting-up-social-cards/#+social.cards_layout_options",
+              "type": "object"
+            },
+            "cards_include": {
+              "title": "Pages or folders to include",
+              "markdownDescription": "https://squidfunk.github.io/mkdocs-material/setup/setting-up-social-cards/#+social.cards_include",
+              "type": "array",
+              "items": {
+                "title": "Pages or folders matching this pattern will be included",
+                "markdownDescription": "https://squidfunk.github.io/mkdocs-material/setup/setting-up-social-cards/#+social.cards_include",
+                "pattern": ".*"
+              },
+              "uniqueItems": true,
+              "minItems": 1
+            },
+            "cards_exclude": {
+              "title": "Pages or folders to exclude",
+              "markdownDescription": "https://squidfunk.github.io/mkdocs-material/setup/setting-up-social-cards/#+social.cards_exclude",
+              "type": "array",
+              "items": {
+                "title": "Pages or folders matching this pattern will be excluded",
+                "markdownDescription": "https://squidfunk.github.io/mkdocs-material/setup/setting-up-social-cards/#+social.cards_exclude",
+                "pattern": ".*"
+              },
+              "uniqueItems": true,
+              "minItems": 1
+            },
+            "debug": {
+              "title": "Debug mode",
+              "markdownDescription": "https://squidfunk.github.io/mkdocs-material/setup/setting-up-social-cards/#+social.debug",
+              "type": "boolean",
+              "default": true
+            },
+            "debug_on_build": {
+              "title": "Always disable debug mode on build",
+              "markdownDescription": "https://squidfunk.github.io/mkdocs-material/setup/setting-up-social-cards/#+social.debug_on_build",
+              "type": "boolean",
+              "default": false
+            },
+            "debug_grid": {
+              "title": "Debug grid",
+              "markdownDescription": "https://squidfunk.github.io/mkdocs-material/setup/setting-up-social-cards/#+social.debug_grid",
+              "type": "boolean",
+              "default": true
+            },
+            "debug_grid_step": {
+              "title": "Debug grid step size",
+              "markdownDescription": "https://squidfunk.github.io/mkdocs-material/setup/setting-up-social-cards/#+social.debug_grid_step",
+              "type": "number",
+              "default": 32
+            },
+            "debug_color": {
+              "title": "Debug color",
+              "markdownDescription": "https://squidfunk.github.io/mkdocs-material/setup/setting-up-social-cards/#+social.debug_color",
+              "type": "string",
+              "default": "yellow"
+            },
+            "cache": {
+              "title": "Enable caching",
+              "markdownDescription": "https://squidfunk.github.io/mkdocs-material/setup/setting-up-social-cards/#+social.cache",
+              "type": "boolean",
+              "default": true
+            },
+            "cache_dir": {
+              "title": "Cache directory",
+              "markdownDescription": "https://squidfunk.github.io/mkdocs-material/setup/setting-up-social-cards/#+social.cache_dir",
+              "type": "string",
+              "default": ".cache/plugins/social"
             }
           },
-          "additionalProperties": false,
-          "defaultSnippets": [
-            {
-              "label": "cards_font",
-              "body": "cards_font: ${1:Roboto}"
-            }
-          ]
+          "additionalProperties": false
         }
       },
       "additionalProperties": false

docs/schema/theme.json

@@ -214,6 +214,12 @@
             "ka"
           ]
         },
+        {
+          "title": "Site language: Kannada",
+          "enum": [
+            "kn"
+          ]
+        },
         {
           "title": "Site language: Korean",
           "enum": [
@@ -304,6 +310,12 @@
             "ru"
           ]
         },
+        {
+          "title": "Site language: Sanskrit",
+          "enum": [
+            "sa"
+          ]
+        },
         {
           "title": "Site language: Serbo-Croatian",
           "enum": [
@@ -340,6 +352,12 @@
             "sv"
           ]
         },
+        {
+          "title": "Site language: Telugu",
+          "enum": [
+            "te"
+          ]
+        },
         {
           "title": "Site language: Thai",
           "enum": [

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

@@ -1,7 +1,3 @@
----
-status: new
----
-
 # Building an optimized site
 
 Material for MkDocs, by default, allows to build optimized sites that rank great
@@ -196,7 +192,7 @@ The following configuration options are available for caching:
     ``` yaml
     plugins:
       - optimize:
-          cache_dir: path/to/folder
+          cache_dir: .cache/plugins/optimize
     ```
 
     By default, all built-in plugins that implement caching will create a

docs/setup/changing-the-language.md

@@ -1,7 +1,7 @@
 # Changing the language
 
 Material for MkDocs supports internationalization (i18n) and provides
-translations for template variables and labels in 50+ languages. Additionally,
+translations for template variables and labels in 60+ languages. Additionally,
 the site search can be configured to use a language-specific stemmer, if
 available.
 

docs/setup/ensuring-data-privacy.md

@@ -199,28 +199,38 @@ The following configuration options are available:
 
 The following configuration options are available for external assets:
 
-[`external_assets`](#+privacy.external_assets){ #+privacy.external_assets }
+[`assets`](#+privacy.assets){ #+privacy.assets }
 
-:   :octicons-milestone-24: Default: `bundle` – This option specifies what the
-    plugin should do when encountering external assets. There are two options:
-    while `report` will issue warning messages during the build, `bundle` will
-    automatically download all external files and adjust all references:
+:   :octicons-milestone-24: Default: `true` – This option specifies whether the
+    plugin should scan the HTML output to detect and process external assets:
 
     ``` yaml
     plugins:
       - privacy:
-          external_assets: bundle
+          assets: true
     ```
 
     If you've removed all external assets from your project via [customization],
-    it's still a good idea to enable the plugin and set the mode to `report`,
-    as the plugin will make sure that there are no hidden external links in any
-    Markdown files that were unintentionally added.
+    it's still a good idea to enable the plugin, as the plugin will make sure
+    that there are no hidden external links in any Markdown files that were 
+    unintentionally added.
 
-    Using `report` in [strict mode] will make the build fail when external
+    Using `assets` in [strict mode] will make the build fail when external
     assets are detected.
 
-[`external_assets_dir`](#+privacy.external_assets_dir){ #+privacy.external_assets_dir }
+[`assets_fetch`](#+privacy.assets_fetch){ #+privacy.assets_fetch }
+
+:   :octicons-milestone-24: Default: `true` – This option specifies whether the
+    plugin should download external assets it encountered and bundle them with
+    your documentation:
+
+    ``` yaml
+    plugins:
+      - privacy:
+          assets_fetch: true
+    ```
+
+[`assets_fetch_dir`](#+privacy.assets_fetch_dir){ #+privacy.assets_fetch_dir }
 
 :   :octicons-milestone-24: Default: `assets/external` – This option
     specifies where the downloaded [external assets] will be stored. It's
@@ -229,12 +239,12 @@ The following configuration options are available for external assets:
     ``` yaml
     plugins:
       - privacy:
-          external_assets_dir: assets/external
+          assets_fetch_dir: assets/external
     ```
 
     The path must be defined relative to [`docs_dir`][docs_dir].
 
-[`external_assets_include`](#+privacy.external_assets_include){ #+privacy.external_assets_include } :material-alert-decagram:{ .mdx-pulse title="Added on February 6, 2023" }
+[`assets_include`](#+privacy.assets_include){ #+privacy.assets_include }
 
 :   :octicons-milestone-24: Default: _none_ – This option allows to only include
     certain external assets for processing by the privacy plugin, so they will
@@ -243,7 +253,7 @@ The following configuration options are available for external assets:
     ``` yaml
     plugins:
       - privacy:
-          external_assets_include:
+          assets_include:
             - unsplash.com/*
     ```
 
@@ -265,7 +275,7 @@ The following configuration options are available for external assets:
         differently from others or exclude some images from downloading, you can
         use multiple instances of the [built-in privacy plugin].
 
-[`external_assets_exclude`](#+privacy.external_assets_exclude){ #+privacy.external_assets_exclude }
+[`assets_exclude`](#+privacy.assets_exclude){ #+privacy.assets_exclude }
 
 :   :octicons-milestone-24: Default: _none_ – This option allows to exclude
     certain external assets from processing by the privacy plugin, so they will
@@ -274,7 +284,7 @@ The following configuration options are available for external assets:
     ``` yaml
     plugins:
       - privacy:
-          external_assets_exclude: # (1)!
+          assets_exclude: # (1)!
             - cdn.jsdelivr.net/npm/mathjax@3/* 
             - giscus.app/*
     ```
@@ -333,7 +343,7 @@ The following configuration options are available for external assets:
 
 The following configuration options are available for external links:
 
-[`external_links`](#+privacy.external_links){ #+privacy.external_links }
+[`links`](#+privacy.links){ #+privacy.links }
 
 :   :octicons-milestone-24: Default: `true` – This option specifies whether the
     plugin should parse and process external links. If you want to speed up
@@ -342,10 +352,10 @@ The following configuration options are available for external links:
     ``` yaml
     plugins:
       - privacy:
-          external_links: !ENV [CI, false]
+          links: !ENV [CI, false]
     ```
 
-[`external_links_attr_map`](#+privacy.external_links_attr_map){ #+privacy.external_links_attr_map }
+[`links_attr_map`](#+privacy.links_attr_map){ #+privacy.links_attr_map }
 
 :   :octicons-milestone-24: Default: _None_ – This option specifies custom
     attributes that should be added to external links, like for example
@@ -354,11 +364,11 @@ The following configuration options are available for external links:
     ``` yaml
     plugins:
       - privacy:
-          external_links_attr_map:
+          links_attr_map:
             target: _blank
     ```
 
-[`external_links_noopener`](#+privacy.external_links_noopener){ #+privacy.external_links_noopener }
+[`links_noopener`](#+privacy.links_noopener){ #+privacy.links_noopener }
 
 :   :octicons-milestone-24: Default: `true` – This option specifies whether the
     plugin should automatically add [`rel="noopener"`][noopener] to all links
@@ -367,7 +377,7 @@ The following configuration options are available for external links:
     ``` yaml
     plugins:
       - privacy:
-          external_links_noopener: true
+          links_noopener: true
     ```
 
   [noopener]: https://mathiasbynens.github.io/rel-noopener/
@@ -484,27 +494,30 @@ carried out. You might want to:
     `.cache` directory in between builds. Taking the example from the
     [publishing guide], add the following lines:
 
-    ``` yaml hl_lines="15-18"
+    ``` yaml hl_lines="15-21"
     name: ci
       on:
         push:
           branches:
             - master
             - main
-      jobs:
-        deploy:
-          runs-on: ubuntu-latest
-          steps:
-            - uses: actions/checkout@v2
-            - uses: actions/setup-python@v2
-              with:
-                python-version: 3.x
-            - uses: actions/cache@v2
-              with:
-                key: ${{ github.ref }}
-                path: .cache
-            - run: pip install mkdocs-material
-            - run: mkdocs gh-deploy --force
+    jobs:
+      deploy:
+        runs-on: ubuntu-latest
+        steps:
+          - uses: actions/checkout@v3
+          - uses: actions/setup-python@v4
+            with:
+              python-version: 3.x
+          - run: echo "cache_id=$(date --utc '+%V')" >> $GITHUB_ENV
+          - uses: actions/cache@v3
+            with:
+              key: mkdocs-material-${{ env.cache_id }}
+              path: .cache
+              restore-keys: |
+                mkdocs-material-
+          - run: pip install mkdocs-material
+          - run: mkdocs gh-deploy --force
     ```
 
   [publishing guide]: ../publishing-your-site.md#with-github-actions

docs/setup/index.md

@@ -13,7 +13,7 @@ setting up site search, and more.
 
 <div class="grid cards" markdown>
 
-- :fontawesome-solid-earth-americas: __[Language]__ – Choose out of the 50+ supported languages or add a new one
+- :fontawesome-solid-earth-americas: __[Language]__ – Choose out of the 60+ supported languages or add a new one
 - :material-page-layout-sidebar-left: __[Navigation]__ – Create a clear, concise, and comprehensive navigation structure
 - :material-page-layout-header: __[Header]__ – Customize the behavior of the header, add an announcement bar
 - :material-page-layout-footer: __[Footer]__ – Add links to your social media profiles or websites in the footer 

docs/setup/setting-up-a-blog.md

@@ -93,7 +93,7 @@ The following configuration options are available:
         ``` yaml
         plugins:
           - blog:
-              blog_dir: path/to/folder
+              blog_dir: blog
         ```
 
     === "Standalone"

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

@@ -78,13 +78,16 @@ The following configuration options are supported:
     - `hy` – Armenian
     - `it` – Italian
     - `ja` – Japanese
+    - `kn` - Kannada
     - `ko` – Korean
     - `no` – Norwegian
     - `pt` – Portuguese
     - `ro` – Romanian
     - `ru` – Russian
+    - `sa` – Sanskrit
     - `sv` – Swedish
     - `ta` – Tamil
+    - `te` – Telugu
     - `th` – Thai
     - `tr` – Turkish
     - `vi` – Vietnamese

docs/setup/setting-up-tags.md

@@ -141,7 +141,7 @@ The following configuration options are available:
     ``` yaml
     plugins:
       - tags:
-          tags_compare: !!python/name:material.plugins.tags.plugin.casefold
+          tags_compare: !!python/name:material.plugins.tags.casefold
     ```
 
     You can also define your own comparison function which must return a tag