mkdocs-material/docs/tutorials/social/basic.md

Basic social cards

Social cards are images that other systems such as social media can display as a preview for content linked to. It is easy to get started with the social plugin, true to the motto of Material with MkDocs: "batteries included."

Basics

Before you start, there are just a couple of dependencies to install. These are libraries for image processing that the plugin needs to produce the social cards, as well as their Python bindings.

With those prerequisites met, it is simply a matter of activating the plugin, which will:

• produce the social cards as PNG images for each page in your site;
• create meta data in the headers of your site's pages that will provide social media systems with key information and tell them how to find the social card image.

!!! example "Add social cards"

Simply add the social plugin to your list of plugins:

```yaml hl_lines="3"
    plugins:
        - search
        - social
        - ...
```

Now, then you run mkdocs build and look at the site directory, you will see that it contains subfolders under assets/images/social that reflect the structure of your Markdown files. Each page has a corresponding PNG file that contains the social card image.

Have a look at the generated HTML and you will see the metadata produced in the head element, including one entry that points to the image.

Background color

The social plugin has configuration options for changing aspects such as colors, images, fonts, logos, the title, even the description. You can configure them for all social cards in the mkdocs.yml and, in the Insiders Edition, they can be overridden in the page header for individual pages.

!!! example "Change the background color"

To change the background color to an attention-grabbing hot pink,
you might add:

```yaml hl_lines="4-5"
plugins:
...
- social:
    cards_layout_options:
        background_color: "#ff1493"
```

Logos

By default, the plugin uses the logo that you set for the whole site, either through the theme.logo or the theme.icon.logo setting. The difference between the two is that the theme.icon.logo version will directly embed the logo's SVG code into the HTML, allowing it to inherit CSS color settings. When you use theme.logo, the Material includes the logo as an image.

You can set your own logo specific for the social cards as well. The path used is relative to your project root and needs to point to an SVG file or a pixel image. It should be rectangular and have a transparent background.

!!! example "Set your own logo"

```yaml hl_lines="3-4"
plugins:
- social:
    cards_layout_options:
      logo: docs/assets/images/ourlogo.png
```

Background images

In addition to adding your own logo, the most impactful way to personalize your social cards is to add a background image instead of the default solid color background. Make sure you choose one that will contrast well with the other elements of the card.

Also, the background color gets rendered on top of the background image, allowing you to use a transparent color to tint an image. To use just the image, use the color value transparent.

!!! example "Add background image"

```yaml hl_lines="4 5"
plugins:
- social:
    cards_layout_options:
      background_image: layouts/background.png
      background_color: transparent
```

The path to the background image is resolved from the root of your project, so this is where you should make the layouts directory and place the background image. The default site of the social cards included with the plugin is 1200x630 pixels, so choose an image that size or one that scales well to it.

Additional layouts and styles

The Insiders Edition provides additional layouts as well as the option to configure different styles for different (kinds of) pages.

The Insiders Edition comes with a number of additional layouts for the social cards. For example, the default/variant layout adds a page icon to the card. You can use this to distinguish social cards visually, depending on what kind of page you are sharing.

For example, imagine you have a set of pages that advertise events and you want to include a calendar icon as a visual indication that a card advertises an event. In the following, you will set up a directory for event pages and use the meta plugin to assign them a calendar icon.

!!! example "Social cards for event pages"

First, create a directory in your `docs` directory to hold the event pages:

```
$ mkdir docs/events
```

Then, add a file `.meta.yml` inside this new directory with settings for
the page icon and a hot pink background color that will stand out on
social media. Note that you can override the background image by setting it
to `null` here since it is not visible anyway because of the opaque coloring.

```yaml
---
icon: material/calendar-plus
social:
  cards_layout_options:
    background_image: null
    background_color: "#ff1493"
---
```

Now add a page within the `docs/events` directoy. It does not need to have
any special content, just a top level header.

To turn on the `default/variant` layout in `mkdocs.yml`, add the
`cards_layout` option and also add the meta plugin:

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

After running `mkdocs build`, you can see that the social card at
`site/assets/images/social/events/index.png` features the page icon.

Note that the icon will also appear next to the navigation element for the page. If that is not what you want then you will need to modify the social card template to gets its icons from another source. You can learn how to do this in the custom social cards tutorial.

Per-page settings

With the Insiders Edition, you can customize the card layout for each page by adding settings to the page header. You have effectively done this in the previous exercise, but using the meta plugin to affect a whole set of pages.

Say that in addition to regular events you also have the odd webinar and for this you want to set a different icon and also set the description to indicate that the event is part of the webinar series.

!!! example "Override card style in page header"

Add the following to the top of the page in `docs/events` or create a new
one:

```yaml
---
icon: material/web
social:
  cards_layout_options:
    description: Our Webinar Series
---
```

What's next?

With the Insiders Edition, you can also define custom layouts if the configuration options introduced above as not enough to meet your needs. Continue to the custom social cards tutorial if you want to find out how to do this.

Social cards are particularly useful for blog posts. If you have a blog, you need to do nothing more than to turn on both plugins to create social cards to advertise your latest blog posts. If you do not have one yet but would like to, why not check out the blog tutorials?