mkdocs-material/docs/setup/setting-up-social-cards.md

template
overrides/main.html

Setting up social cards

Social cards, also known as social previews, are images that are displayed when a link to your project documentation is shared on social media. Material for MkDocs can generate beautiful social cards automatically, using the colors, fonts and logo¹ defined in mkdocs.yml.

Configuration

Built-in social cards

:octicons-heart-fill-24:{ .mdx-heart } Insiders{ .mdx-insiders } · :octicons-cpu-24: Plugin · :octicons-beaker-24: Experimental · :octicons-tag-24: insiders-2.12.0 ... present

The built-in social cards plugin generates a social card image for every page and adds the necessary meta tags, so it's displayed on social media when shared. Enable it via mkdocs.yml:

plugins:
  - social

For example, the page on setting up site analytics renders as:

Want to try it out? Copy the current URL and paste it into Twitter's Card validator to see how social cards look in action.

This is a built-in plugin, which means that no third-party plugin needs to be installed, as Material for MkDocs already bundles it. The following options are available:

cards_color{ #cards-color } :material-new-box:

:octicons-milestone-24: Default: automatically set based on primary color – This option specifies which colors to use for the background fill and foreground text when generating the social card.

plugins:
  - social:
      cards_color:
        fill: "#0FF1CE"
        text: "#FFFFFF"

Note that the values for fill and text can either be HEX color values (e.g. #0FF1CE, must be enclosed in quotes) or CSS color keywords (e.g. red, green, etc.).

cards_directory{ #cards-directory }

:octicons-milestone-24: Default: assets/images/social – This option specifies where the generated social card images will be written to. It should normally not be necessary to change this option.

plugins:
  - social:
      cards_directory: assets/images/social

Caching

When enabled, the social cards plugin automatically fetches the fonts you define in mkdocs.yml from Google Fonts, and uses them to render the text that is displayed on the social card. The font files and generated cards are both written to the .cache directory, which is used in subsequent builds to detect whether the social cards need to be regenerated. You might want to:

1. Ignore the .cache directory in your project, by adding it to .gitignore.

2. When building your site for publishing, use a build cache to save the .cache directory in between builds. Taking the example from the publishing guide, add the following lines:

   name: ci
     on:
       push:
         branches:
           - master
           - main
     jobs:
       deploy:
         runs-on: ubuntu-latest
         steps:
           - uses: actions/checkout@v2
           - uses: actions/setup-python@v2
             with:
               python-version: 3.x
           - uses: actions/cache@v2
             with:
               key: ${{ github.ref }}
               path: .cache
           - run: pip install mkdocs-material
           - run: mkdocs gh-deploy --force
   

Usage

If you want to adjust the title or set a custom description for the social card, you can use the Metadata extension, which takes precedence over the default values.

• Changing the title

• Changing the description

Using social media meta tags

The built-in social cards plugin generates beautiful image previews for social media during the build and sets all necessary meta tags, equivalent to the following two customizations:

=== ":material-graph: Open Graph"

``` html
{% block extrahead %}
  {% set title = config.site_name %}
  {% if page and page.meta and page.meta.title %}
    {% set title = title ~ " - " ~ page.meta.title %}
  {% elif page and page.title and not page.is_homepage %}
    {% set title = title ~ " - " ~ page.title | striptags %}
  {% endif %}
  <meta property="og:type" content="website" />
  <meta property="og:title" content="{{ title }}" />
  <meta property="og:description" content="{{ config.site_description }}" />
  <meta property="og:url" content="{{ page.canonical_url }}" />
  <meta property="og:image" content="<url>" />
  <meta property="og:image:type" content="image/png" />
  <meta property="og:image:width" content="1200" />
  <meta property="og:image:height" content="630" />
{% endblock %}
```

=== ":fontawesome-brands-twitter: Twitter Cards"

``` html
{% block extrahead %}
  {% set title = config.site_name %}
  {% if page and page.meta and page.meta.title %}
    {% set title = title ~ " - " ~ page.meta.title %}
  {% elif page and page.title and not page.is_homepage %}
    {% set title = title ~ " - " ~ page.title | striptags %}
  {% endif %}
  <meta name="twitter:card" content="summary_large_image" />
  <meta name="twitter:site" content="<username>" />
  <meta name="twitter:creator" content="<username>" />
  <meta name="twitter:title" content="{{ title }}" />
  <meta name="twitter:description" content="{{ config.site_description }}" />
  <meta name="twitter:image" content="<url>" />
{% endblock %}
```

---

1. Both types of logos, images (theme.logo) and icons (theme.icon.logo) are supported. While an image logo is used as-is, icons are filled with the color used in the header (white or black), which depends on the primary color. ↩︎