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¹, it would add further liabilities to your toolchain, with the potential to make build pipelines more complex, much more resource intense, and significantly slower.

The generated social cards are cached and stored in the site directory, 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¶

8.5.0 social – built-in

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:

enabled¶

8.5.0 true

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 in mkdocs.yml:

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

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

concurrency¶

insiders-4.33.0 available CPUs - 1

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:

cache¶

insiders-4.33.0 true

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

cache_dir¶

8.5.0 .cache/plugin/social

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:

log¶

insiders-4.40.2 true

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

log_level¶

insiders-4.40.2 warn

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

plugins:
  - social:
      log_level: warn

plugins:
  - social:
      log_level: info

plugins:
  - social:
      log_level: ignore

Social cards¶

The following settings are available for social card generation:

cards¶

8.5.0 true

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 setting, but in the future, other features might be added. If you want to disable social card generation, use:

plugins:
  - social:
      cards: false

cards_dir¶

8.5.0 assets/images/social

It is normally not necessary to specify this setting, except for when you want to change the path within the site directory 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.

cards_layout_dir¶

insiders-4.33.0 layouts

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.

.
├─ docs/
│  └─ *.md
├─ layouts/
│  └─ *.yml
└─ mkdocs.yml

cards_layout¶

insiders-4.33.0 default

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.

.
├─ docs/
│  └─ *.md
├─ layouts/
│  └─ my-custom-layout.yml
└─ mkdocs.yml

cards_layout_options¶

9.1.10

Use this setting to set options for the layout specified via 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:

cards_include¶

insiders-4.35.0

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.

cards_exclude¶

insiders-4.35.0

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.

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:

debug¶

insiders-4.33.0 false

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

debug_on_build¶

insiders-4.34.1 false

By default, the plugin automatically disables 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.

debug_grid¶

insiders-4.33.0 true

When 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

debug_grid_step¶

insiders-4.33.0 32

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

debug_color¶

insiders-4.33.0 grey

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:

cards¶

insiders-4.37.0

Use this property to override the cards setting for the given page:

---
social:
  cards: false
---

# Page title
...

cards_layout¶

insiders-4.37.0

Use this property to override the cards_layout setting for the given page:

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

# Page title
...

cards_layout_options¶

insiders-4.37.0

Use this property to override the 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:

plugins:
  - social:
      cards_layout: default

plugins:
  - social:
      cards_layout: default/variant

plugins:
  - social:
      cards_layout: default/accent

plugins:
  - social:
      cards_layout: default/invert

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

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:

background_color¶

9.1.10

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:

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

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

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

If this options is used together with 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

background_image¶

insiders-4.33.0

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

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

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

The provided path is resolved from the root directory.

color¶

9.1.10

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:

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

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

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

font_family¶

9.1.10

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.

font_variant¶

insiders-4.53.3

Use this option to change the font variant used to generate the social card. If the downloaded font has variants like Condensed or Expanded, you can set them with:

plugins:
  - social:
      cards_layout_options:
        font_variant: Condensed

The variant is combined with the style as used in the custom layout, so the plugin is instructed to use combinations like Condensed Regular or Expanded Bold.

logo¶

insiders-4.40.0

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.

title¶

insiders-4.40.0

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

description¶

insiders-4.40.0

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

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