Built-in social plugin

The social plugin automatically and intelligently generates beautiful and highly customizable social cards in different layouts for each page of your project, rendering as preview images whenever you or somebody else share a link to your project on social media.

Objective

How it works

The plugin automatically generates a customizable social card for each page of your project, which appears as a preview image when sharing a link to your project on social media, without the use of external services and just a single line of configuration.

With the use of an efficient image processing library, the plugin allows to define custom layouts for social cards, which can be adapted to match your project's style and branding. While it would technically be much simpler to generate social cards by using a web browser and an automation framework like Puppeteer[^1], it would add further liabilities to your toolchain, with the potential to make build pipelines more complex, much more resource intense, and significantly slower.

[^1]: GitHub wrote in their blog that they use Puppeteer to generate social card images for repositories, issues, commits, discussions, and basically everything else that appear as preview images when shared on social media.

The generated social cards are cached and stored in the [site directory][mkdocs.site_dir], and thus self-hosted, ensuring that your project doesn't depend on external services. In order to generate social cards images, a few dependencies need to be available on your system.

When to use it

There's one particular case when we don't recommend to use the plugin: when you build offline-capable documentation to offer it as a download. Otherwise, it always makes sense to enable the plugin, as links to your documentation shared on social media will appear much more appealing.

Even more interestingly, the plugin can be combined with other built-in plugins that Material for MkDocs offers, in order to create sophisticated build pipelines tailored to your project:

Configuration

In order to get started with the social plugin, just add the following lines to mkdocs.yml, and observe how Material for MkDocs generates beautiful social cards for you:

plugins:
  - social

The social plugin is built into Material for MkDocs and doesn't need to be installed.

However, in order to generate social card images, it's necessary to install the dependencies for image processing, if they're not already available on your system. The linked guide includes instructions for several operating systems and mentions some alternative environments.

General

The following settings are available:

Use this setting to enable or disable the plugin when building your project. If you want to disable the plugin, e.g., for local builds, you can use an [environment variable][mkdocs.env] in mkdocs.yml:

plugins:
  - social:
      enabled: !ENV [CI, false]

This configuration enables the plugin only during continuous integration (CI).

With more CPUs available, the plugin can do more work in parallel, and thus complete social card generation faster. If you want to disable concurrent processing completely, use:

plugins:
  - social:
      concurrency: 1

By default, the plugin uses all available CPUs - 1 with a minimum of 1.

Caching

The plugin implements an intelligent caching mechanism, ensuring that social cards are only regenerated when their contents change or they're not already contained in the cache. If any of the variables used in a layout changes, the plugin detects it and regenerates the social card.

The following settings are available for caching:

Use this setting to instruct the plugin to bypass the cache, in order to re-generate social cards for all pages, even though the cache may not be stale. It's normally not necessary to specify this setting, except for when debugging the plugin itself. Caching can be disabled with:

plugins:
  - social:
      cache: false

It is normally not necessary to specify this setting, except for when you want to change the path within your root directory where social card images are cached. If you want to change it, use:

plugins:
  - social:
      cache_dir: my/custom/dir

If you're using multiple instances of the plugin, it can be a good idea to set different cache directories for both instances, so that they don't interfere with each other.

Logging

The following settings are available for logging:

Use this setting to control whether the plugin should only log errors when generating social cards without terminating the build, e.g., invalid references to icons. To terminate the build, use:

plugins:
  - social:
      log: false

Use this setting to control the log level that the plugin should employ when encountering errors, which requires that the [log][config.log] setting is enabled. The following log levels are available:

=== "warn"

``` yaml
plugins:
  - social:
      log_level: warn
```

Errors are reported as warnings, terminating the build in
[`strict`][mkdocs.strict] mode.

=== "info"

``` yaml
plugins:
  - social:
      log_level: info
```

Errors are only reported as informational messages.

=== "ignore"

``` yaml
plugins:
  - social:
      log_level: ignore
```

Errors are only reported when using the `--verbose` flag.

Social cards

The following settings are available for social card generation:

Use this setting to enable or disable social card generation. Currently, the plugin's sole purpose is to generate social cards, so it's equivalent to the [enabled][config.enabled] setting, but in the future, other features might be added. If you want to disable social card generation, use:

plugins:
  - social:
      cards: false

It is normally not necessary to specify this setting, except for when you want to change the path within the [site directory][mkdocs.site_dir] where social cards are stored. If you want to change it, use:

plugins:
  - social:
      cards_dir: my/custom/dir

This configuration stores the generated images at my/custom/dir in the [site directory][mkdocs.site_dir].

If you want to build a custom social card layout, use this setting to change the folder where you store your custom layouts, the default being a folder called layouts in your root directory:

plugins:
  - social:
      cards_layout_dir: layouts

The provided path is resolved from the root directory.

!!! tip "Where to store custom layouts"

Our recommendation is to locate the folder outside of the
[`docs` directory][mkdocs.docs_dir], to make sure that your [custom layouts]
are not copied to the [`site` directory][mkdocs.site_dir] when
[building your project], e.g., by adhering to the following directory
layout:

``` { .sh .no-copy }
.
├─ docs/
│  └─ *.md
├─ layouts/
│  └─ *.yml
└─ mkdocs.yml
```

The plugin ships a growing list of default layouts for social cards. If you've created a custom social card layout, you can instruct the plugin to use it exactly as one of the included layouts:

plugins:
  - social:
      cards_layout: my-custom-layout

The provided path is resolved from the[ layouts directory][config.cards_layout_dir].

!!! tip "How custom layouts are resolved"

By default, the plugin will load your [custom layouts] from a folder named
`layouts` in your root directory. If your layout is called
`my-custom-layout`, the directory layout must adhere to:

``` { .sh .no-copy }
.
├─ docs/
│  └─ *.md
├─ layouts/
│  └─ my-custom-layout.yml
└─ mkdocs.yml
```

Use this setting to set options for the layout specified via [cards_layout] [config.cards_layout] (if the layout supports it), which allows for making layouts easily and entirely configurable:

plugins:
  - social:
      cards_layout_options:
        <option>: <value>

When creating a custom layout, you are completely free in defining which parts of your layout can be parametrized. The default layouts included with the plugin support the following options:

Use this setting to enable social card generation for subsections of your project, e.g., when using multiple instances of the plugin to generate different social cards for different subsections:

plugins:
  - social:
      cards_include:
        - blog/*

This configuration enables social card generation for all pages that are contained in the blog folder and its subfolders inside the [docs directory] [mkdocs.docs_dir].

Use this setting to disable social card generation for subsections of your project, e.g., when using multiple instances of the plugin to generate different social cards for different subsections:

plugins:
  - social:
      cards_exclude:
        - changelog/*

This configuration disables social card generation for all pages that are contained in the changelog folder and its subfolders inside the [docs directory][mkdocs.docs_dir].

Debugging

The plugin includes a special mode for debugging layouts, which is very useful when creating custom layouts, as it allows for quicker iteration and better understanding of composition.

The following settings are available for debugging:

Use this setting to enable a special mode for debugging your layout, which renders each layer with a colored outline and its x and y offsets, and overlays a dot grid for alignment, so it's easier to understand how the distinct layers of your layout are composed together:

plugins:
  - social:
      debug: true

By default, the plugin automatically disables [debug][config.debug] mode when building your project, so you can be sure that debug overlays are never deployed to production. If you want to change that, use:

plugins:
  - social:
      debug_on_build: true

It's normally not necessary to change this setting, as it's just intended to be a safety net.

When [debug][config.debug] mode is enabled, this setting specifies whether a dot grid is rendered on top of all layers, to allow for better alignment. If you want to switch the grid off, use:

plugins:
  - social:
      debug_grid: false

Use this setting to specify the step size of the dot grid in pixels, if enabled, which can be useful to create perfectly aligned layers for ideal composition. It you want to change it, use:

plugins:
  - social:
      debug_grid_step: 64

Use this setting to specify the color of the outlines that are added to each layer and the dot grid that is rendered on top of all layers. If you need to change it, use:

plugins:
  - social:
      debug_color: yellow

In rare cases, it might be necessary to change this setting if the dot grid or the outlines are hard to distinguish, as the plugin will automatically adjust the color if not explicitly set.

Usage

Metadata

The plugin allows to override a subset of settings through metadata (front matter) in order to customize social card generation, e.g., to set options for the included default layouts for a single page, or even for an entire subsection of your project by leveraging the meta plugin.

The following properties are available:

Use this property to override the [cards][config.cards] setting for the given page:

---
social:
  cards: false
---

# Page title
...

Use this property to override the [cards_layout][config.cards_layout] setting for the given page:

---
social:
  cards_layout: my-custom-layout
---

# Page title
...

Use this property to override the [cards_layout_options] [config.cards_layout_options] setting for the given page:

---
social:
  cards_layout_options:
    background_color: blue             # Change background color
    background_image: null             # Remove background image
---

# Page title
...

Setting an option to null resets the option.

Layouts

While it is possible and simple to build custom layouts, the plugin ships several predefined layouts, all of which are prefixed with default. The following layouts are included:

=== "default"

``` yaml
plugins:
  - social:
      cards_layout: default
```

<div class="result" markdown>

![Layout default]

This layout sets the following defaults:

- [`background_color`][option.background_color]
  – <!-- md:default [`theme.palette.primary`][primary color] -->

- [`font_family`][option.font_family]
  – <!-- md:default [`theme.font.text`][font] -->

</div>

=== "default/variant"

``` yaml
plugins:
  - social:
      cards_layout: default/variant
```

<div class="result" markdown>

![Layout default variant]

This layout includes the [page icon] and sets the following defaults:

- [`background_color`][option.background_color]
  – <!-- md:default [`theme.palette.primary`][primary color] -->

- [`font_family`][option.font_family]
  – <!-- md:default [`theme.font.text`][font] -->

</div>

=== "default/accent"

``` yaml
plugins:
  - social:
      cards_layout: default/accent
```

<div class="result" markdown>

![Layout default accent]

This layout sets the following defaults:

- [`background_color`][option.background_color]
  – <!-- md:default [`theme.palette.accent`][accent color] -->

- [`font_family`][option.font_family]
  – <!-- md:default [`theme.font.text`][font] -->

</div>

=== "default/invert"

``` yaml
plugins:
  - social:
      cards_layout: default/invert
```

<div class="result" markdown>

![Layout default invert]

This layout sets the following defaults:

- [`color`][option.background_color]
  – <!-- md:default [`theme.palette.primary`][primary color] -->

- [`font_family`][option.font_family]
  – <!-- md:default [`theme.font.text`][font] -->

</div>

=== "default/only/image"

``` yaml
plugins:
  - social:
      cards_layout: default/only/image
      cards_layout_options:
        background_image: layouts/background.png

```

<div class="result" markdown>

This layout only shows the given background image and scales it to cover.

</div>

The default layouts are very flexible and comfortable to use, as they replicate the original behavior of the plugin, sourcing default values for all options from other theme settings.

The following options are available:

Use this option to change the background color of the generated social card. The value can be set to a valid color value supported by pillow, the imaging library used for card generation:

=== "Hexadecimal"

``` yaml
plugins:
  - social:
      cards_layout_options:
        background_color: "#ff1493" # (1)!
```

1.  The following notations are supported, whereas each character after the
    `#` must be a valid hexadecimal in the range `#!css 0-F`:

    - `#!css #rgb` – Color (short)
    - `#!css #rgba` – Color + alpha (short)
    - `#!css #rrggbb` – Color
    - `#!css #rrggbbaa` – Color + alpha

=== "Color function"

``` yaml
plugins:
  - social:
      cards_layout_options:
        background_color: rgb(255, 20, 147) # (1)!
```

1.  The following functions are supported, listing the allowed maximum
    values with the minimum values all being `#!css 0` or `#!css 0%`:

    - `#!css rgb(255, 255, 255)` – Red, green and blue
    - `#!css hsl(360, 100%, 100%)` – Hue, saturation and lightness
    - `#!css hsv(360, 100%, 100%)` – Hue, saturation and value

=== "Color name"

``` yaml
plugins:
  - social:
      cards_layout_options:
        background_color: deeppink # (1)!
```

1.  See the [`<named-color>`][named-color] CSS data type for a list of
    supported color names. Note that some might not be available.

If this options is used together with [background_image] [option.background_image], the color is rendered on top of the image which allows for tinting images. If you want to remove the background color, use:

plugins:
  - social:
      cards_layout_options:
        background_color: transparent

Use this option to define a background image for the generated social card. Note that the image is tinted with the [background_color][option.background_color], which can also be set to transparent:

=== "Image"

``` yaml
plugins:
  - social:
      cards_layout_options:
        background_image: layouts/background.png
        background_color: transparent
```

=== "Image with tint"

``` yaml
plugins:
  - social:
      cards_layout_options:
        background_image: layouts/background.png
        background_color: "#ff149366"
```

The provided path is resolved from the root directory.

Use this option to change the foreground color of the generated social card. The value can be set to a valid color value supported by pillow, the imaging library used for card generation:

=== "Hexadecimal"

``` yaml
plugins:
  - social:
      cards_layout_options:
        color: "#ffffff" # (1)!
```

1.  The following notations are supported, whereas each character after the
    `#` must be a valid hexadecimal in the range `#!css 0-F`:

    - `#!css #rgb` – Color (short)
    - `#!css #rgba` – Color + alpha (short)
    - `#!css #rrggbb` – Color
    - `#!css #rrggbbaa` – Color + alpha

=== "Color function"

``` yaml
plugins:
  - social:
      cards_layout_options:
        color: rgb(255, 255, 255) # (1)!
```

1.  The following functions are supported, listing the allowed maximum
    values with the minimum values all being `#!css 0` or `#!css 0%`:

    - `#!css rgb(255, 255, 255)` – Red, green and blue
    - `#!css hsl(360, 100%, 100%)` – Hue, saturation and lightness
    - `#!css hsv(360, 100%, 100%)` – Hue, saturation and value

=== "Color name"

``` yaml
plugins:
  - social:
      cards_layout_options:
        color: white # (1)!
```

1.  See the [`<named-color>`][named-color] CSS data type for a list of
    supported color names. Note that some might not be available.

Use this option to change the font family of the generated social card. The plugin automatically downloads the font from Google Fonts, so the font must point to an existing Google Font:

plugins:
  - social:
      cards_layout_options:
        font_family: Ubuntu

When you've found a font that you like on Google Fonts, you can just copy the name from the font's specimen page and use it as the value for this option – no further configuration needed.

Use this option to change the logo that is used in the generated social card. By default, the plugin uses the theme.logo or theme.icon.logo setting from mkdocs.yml. You can change it with:

plugins:
  - social:
      cards_layout_options:
        logo: layouts/logo.png

The provided path is resolved from the root directory.

Use this option to change the title of the generated social card. This overrides the computed page title as assigned by MkDocs, as well as the title metadata property:

plugins:
  - social:
      cards_layout_options:
        title: My custom title

Use this option to change the description of the generated social card. This overrides the set [site_description][mkdocs.site_description], if defined, as well as the description metadata property:

plugins:
  - social:
      cards_layout_options:
        description: My custom description

!!! question "Missing something?"

When setting up social cards, you might discover that you're missing
specific functionality – we're happy to consider adding it to the plugin!
You can [open a discussion] to ask a question, or create a [change request]
on our [issue tracker], so we can find out if it might be a good fit for
the plugin.