27 KiB
| title | icon |
|---|---|
| Built-in social plugin | material/share-circle |
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.
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:
-
:material-newspaper-variant-outline: Built-in blog plugin
The social plugin automatically generates beautiful and customizable social cards for each post and page, showing as previews on social media.
Links to your blog render beautiful social cards when shared on social media
-
:material-file-tree: Built-in meta plugin
The meta plugin can be used to [change the layout][meta.social.cards_layout] for social cards or [change specific layout options] [meta.social.cards_layout_options] like [background][option.background_color] or [color][option.color] for a subset of pages.
Your documentation can use completely different social cards per section
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]
default layouts included with the plugin support the following options:
- [
background_color][option.background_color] - [
background_image][option.background_image] - [
color][option.color] - [
font_family][option.font_family] - [
logo][option.logo] - [
title][option.title] - [
description][option.description]
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 #!yaml 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]
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]
meta.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.
-
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. ↩︎