Merge remote-tracking branch 'upstream/master'

# Conflicts:
#	src/plugins/social/plugin.py

Author: croesus

.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"
+}

.github/workflows/build.yml

@@ -29,7 +29,7 @@ on:
       - published
 
 env:
-  NODE_VERSION: 14.x
+  NODE_VERSION: 18.x
   PYTHON_VERSION: 3.x
 
 permissions:
@@ -144,9 +144,11 @@ jobs:
 
       - name: Check Docker image
         working-directory: /tmp
+        env:
+          REPO_FULL_NAME: '${{ github.event.repository.full_name }}'
         run: |
-          docker run --rm -i -v ${PWD}:/docs ${{ github.event.repository.full_name }}:${{ steps.meta.outputs.version }} new .
-          docker run --rm -i -v ${PWD}:/docs ${{ github.event.repository.full_name }}:${{ steps.meta.outputs.version }} build
+          docker run --rm -i -v ${PWD}:/docs ${REPO_FULL_NAME,,}:${{ steps.meta.outputs.version }} new .
+          docker run --rm -i -v ${PWD}:/docs ${REPO_FULL_NAME,,}:${{ steps.meta.outputs.version }} build
 
       - name: Set platforms
         if: github.event_name == 'release'

.github/workflows/documentation.yml

@@ -46,12 +46,17 @@ jobs:
         with:
           python-version: ${{ env.PYTHON_VERSION }}
 
+      - name: Set the date environmental variable
+        run: echo "cache_id=$(date --utc '+%V')" >> $GITHUB_ENV
+
       - name: Set up build cache
         uses: actions/cache@v3
         id: cache
         with:
-          key: ${{ runner.os }}-${{ hashFiles('.cache/**') }}
+          key: mkdocs-material-${{ env.cache_id }}
           path: .cache
+          restore-keys: |
+            mkdocs-material-
 
       - name: Install dependencies
         run: sudo apt-get install pngquant

.vscode/settings.json

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

CHANGELOG

@@ -1,17 +1,68 @@
+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)
+  * 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
+  * 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
+  * 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)
 

CONTRIBUTING.md

@@ -42,10 +42,10 @@ it is:
 
 ### Missing translations?
 
-Material for MkDocs supports 50+ languages with the help of community
+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 50+ languages), so we have to rely on
+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:

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">

docs/assets/screenshots/social-cards-accent.png

@@ -2,6 +2,30 @@
 
 ## Material for MkDocs
 
+### 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/assets/screenshots/social-cards-debug.png

@@ -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/assets/screenshots/social-cards-invert.png

@@ -2,6 +2,33 @@
 
 ## Material for MkDocs Insiders
 
+### 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/assets/screenshots/social-cards-layer-0.png

@@ -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/assets/screenshots/social-cards-layer-1.png

@@ -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/assets/screenshots/social-cards-layer-2.png

@@ -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