Finished documentation on social cards

docs/insiders/index.md

@@ -331,7 +331,7 @@ are released for general availability.
 - [x] [Code annotations: custom selectors]
 - [ ] Code line wrap button
 
-  [Social plugin: custom layouts]: ../setup/setting-up-social-cards.md#custom-layouts
+  [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/setup/setting-up-social-cards.md

@@ -6,7 +6,7 @@ status: new
 
 Material for MkDocs can automatically create beautiful social cards for your 
 documentation, which appear as link previews on social media platforms. You 
-can select from a variety of [pre-designed layouts][default layouts] or create
+can select from several [pre-designed layouts][default layouts] or create
 [custom layouts] to match your unique style and branding.
 
 <figure markdown>
@@ -15,12 +15,12 @@ can select from a variety of [pre-designed layouts][default layouts] or create
 
   <figcaption markdown>
 
-Social card of [formatting] reference.
+Social card of our [formatting] reference
 
   </figcaption>
 </figure>
 
-  [custom layouts]: #custom-layouts
+  [custom layouts]: #customization
   [formatting]: ../reference/formatting.md
 
 ## Configuration
@@ -46,8 +46,7 @@ following lines to `mkdocs.yml`:
     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.
+    libraries.
 
 ``` yaml
 plugins:
@@ -95,7 +94,7 @@ The following configuration options are available:
 
 #### Social cards
 
-The following configuration options are available for social card generation:
+The following configuration options are available for card generation:
 
 [`cards`](#+social.cards){ #+social.cards }
 
@@ -121,7 +120,9 @@ The following configuration options are available for social card generation:
           cards_dir: assets/images/social
     ```
 
-[`cards_color`](#+social.cards_color){ #+social.cards_color }
+<div class="mdx-deprecated" markdown>
+
+[`cards_color`](#+social.cards_color){ #+social.cards_color } – <small>:material-trash-can: Deprecated, use [`cards_layout_options`][layout options]</small>
 
 :   :octicons-milestone-24: Default: [`theme.palette.primary`][primary color] – 
     This option specifies the colors for the background `fill` and foreground
@@ -135,9 +136,7 @@ The following configuration options are available for social card generation:
             text: "#FFFFFF"
     ```
 
-    !!! warning "If you're using [Insiders], use [`cards_layout_params`](#+social.cards_layout_params)"
-
-[`cards_font`](#+social.cards_font){ #+social.cards_font }
+[`cards_font`](#+social.cards_font){ #+social.cards_font } – <small>:material-trash-can: Deprecated, use [`cards_layout_options`][layout options]</small>
 
 :   :octicons-milestone-24: Default: [`theme.font.text`][font] – This option
     specifies which font to use for rendering the social card, which can be
@@ -149,19 +148,19 @@ The following configuration options are available for social card generation:
           cards_font: Ubuntu
     ```
 
-    !!! warning "If you're using [Insiders], use [`cards_layout_params`](#+social.cards_layout_params)"
+</div>
 
 [`cards_layout_dir`](#+social.cards_layout_dir){ #+social.cards_layout_dir }
 
 :   [:octicons-tag-24: insiders-4.33.0][Insiders] · :octicons-milestone-24:
-    Default: _project root_ – This option specifies where the social plugin
-    should try to resolve [custom layouts] from, taking precedence over the
-    included layouts:
+    Default: _none_ – This option specifies where the social plugin should try
+    to resolve [custom layouts] from, taking precedence over the included
+    layouts:
 
     ``` yaml
     plugins:
       - social:
-          cards_layout_dir: .overrides/social/layouts
+          cards_layout_dir: layouts
     ```
 
 [`cards_layout`](#+social.cards_layout){ #+social.cards_layout } :material-alert-decagram:{ .mdx-pulse title="Added on May 8, 2023" }
@@ -219,14 +218,15 @@ The following configuration options are available for social card generation:
 
         [![Layout default invert]][Layout default invert]
 
-    All of the `default` layouts use the following variables:
+    All [`default`][default layouts] layouts make use of the following
+    [template 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 }
+[`cards_layout_options`](#+social.cards_layout_options){ #+social.cards_layout_options }
 
 :   [:octicons-tag-24: insiders-4.33.0][Insiders] · :octicons-milestone-24:
     Default: _none_ – This option allows to set [parameters] as provided by
@@ -235,21 +235,21 @@ The following configuration options are available for social card generation:
 
     ---
 
-    All [`default`][default layouts] layouts specify the following parameters:
+    All [`default`][default layouts] layouts expose the following parameters:
 
-    [`background_color`](#+social.cards_layout_params.background_color){ #+social.cards_layout_params.background_color }
+    [`background_color`](#+social.cards_layout_options.background_color){ #+social.cards_layout_options.background_color }
 
-    :   Set a background color, which can be a [CSS color keyword], a 3, 4, 6
+    :   Set a background color, which can be a [CSS color keyword], or a 3, 4, 6
         or 8 letter HEX color code. Alpha channels are supported as well:
 
         ``` yaml
         plugins:
           - social:
-              cards_layout_params:
+              cards_layout_options:
                 background_color: "#0FF1CE"
         ```
 
-    [`background_image`](#+social.cards_layout_params.background_image){ #+social.cards_layout_params.background_image }
+    [`background_image`](#+social.cards_layout_options.background_image){ #+social.cards_layout_options.background_image }
 
     :   Set a background image. If a `background_color` is set, like for the
         [`default`][default layouts] layouts, the image is tinted (overlayed)
@@ -259,27 +259,27 @@ The following configuration options are available for social card generation:
         ``` yaml
         plugins:
           - social:
-              cards_layout_params:
+              cards_layout_options:
                 background_color: "#00000000"
-                background_image: .overrides/social/background.png
+                background_image: layouts/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 }
+    [`color`](#+social.cards_layout_options.color){ #+social.cards_layout_options.color }
 
-    :   Set a foreground color, which can be a [CSS color keyword], a 3, 4, 6
+    :   Set a foreground color, which can be a [CSS color keyword], or 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:
+              cards_layout_options:
                 color: "#0FF1CE"
         ```
 
-    [`font_family`](#+social.cards_layout_params.font_family){ #+social.cards_layout_params.font_family }
+    [`font_family`](#+social.cards_layout_options.font_family){ #+social.cards_layout_options.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
@@ -288,7 +288,7 @@ The following configuration options are available for social card generation:
         ``` yaml
         plugins:
           - social:
-              cards_layout_params:
+              cards_layout_options:
                 font_family: Ubuntu
         ```
 
@@ -297,15 +297,86 @@ The following configuration options are available for social card generation:
   [accent color]: ./changing-the-colors.md#accent-color
   [font]: ./changing-the-fonts.md#regular-font
   [Google Fonts]: https://fonts.google.com/
+  [layout options]: #+social.cards_layout_options
   [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
+  [template variables]: https://www.mkdocs.org/dev-guide/themes/#template-variables
   [parameters]: #parameters
   [default layouts]: #+social.cards_layout
   [CSS color keyword]: https://developer.mozilla.org/en-US/docs/Web/CSS/color_value#color_keywords
 
+#### Debugging
+
+The following configuration options are available for debugging:
+
+[`debug`](#+social.debug){ #+social.debug }
+
+:   [:octicons-tag-24: insiders-4.33.0][Insiders] · :octicons-milestone-24:
+    Default: `false` – This option enables a special debug mode, which renders
+    each layer with an outline and its `x` and `y` offset in order to understand
+    how the layout is composed, and optionally renders a grid for easier
+    alignment:
+
+    ``` yaml
+    plugins:
+      - social:
+          debug: true
+    ```
+
+    === "With debug mode"
+
+        [![Debug mode enabled]][Debug mode enabled]
+
+    === "Without"
+
+        [![Debug mode disabled]][Debug mode disabled]
+
+    [Debug mode enabled]: ../assets/screenshots/social-cards-debug.png
+    [Debug mode disabled]: ../assets/screenshots/social-cards-variant.png
+
+[`debug_grid`](#+social.debug_grid){ #+social.debug_grid }
+
+:   [:octicons-tag-24: insiders-4.33.0][Insiders] · :octicons-milestone-24:
+    Default: `true` – This option enables the rendering of a dot grid when
+    [`debug`][debug] is enabled (see screenshot above). The grid can be switched
+    off with:
+
+    ``` yaml
+    plugins:
+      - social:
+          debug_grid: false
+    ```
+
+[`debug_grid_step`](#+social.debug_grid_step){ #+social.debug_grid_step }
+
+:   [:octicons-tag-24: insiders-4.33.0][Insiders] · :octicons-milestone-24:
+    Default: `32` – This option specifies the step size of the grid in pixels,
+    if enabled, which can be used to align elements. It can be changed with:
+
+    ``` yaml
+    plugins:
+      - social:
+          debug_grid_step: 64
+    ```
+
+[`debug_color`](#+social.debug_color){ #+social.debug_color }
+
+:   [:octicons-tag-24: insiders-4.33.0][Insiders] · :octicons-milestone-24:
+    Default: `grey` – This option sets the color of the layer outlines and
+    the grid which are rendered when [`debug`][debug] is enabled. It can be
+    changed with:
+
+    ``` yaml
+    plugins:
+      - social:
+          debug_color: yellow
+    ```
+
+  [debug]: #+social.debug
+
 #### Caching
 
 The [built-in social plugin] implements an intelligent caching mechanism,
@@ -404,17 +475,336 @@ comes with CJK characters, e.g. one from the `Noto Sans` font family:
 
 ## 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"
+[Insiders] ships a ground up rewrite of the [built-in social plugin] and
+introduces a brand new layout system based on a combination of YAML and
+[Jinja templates] – the same engine Material for MkDocs uses for HTML
+templating – allowing for the creation of complex custom layouts:
 
-    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).
+<div class="mdx-social">
+  <div class="mdx-social__layer">
+    <div class="mdx-social__image">
+      <span class="mdx-social__label">Layer 0</span>
+      <img src="../../assets/screenshots/social-cards-layer-0.png" />
+    </div>
+  </div>
+  <div class="mdx-social__layer">
+    <div class="mdx-social__image">
+      <span class="mdx-social__label">Layer 1</span>
+      <img src="../../assets/screenshots/social-cards-layer-1.png" />
+    </div>
+  </div>
+  <div class="mdx-social__layer">
+    <div class="mdx-social__image">
+      <span class="mdx-social__label">Layer 2</span>
+      <img src="../../assets/screenshots/social-cards-layer-2.png" />
+    </div>
+  </div>
+  <div class="mdx-social__layer">
+    <div class="mdx-social__image">
+      <span class="mdx-social__label">Layer 3</span>
+      <img src="../../assets/screenshots/social-cards-layer-3.png" />
+    </div>
+  </div>
+  <div class="mdx-social__layer">
+    <div class="mdx-social__image">
+      <span class="mdx-social__label">Layer 4</span>
+      <img src="../../assets/screenshots/social-cards-layer-4.png" />
+    </div>
+  </div>
+  <div class="mdx-social__layer">
+    <div class="mdx-social__image">
+      <span class="mdx-social__label">Layer 5</span>
+      <img src="../../assets/screenshots/social-cards-layer-5.png" />
+    </div>
+  </div>
+</div>
 
-#### Parameters
+Social cards are composed of layers, analogous to how they are represented in
+graphic design software such as Adobe Photoshop. As many layers are common
+across the cards generated for each page (e.g., backgrounds or logos), the
+built-in social plugin can automatically deduplicate layers and render them
+just once, substantially accelerating card generation. The generated cards are
+cached to ensure they are only regenerated when their contents change.
+
+Layouts are written in YAML syntax. Before starting to create a custom layout,
+it is a good idea to [study the pre-designed layouts] (link to [Insiders]
+repository), in order to get a better understanding of how they work. Then,
+create a new layout and reference it in `mkdocs.yml`:
+
+=== ":octicons-file-code-16: `layouts/custom.yml`"
+
+    ``` yaml
+    size: { width: 1200, height: 630 }
+    layers: []
+    ```
+
+=== ":octicons-file-code-16: `mkdocs.yml`"
+
+    ``` yaml
+    plugins:
+      - social:
+          cards_layout_dir: layouts
+          cards_layout: custom
+          debug: true
+    ```
+
+Note that the `.yml` file extension should be omitted. Next, run `mkdocs serve`,
+and see how the `.cache` directory is populated with the generated cards. Open
+any card in your editor, so you can see your changes immediately. Since we
+haven't defined any layers, the cards are transparent.
+
+The following sections explain how to create custom layouts.
+
+  [Jinja templates]: https://jinja.palletsprojects.com/en/3.1.x/
+  [study the pre-designed layouts]: https://github.com/squidfunk/mkdocs-material-insiders/tree/master/src/plugins/social/layouts
+
+### Size and offset
+
+Each layer has an associated size and offset, which is defined in pixels. The
+`size` is defined by a `width` and `height` property, and the `offset` by `x`
+and `y` properties:
+
+``` yaml
+size: { width: 1200, height: 630 }
+layers:
+  - size: { width: 1200, height: 630 }
+    offset: { x: 0, y: 0 }
+```
+
+If the `size` is omitted, it defaults to the size of the layout. If the `offset`
+is omitted, it defaults to the top left corner, which is the origin for all
+layers. Saving the layout and reloading renders:
+
+![Layer size]
+
+The layer outline and grid are visible because we enabled [`debug`][debug]
+mode in `mkdocs.yml`. The top left shows the layer index and offset, which is
+useful for alignment and composition.
+
+  [Layer size]: ../assets/screenshots/social-cards-layer-size.png
+
+### Backgrounds
+
+Each layer can be assigned a background color and image. If both are given, the
+color is rendered on top of the image, allowing for semi-transparent, tinted
+backgrounds:
+
+=== "Background color"
+
+    ``` yaml
+    size: { width: 1200, height: 630 }
+    layers:
+      - background:
+          color: "#4051b5"
+    ```
+
+    ![Layer background color]
+
+=== "Background image"
+
+    ``` yaml
+    size: { width: 1200, height: 630 }
+    layers:
+      - background:
+          image: layouts/background.jpg
+    ```
+
+    ![Layer background image]
+
+=== "Background image, tinted"
+
+    ``` yaml
+    size: { width: 1200, height: 630 }
+    layers:
+      - background:
+          image: layouts/background.jpg
+          color: "#4051b5ee" # (1)!
+    ```
+
+    1.  The color value can be set to a [CSS color keyword], or a 3, 4, 6 or 8
+        letter HEX color code, allowing for semi-transparent layers.
+
+    ![Layer background]
+
+Background images are automatically scaled to fit the layer while preserving
+aspect-ratio. Notice how we omitted `size` and `offset`, because we want to
+fill the entire area of the social card.
+
+[Layer background color]: ../assets/screenshots/social-cards-layer-background-color.png
+[Layer background image]: ../assets/screenshots/social-cards-layer-background-image.png
+[Layer background]: ../assets/screenshots/social-cards-layer-background.png
+
+### Typography
+
+Now, we can add dynamic typography that is sourced from Markdown files - this is
+the actual raison d'être of the [built-in social plugin]. [Jinja templates] are
+used to render a text string that is then added to the image:
+
+``` yaml
+size: { width: 1200, height: 630 }
+layers:
+  - size: { width: 832, height: 310 }
+    offset: { x: 62, y: 160 }
+    typography:
+      content: "{{ page.title }}" # (1)!
+      align: start
+      color: white
+      line:
+        amount: 3
+        height: 1.25
+      font:
+        family: Roboto
+        style: Bold
+```
+
+1.  The following variables can be used in [Jinja templates]:
+
+    - [`config.*`][config variable]
+    - [`page.*`][page variable]
+    - [`layout.*`][layout options]
+
+    The author is free in defining `layout.*` options, which can be used to pass
+    arbitrary data to the layout from `mkdocs.yml`.
+
+This renders a text layer with the title of the page with a line height of 1.25,
+and a maximum number of 3 lines. The plugin automatically computes the font size
+from the line height, the number of lines, and font metrics like ascender and
+descender.[^2] This renders:
+
+  [^2]:
+    If the plugin would require the author to specify the font size and line
+    height manually, it would be impossible to guarantee that the text fits
+    into the layer. For this reason we implemented a declarative approach,
+    where the author specifies the desired line height and number of lines, and
+    the plugin computes the font size automatically.
+
+![Layer typography]
+
+  [config variable]: https://www.mkdocs.org/dev-guide/themes/#config
+  [page variable]: https://www.mkdocs.org/dev-guide/themes/#page
+  [Layer typography]: ../assets/screenshots/social-cards-layer-typography.png
+
+#### Overflow
+
+If the text overflows the layer, it is automatically truncated and an ellipsis
+is appended, e.g.:
+
+``` { .markdown .no-copy }
+# If we use a very long headline, we can see how the text will be truncated
+```
+
+![Layer typography ellipsis]
+
+  [Layer typography ellipsis]: ../assets/screenshots/social-cards-layer-typography-ellipsis.png
+
+#### Alignment
+
+Text can be aligned to all corners and edges of the layer. For example, if we
+want to align the text to the middle of the layer, we can set `align` to  `start center`, which will render as:
+
+![Layer typography align]
+
+  [Layer typography align]: ../assets/screenshots/social-cards-layer-typography-align.png
+
+The following table shows the supported values:
+
+<figure markdown>
+
+| Alignment      |                 |              |
+| -------------- | --------------- | ------------ |
+| :material-arrow-top-left:    `start top`    | :material-arrow-up:     `center top`    | :material-arrow-top-right:    `end top`    |
+| :material-arrow-left:        `start center` | :material-circle-small: `center`        | :material-arrow-right:        `end center` |
+| :material-arrow-bottom-left: `start bottom` | :material-arrow-down:   `center bottom` | :material-arrow-bottom-right: `end bottom` |
+
+  <figcaption>
+    Supported values for text alignment
+  </figcaption>
+</figure>
+
+#### Font
+
+The [built-in social plugin] integrates with [Google Fonts] and will
+automatically download the font files for you. The `font` property accepts a
+`family` and `style` property, where the `family` must be set to the name of the
+font, and the `style` to one of the supported font styles. For example, setting
+`family` to `Roboto` will automatically download the following files:
+
+``` { .sh .no-copy #example }
+.cache/plugins/social/fonts
+└─ Roboto/
+    ├─ Black.ttf
+    ├─ Black Italic.ttf
+    ├─ Bold.ttf
+    ├─ Bold Italic.ttf
+    ├─ Italic.ttf
+    ├─ Light.ttf
+    ├─ Light Italic.ttf
+    ├─ Medium.ttf
+    ├─ Medium Italic.ttf
+    ├─ Regular.ttf
+    ├─ Thin.ttf
+    └─ Thin Italic.ttf
+```
+
+In that case, the author can use `Bold` or `Medium Italic` as the `style`. If
+the font style specified in the layer is not part of the font family, the
+font always falls back to `Regular` and prints a warning in [`debug`][debug]
+mode, as `Regular` is included with all font families.
+
+### Icons
+
+Authors can leverage the full range of icons that are shipped with Material for
+MkDocs, or even provide custom icons by using theme extension and going through
+the process described in the guide on [additional icons]. Icons can even be
+tinted by using the `color` property:
+
+``` yaml
+size: { width: 1200, height: 630 }
+layers:
+  - background:
+      color: "#4051b5"
+  - size: { width: 144, height: 144 }
+    offset: { x: 992, y: 64 }
+    icon:
+      value: material/cat
+      color: white
+```
+
+This will render the icon in the top right corner of the social card:
+
+![Layer icon]
+
+The possibilities are endless. For example, icons can be used to draw shapes
+like circles:
+
+``` yaml
+size: { width: 1200, height: 630 }
+layers:
+  - background:
+      color: "#4051b5"
+  - size: { width: 2400, height: 2400 }
+    offset: { x: -1024, y: 64 }
+    icon:
+      value: material/circle
+      color: "#5c6bc0"
+  - size: { width: 1800, height: 1800 }
+    offset: { x: 512, y: -1024 }
+    icon:
+      value: material/circle
+      color: "#3949ab"
+```
+
+This will add two circles to the background:
+
+![Layer icon circles]
+
+__Are you missing something? Please [open a discussion] and let us know!__
+
+  [additional icons]: ./changing-the-logo-and-icons.md#additional-icons
+  [Layer icon]: ../assets/screenshots/social-cards-layer-icon.png
+  [Layer icon circles]: ../assets/screenshots/social-cards-layer-icon-circles.png
+  [open a discussion]: https://github.com/squidfunk/mkdocs-material/discussions/new

material/.overrides/assets/stylesheets/custom.bea7efe8.min.css.map

@@ -1 +0,0 @@
-{"version":3,"sources":["src/.overrides/assets/stylesheets/custom/_typeset.scss","../../../../src/.overrides/assets/stylesheets/custom.scss","src/assets/stylesheets/utilities/_break.scss","src/.overrides/assets/stylesheets/custom/layout/_banner.scss","src/.overrides/assets/stylesheets/custom/layout/_hero.scss","src/.overrides/assets/stylesheets/custom/layout/_iconsearch.scss","src/.overrides/assets/stylesheets/custom/layout/_sponsorship.scss"],"names":[],"mappings":"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","file":"custom.css"}

material/.overrides/assets/stylesheets/custom.f7ec4df2.min.css.map

@@ -0,0 +1 @@
+{"version":3,"sources":["src/.overrides/assets/stylesheets/custom/_typeset.scss","../../../../src/.overrides/assets/stylesheets/custom.scss","src/assets/stylesheets/utilities/_break.scss","src/.overrides/assets/stylesheets/custom/layout/_banner.scss","src/.overrides/assets/stylesheets/custom/layout/_hero.scss","src/.overrides/assets/stylesheets/custom/layout/_iconsearch.scss","src/.overrides/assets/stylesheets/custom/layout/_sponsorship.scss"],"names":[],"mappings":"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","file":"custom.css"}

material/.overrides/main.html

@@ -3,7 +3,7 @@
 -#}
 {% extends "base.html" %}
 {% block extrahead %}
-  <link rel="stylesheet" href="{{ 'assets/stylesheets/custom.bea7efe8.min.css' | url }}">
+  <link rel="stylesheet" href="{{ 'assets/stylesheets/custom.f7ec4df2.min.css' | url }}">
 {% endblock %}
 {% block announce %}
   For updates follow <strong>@squidfunk</strong> on

mkdocs.yml

@@ -24,7 +24,7 @@ site_url: https://squidfunk.github.io/mkdocs-material/
 site_author: Martin Donath
 site_description: >-
   Write your documentation in Markdown and create a professional static site in
-  minutes – searchable, customizable, for all devices
+  minutes – searchable, customizable, in 60+ languages, for all devices
 
 # Repository
 repo_name: squidfunk/mkdocs-material

src/.overrides/assets/stylesheets/custom/_typeset.scss

@@ -211,4 +211,74 @@
       }
     }
   }
+
+  // Social card
+  .mdx-social {
+    position: relative;
+    height: min(#{px2rem(540px)}, 80vw);
+
+    // Social card image on hover
+    &:hover .mdx-social__image {
+      background-color: rgba(228, 228, 228, 0.05);
+    }
+
+    // Social card layer
+    &__layer {
+      position: absolute;
+      margin-top: px2rem(80px);
+      transition: 250ms cubic-bezier(0.7, 0, 0.3, 1);
+      transform-style: preserve-3d;
+
+      // Social card layer on hover
+      &:hover {
+
+        // Social card label
+        .mdx-social__label {
+          opacity: 1;
+        }
+
+        // Social card image
+        .mdx-social__image {
+          background-color: rgba(127, 127, 127, 0.99);
+        }
+
+        // Hide top layers
+        ~ .mdx-social__layer {
+          opacity: 0;
+        }
+      }
+    }
+
+    // Social card image
+    &__image {
+      box-shadow:
+        px2rem(-5px) px2rem(5px) px2rem(10px)
+        rgba(0, 0, 0, 0.05);
+      transition: all 250ms;
+      transform: rotate(-40deg) skew(15deg, 15deg) scale(0.7);
+
+      // Actual image
+      img {
+        display: block;
+      }
+    }
+
+    // Social card label
+    &__label {
+      position: absolute;
+      display: block;
+      padding: px2rem(4px) px2rem(8px);
+      color: var(--md-default-bg-color);
+      background-color: var(--md-default-fg-color--light);
+      opacity: 0;
+      transition: all 250ms;
+    }
+
+    // Transform on hover
+    @for $i from 6 through 0 {
+      &:hover .mdx-social__layer:nth-child(#{$i}) {
+        transform: translateY(#{($i - 3) * -10}px);
+      }
+    }
+  }
 }