Documentation

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
+15m – Learn how to create and host a documentation site using Material for 
-on GitHub Pages in a step-by-step guide.
+MkDocs on GitHub Pages in a step-by-step guide.
 
   [How to set up Material for MkDocs]: https://www.youtube.com/watch?v=Q-YA_dA8C20
 

docs/insiders/changelog.md

@@ -2,6 +2,11 @@
 
 ## Material for MkDocs Insiders
 
+### 4.33.0 <small>April 22, 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] [Code annotations: custom selectors]
-- [x] [Privacy plugin: optimization support] :material-alert-decagram:{ .mdx-pulse title="Added on February 6, 2023" }
+- [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]
@@ -327,10 +325,14 @@ are released for general availability.
 
 #### $ 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#custom-layouts
+  [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/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/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-social-cards.md

@@ -1,36 +1,27 @@
+---
+status: new
+---
+
 # Setting up social cards
 
-Social cards, also known as social previews, are images that are displayed when
+Material for MkDocs can automatically create beautiful social cards for your 
-a link to your project documentation is shared on social media. Material for
+documentation, which appear as link previews on social media platforms. You 
-MkDocs can generate beautiful social cards automatically, using the [colors], 
+can select from a variety of [pre-designed layouts][default layouts] or create
-[fonts] and [logo][^1] defined in `mkdocs.yml`,
+[custom layouts] to match your unique style and branding.
-e.g.:
 
 <figure markdown>
 
-[![Social cards preview]][Social cards preview]
+[![Layout default variant]][Layout default variant]
 
   <figcaption markdown>
 
-The social preview image for the page on [setting up site analytics].
+Social card of [formatting] reference.
-[Twitter's Card validator] shows how it will look when shared.
 
   </figcaption>
 </figure>
 
-  [^1]:
+  [custom layouts]: #custom-layouts
-    Both types of logos, images ([`theme.logo`](changing-the-logo-and-icons.md#image)) 
+  [formatting]: ../reference/formatting.md
-    and icons ([`theme.icon.logo`](changing-the-logo-and-icons.md#icon-bundled))
-    are supported.  While an image logo is used as-is, icons are filled with the 
-    ([`social.cards_color.text`](#+social.cards_color)) color. Valid file paths
-    inside the [`custom_dir`](../customization.md#setup-and-theme-structure) will take priority.  
-
-  [colors]: changing-the-colors.md#primary-color
-  [fonts]: changing-the-fonts.md#regular-font
-  [logo]: changing-the-logo-and-icons.md#logo
-  [Social cards preview]: ../assets/screenshots/social-cards.png
-  [setting up site analytics]: setting-up-site-analytics.md
-  [Twitter's Card validator]: https://cards-dev.twitter.com/validator
 
 ## Configuration
 
@@ -40,17 +31,72 @@ The social preview image for the page on [setting up site analytics].
 :octicons-cpu-24: Plugin ·
 :octicons-beaker-24: Experimental
 
-First, ensure you've installed all [dependencies] and have a valid [`site_url`]
+The built-in social plugin automatically generate a custom preview image for 
-[site_url], as social preview images must be referenced via absolute URLs.
+each page. Install all [dependencies for image processing][^1] and add the 
-Then, add the following lines to `mkdocs.yml`:
+following lines to `mkdocs.yml`:
+
+  [^1]:
+    The awesome thing about social cards is that they are generated during 
+    build time and directly distributed with your documentation, no external 
+    services involved. While it would technically be simpler to generate 
+    social cards using a web browser and an automation framework like 
+    [Puppeteer], it would add further liabilities to the toolchain, with the 
+    potential to make build pipelines more complex and resource intense.
+
+    For this reason, Material for MkDocs again follows its core principle of 
+    making it as simple and powerful as possible, providing an easy-to-use 
+    framework for building [custom layouts] using Python image processing 
+    libraries. Additionally, this means that there's no necessity for internet
+    access in CI environments.
 
 ``` yaml
 plugins:
   - social
 ```
 
+> Note that [Insiders] contains a ground up rewrite of the social plugin that 
+> generates images much more efficiently in parallel and allows to build 
+> entirely [custom layouts].
+
 The following configuration options are available:
 
+[`enabled`](#+social.enabled){ #+social.enabled }
+
+:   :octicons-milestone-24: Default: `true` – This option specifies whether
+    the plugin is enabled when building your project. If you want to speed up
+    local builds, you can use an [environment variable]:
+
+    ``` yaml
+    plugins:
+      - social:
+          enabled: !ENV [CI, false]
+    ```
+
+[`concurrency`](#+social.concurrency){ #+social.concurrency }
+
+:   [:octicons-tag-24: insiders-4.33.0][Insiders] · :octicons-milestone-24: 
+    Default: _number of CPUs_ – How many CPUs the plugin is allowed to use when
+    generating social cards. With more CPUs, the plugin can do more work in the
+    same time, thus complete generation faster. Concurrent processing can be
+    disabled with:
+
+    ``` yaml
+    plugins:
+      - social:
+          concurrency: 1
+    ```
+
+  [Social cards support]: https://github.com/squidfunk/mkdocs-material/releases/tag/8.5.0
+  [built-in plugins]: ../insiders/getting-started.md#built-in-plugins
+  [dependencies for image processing]: dependencies/image-processing.md
+  [Puppeteer]: https://github.com/puppeteer/puppeteer
+  [Insiders]: ../insiders/index.md
+  [environment variable]: https://www.mkdocs.org/user-guide/configuration/#environment-variables
+
+#### Social cards
+
+The following configuration options are available for social card generation:
+
 [`cards`](#+social.cards){ #+social.cards }
 
 :   :octicons-milestone-24: Default: `true` – This option specifies whether
@@ -60,256 +106,250 @@ The following configuration options are available:
     ``` yaml
     plugins:
       - social:
-          cards: !ENV [CARDS, false]
+          cards: !ENV [CI, false]
+    ```
+
+[`cards_dir`](#+social.cards_dir){ #+social.cards_dir }
+
+:   :octicons-milestone-24: Default: `assets/images/social` – This option
+    specifies where the generated social cards will be stored. While it's
+    usually not necessary to change this option, change it with:
+
+    ``` yaml
+    plugins:
+      - social:
+          cards_dir: assets/images/social
     ```
 
 [`cards_color`](#+social.cards_color){ #+social.cards_color }
 
-:   :octicons-milestone-24: Default: [`theme.palette.primary`][palette.primary]
+:   :octicons-milestone-24: Default: [`theme.palette.primary`][primary color] – 
-    – This option specifies the colors for the background `fill` and foreground 
+    This option specifies the colors for the background `fill` and foreground
     `text` when generating the social card:
 
     ``` yaml
     plugins:
       - social:
           cards_color:
-            fill: "#0FF1CE" # (1)!
+            fill: "#0FF1CE"
             text: "#FFFFFF"
     ```
 
-    1.  Colors can either be defined as HEX colors, or as [CSS color keywords].
+    !!! warning "If you're using [Insiders], use [`cards_layout_params`](#+social.cards_layout_params)"
-        Note that HEX colors must be enclosed in quotes.
 
 [`cards_font`](#+social.cards_font){ #+social.cards_font }
 
-:   :octicons-milestone-24: Default: [`theme.font.text`][font.text] – This
+:   :octicons-milestone-24: Default: [`theme.font.text`][font] – This option
-    option specifies which font to use for rendering the social card, which can
+    specifies which font to use for rendering the social card, which can be
-    be any font hosted on [Google Fonts]:
+    any font hosted on [Google Fonts]:
 
     ``` yaml
     plugins:
       - social:
-          cards_font: Roboto
+          cards_font: Ubuntu
     ```
 
-    !!! question "Why do social cards render boxes for CJK languages?"
+    !!! warning "If you're using [Insiders], use [`cards_layout_params`](#+social.cards_layout_params)"
 
-        Some fonts do not contain CJK characters, like for example the
+[`cards_layout_dir`](#+social.cards_layout_dir){ #+social.cards_layout_dir }
-        [default font, `Roboto`][font.text]. In case your `site_name`,
-        `site_description`, or [page title] contain CJK characters, choose
-        another font from [Google Fonts] which comes with CJK characters, e.g.
-        one from the `Noto Sans` font family:
 
-        === "Chinese (Simplified)"
+:   [:octicons-tag-24: insiders-4.33.0][Insiders] · :octicons-milestone-24:
-
+    Default: _project root_ – This option specifies where the social plugin
-            ``` yaml
+    should try to resolve [custom layouts] from, taking precedence over the
-            plugins:
+    included layouts:
-              - social:
-                  cards_font: Noto Sans SC
-            ```
-
-        === "Chinese (Traditional)"
-
-            ``` yaml
-            plugins:
-              - social:
-                  cards_font: Noto Sans TC
-            ```
-
-        === "Japanese"
-
-            ``` yaml
-            plugins:
-              - social:
-                  cards_font: Noto Sans JP
-            ```
-
-        === "Korean"
-
-            ``` yaml
-            plugins:
-              - social:
-                  cards_font: Noto Sans KR
-            ```
-
-[`cards_dir`](#+social.cards_dir){ #+social.cards_dir }
-
-:   :octicons-milestone-24: Default: `assets/images/social` – This option
-    specifies where the generated social card images will be written to. It's
-    normally not necessary to change this option:
 
     ``` yaml
     plugins:
       - social:
-          cards_dir: path/to/folder
+          cards_layout_dir: .overrides/social/layouts
     ```
 
-  [Social cards support]: https://github.com/squidfunk/mkdocs-material/releases/tag/8.5.0
+[`cards_layout`](#+social.cards_layout){ #+social.cards_layout } :material-alert-decagram:{ .mdx-pulse title="Added on May 8, 2023" }
-  [dependencies]: #dependencies
-  [site_url]: https://www.mkdocs.org/user-guide/configuration/#site_url
-  [palette.primary]: changing-the-colors.md#primary-color
-  [font.text]: changing-the-fonts.md#regular-font
-  [environment variable]: https://www.mkdocs.org/user-guide/configuration/#environment-variables
-  [CSS color keywords]: https://developer.mozilla.org/en-US/docs/Web/CSS/color_value#color_keywords
-  [Google Fonts]: https://fonts.google.com
-  [page title]: ../reference/index.md#setting-the-page-title
 
-#### Dependencies
+:   [:octicons-tag-24: insiders-4.33.0][Insiders] · :octicons-milestone-24:
+    Default: `default` – Layout specification the social card should use. The
+    plugin includes the following layouts which make use of the [color palette]
+    and [font]:
 
-Two Python libraries must be installed alongside Material for MkDocs to generate
+    === "`default`"
-the social preview images, both of which are based on [Cairo Graphics] – 
-[Pillow] and [CairoSVG]:
 
-```
+        ``` yaml
-pip install pillow cairosvg
+        plugins:
-```
+          - social:
+              cards_layout: default
+        ```
 
-Both libraries are built with native extensions which need to be installed as
+        This layout uses the configured [primary color] as a background:
-well. The [Docker image] comes with all dependencies pre-installed. If you don't
-want to use Docker, see the following section which explains how to install all
-dependencies on your system:
 
-=== ":material-apple: macOS"
+        [![Layout default]][Layout default]
 
-    Make sure [Homebrew] is installed, which is a modern package manager for
+    === "`default/variant`"
-    macOS. Next, use the following command to install all necessary
-    dependencies:
 
-    ```
+        ``` yaml
-    brew install cairo freetype libffi libjpeg libpng zlib
+        plugins:
+          - social:
+              cards_layout: default/variant
+        ```
+
+        This layout includes the [page icon] as a watermark, if defined:
+
+        [![Layout default variant]][Layout default variant]
+
+    === "`default/accent`"
+
+        ``` yaml
+        plugins:
+          - social:
+              cards_layout: default/accent
+        ```
+
+        This layout uses the configured [accent color] as a background:
+
+        [![Layout default accent]][Layout default accent]
+
+    === "`default/invert`"
+
+        ``` yaml
+        plugins:
+          - social:
+              cards_layout: default/invert
+        ```
+
+        This layout inverts the background and foreground colors:
+
+        [![Layout default invert]][Layout default invert]
+
+    All of the `default` layouts use the following variables:
+
+    - :material-page-layout-header: – `config.site_name`
+    - :material-page-layout-body: – `page.meta.title` or `page.title`
+    - :material-page-layout-footer: – `page.meta.description` or `config.site_description`
+    - :material-page-layout-sidebar-right: – `theme.logo` or `theme.icon.logo`
+
+[`cards_layout_params`](#+social.cards_layout_params){ #+social.cards_layout_params }
+
+:   [:octicons-tag-24: insiders-4.33.0][Insiders] · :octicons-milestone-24:
+    Default: _none_ – This option allows to set [parameters] as provided by
+    the layout specification. For [custom layouts], this key can be used to
+    provide layout-specific options, making layouts entirels configurable.
+
+    ---
+
+    All [`default`][default layouts] layouts specify the following parameters:
+
+    [`background_color`](#+social.cards_layout_params.background_color){ #+social.cards_layout_params.background_color }
+
+    :   Set a background color, which can be a [CSS color keyword], a 3, 4, 6
+        or 8 letter HEX color code. Alpha channels are supported as well:
+
+        ``` yaml
+        plugins:
+          - social:
+              cards_layout_params:
+                background_color: "#0FF1CE"
+        ```
+
+    [`background_image`](#+social.cards_layout_params.background_image){ #+social.cards_layout_params.background_image }
+
+    :   Set a background image. If a `background_color` is set, like for the
+        [`default`][default layouts] layouts, the image is tinted (overlayed)
+        with the color. Thus, the background color must be (partially)
+        transparent for the image to become visible:
+
+        ``` yaml
+        plugins:
+          - social:
+              cards_layout_params:
+                background_color: "#00000000"
+                background_image: .overrides/social/background.png
+        ```
+
+        The path of the image must be defined relative to the project root.
+
+    [`color`](#+social.cards_layout_params.color){ #+social.cards_layout_params.color }
+
+    :   Set a foreground color, which can be a [CSS color keyword], a 3, 4, 6
+        or 8 letter HEX color code. The color is primarily used to tint text and
+        icons:
+
+        ``` yaml
+        plugins:
+          - social:
+              cards_layout_params:
+                color: "#0FF1CE"
+        ```
+
+    [`font_family`](#+social.cards_layout_params.font_family){ #+social.cards_layout_params.font_family }
+
+    :   Set a font family. This overrides the [font] that is set as part of the
+        theme configuration. The [built-in social plugin] will automatically
+        download the font from [Google Fonts]:
+
+        ``` yaml
+        plugins:
+          - social:
+              cards_layout_params:
+                font_family: Ubuntu
+        ```
+
+  [color palette]: ./changing-the-colors.md#color-palette
+  [primary color]: ./changing-the-colors.md#primary-color
+  [accent color]: ./changing-the-colors.md#accent-color
+  [font]: ./changing-the-fonts.md#regular-font
+  [Google Fonts]: https://fonts.google.com/
+  [page icon]: ../reference/index.md#setting-the-page-icon
+  [Layout default]: ../assets/screenshots/social-cards.png
+  [Layout default variant]: ../assets/screenshots/social-cards-variant.png
+  [Layout default accent]: ../assets/screenshots/social-cards-accent.png
+  [Layout default invert]: ../assets/screenshots/social-cards-invert.png
+  [parameters]: #parameters
+  [default layouts]: #+social.cards_layout
+  [CSS color keyword]: https://developer.mozilla.org/en-US/docs/Web/CSS/color_value#color_keywords
+
+#### Caching
+
+The [built-in social plugin] implements an intelligent caching mechanism,
+ensuring that social cards are only re-generated when they're not contained in
+the cache or their contents change. If any of the variables used in a layout 
+changes, the plugin will detect it and re-generate the card.
+
+The following configuration options are available for caching:
+
+[`cache`](#+social.cache){ #+social.cache }
+
+:   [:octicons-tag-24: insiders-4.33.0][Insiders] · :octicons-milestone-24:
+    Default: `true` – Whether the plugin queries its cache for an existing
+    artifact before starting a generation job. It's normally not necessary to
+    change this setting, except for when debugging the plugin itself. Caching
+    can be disabled with:
+
+    ``` yaml
+    plugins:
+      - social:
+          cache: false
     ```
 
-=== ":fontawesome-brands-windows: Windows"
+[`cache_dir`](#+social.cache_dir){ #+social.cache_dir }
 
-    As stated in the [installation guide], the easiest way to get up and running
+:   :octicons-milestone-24: Default: `.cache/plugins/social` – This option
-    with the [Cairo Graphics] library on Windows is by installing [GTK+], since
+    specifies the file system location of the plugin's cache. It's normally not
-    it has Cairo as a dependency. You can also download and install a
+    necessary to change this setting, except for when debugging the plugin
-    precompiled [GTK runtime].
+    itself. The cache directory can be changed with:
 
-=== ":material-linux: Linux"
+    ``` yaml
-
+    plugins:
-    There are several package managers for Linux with varying availability per
+      - social:
-    distribution. The [installation guide] explains how to install the [Cairo
+          cache_dir: .cache/plugins/social
-    Graphics] library for your distribution:
-
-    === ":material-ubuntu: Ubuntu"
-
-        ```
-        apt-get install libcairo2-dev libfreetype6-dev libffi-dev libjpeg-dev libpng-dev libz-dev
-        ```
-
-    === ":material-fedora: Fedora"
-
-        ```
-        yum install cairo-devel freetype-devel libffi-devel libjpeg-devel libpng-devel zlib-devel
-        ```
-
-    === ":fontawesome-brands-suse: openSUSE"
-
-        ```
-        zypper install cairo-devel freetype-devel libffi-devel libjpeg-devel libpng-devel zlib-devel
-        ```
-
-  [Cairo Graphics]: https://www.cairographics.org/
-  [Pillow]: https://pillow.readthedocs.io/
-  [CairoSVG]: https://cairosvg.org/
-  [Docker image]: https://hub.docker.com/r/squidfunk/mkdocs-material/
-  [Homebrew]: https://brew.sh/
-  [installation guide]: https://www.cairographics.org/download/
-  [GTK+]: https://www.gtk.org/docs/installations/windows/
-  [GTK runtime]: https://github.com/tschoonj/GTK-for-Windows-Runtime-Environment-Installer/releases
-
-#### Caching <small>recommended</small> { #caching data-toc-label="Caching" }
-
-The [built-in social plugin] automatically fetches the fonts you define in
-`mkdocs.yml` from Google Fonts, and uses them to render the text that is
-displayed on the social card. The font files and generated cards are both
-written to the `.cache` directory, which is used in subsequent builds to detect
-whether the social cards need to be regenerated. You might want to:
-
-1.  Ignore the `.cache` directory in your project, by adding it to `.gitignore`.
-2.  When building your site for publishing, use a build cache to save the
-    `.cache` directory in between builds. Taking the example from the
-    [publishing guide], add the following lines:
-
-    ``` yaml hl_lines="15-20"
-    name: ci
-      on:
-        push:
-          branches:
-            - master
-            - main
-    jobs:
-      deploy:
-        runs-on: ubuntu-latest
-        steps:
-          - uses: actions/checkout@v3
-          - uses: actions/setup-python@v4
-            with:
-              python-version: 3.x
-          - uses: actions/cache@v3
-            with:
-              key: mkdocs-material-${{ github.sha }}
-              path: .cache
-              restore-keys: |
-                mkdocs-material-
-          - run: pip install mkdocs-material
-          - run: mkdocs gh-deploy --force
     ```
 
+    By default, all built-in plugins that implement caching will create a
+    `.cache` directory in the same folder your `mkdocs.yml` resides, and create
+    subfolders to not interfere with each other. If you use multiple instances
+    of this plugin, it could be necessary to change this setting.
+
   [built-in social plugin]: #built-in-social-plugin
   [publishing guide]: ../publishing-your-site.md#with-github-actions
 
-#### Meta tags
-
-The [built-in social plugin] automatically sets all necessary `meta` tags,
-equivalent to the following two customizations, which you can set manually when
-you don't want to use it:
-
-=== ":material-graph: Open Graph"
-
-    ``` html
-    {% extends "base.html" %}
-
-    {% block extrahead %}
-      {% set title = config.site_name %}
-      {% if page and page.meta and page.meta.title %}
-        {% set title = title ~ " - " ~ page.meta.title %}
-      {% elif page and page.title and not page.is_homepage %}
-        {% set title = title ~ " - " ~ page.title %}
-      {% endif %}
-      <meta property="og:type" content="website" />
-      <meta property="og:title" content="{{ title }}" />
-      <meta property="og:description" content="{{ config.site_description }}" />
-      <meta property="og:url" content="{{ page.canonical_url }}" />
-      <meta property="og:image" content="<url>" />
-      <meta property="og:image:type" content="image/png" />
-      <meta property="og:image:width" content="1200" />
-      <meta property="og:image:height" content="630" />
-    {% endblock %}
-    ```
-
-=== ":fontawesome-brands-twitter: Twitter Cards"
-
-    ``` html
-    {% extends "base.html" %}
-
-    {% block extrahead %}
-      {% set title = config.site_name %}
-      {% if page and page.meta and page.meta.title %}
-        {% set title = title ~ " - " ~ page.meta.title %}
-      {% elif page and page.title and not page.is_homepage %}
-        {% set title = title ~ " - " ~ page.title %}
-      {% endif %}
-      <meta name="twitter:card" content="summary_large_image" />
-      <meta name="twitter:title" content="{{ title }}" />
-      <meta name="twitter:description" content="{{ config.site_description }}" />
-      <meta name="twitter:image" content="<url>" />
-    {% endblock %}
-    ```
-
-  [Twitter Cards]: https://developer.twitter.com/en/docs/tweets/optimize-with-cards/overview/abouts-cards
-
 ## Usage
 
 If you want to adjust the title or set a custom description for the social card,
@@ -321,3 +361,60 @@ precedence over the default values.
 
   [Changing the title]: ../reference/index.md#setting-the-page-title
   [Changing the description]: ../reference/index.md#setting-the-page-description
+
+
+### Choosing a font
+
+Some fonts do not contain CJK characters, like for example the
+[default font, `Roboto`][font]. In case your `site_name`, `site_description`, or
+page title contain CJK characters, choose another font from [Google Fonts] which
+comes with CJK characters, e.g. one from the `Noto Sans` font family:
+
+=== "Chinese (Simplified)"
+
+    ``` yaml
+    plugins:
+      - social:
+          cards_font: Noto Sans SC
+    ```
+
+=== "Chinese (Traditional)"
+
+    ``` yaml
+    plugins:
+      - social:
+          cards_font: Noto Sans TC
+    ```
+
+=== "Japanese"
+
+    ``` yaml
+    plugins:
+      - social:
+          cards_font: Noto Sans JP
+    ```
+
+=== "Korean"
+
+    ``` yaml
+    plugins:
+      - social:
+          cards_font: Noto Sans KR
+    ```
+
+## Customization
+
+### Custom layouts
+
+[:octicons-heart-fill-24:{ .mdx-heart } Sponsors only][Insiders]{ .mdx-insiders } ·
+[:octicons-tag-24: insiders-4.33.0][Insiders] ·
+:octicons-beaker-24: Experimental
+
+!!! info "Custom layout guide coming shortly"
+
+    We're working hard to explain in detail how to build custom layouts. If you
+    want to start to build a custom layout right away before we finish the guide,
+    check out the [source code of the `default` layout](https://github.com/squidfunk/mkdocs-material-insiders/blob/master/src/plugins/social/layouts/default.yml)
+    and watch the [demo on Twitter](https://twitter.com/squidfunk/status/1654832324272431104).
+
+#### Parameters