Ana içeriğe geç

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 Puppeteer1, 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

Errors are reported as warnings, terminating the build in strict mode.

plugins:
  - social:
      log_level: info

Errors are only reported as informational messages.

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:


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.

Where to store custom layouts

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

.
├─ 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.

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:

.
├─ 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

Layout default

This layout sets the following defaults:

plugins:
  - social:
      cards_layout: default/variant

Layout default variant

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

plugins:
  - social:
      cards_layout: default/accent

Layout default accent

This layout sets the following defaults:

plugins:
  - social:
      cards_layout: default/invert

Layout default invert

This layout sets the following defaults:

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

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

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)!
  1. The following notations are supported, whereas each character after the # must be a valid hexadecimal in the range 0-F:

    • #rgb – Color (short)
    • #rgba – Color + alpha (short)
    • #rrggbb – Color
    • #rrggbbaa – Color + alpha
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 0 or 0%:

    • rgb(255, 255, 255) – Red, green and blue
    • hsl(360, 100%, 100%) – Hue, saturation and lightness
    • hsv(360, 100%, 100%) – Hue, saturation and value
plugins:
  - social:
      cards_layout_options:
        background_color: deeppink # (1)!
  1. See the <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, 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)!
  1. The following notations are supported, whereas each character after the # must be a valid hexadecimal in the range 0-F:

    • #rgb – Color (short)
    • #rgba – Color + alpha (short)
    • #rrggbb – Color
    • #rrggbbaa – Color + alpha
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 0 or 0%:

    • rgb(255, 255, 255) – Red, green and blue
    • hsl(360, 100%, 100%) – Hue, saturation and lightness
    • hsv(360, 100%, 100%) – Hue, saturation and value
plugins:
  - social:
      cards_layout_options:
        color: white # (1)!
  1. See the <named-color> CSS data type for a list of supported color names. Note that some might not be available.

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.


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

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.


  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.