Setting up social cards plugin¶

Introduction¶

When you are a blogger or a person who wants to publish some documentation, book or any other piece of written text, you probably also want to share it over social media. Most platforms (like Facebook, LinkedIn, etc.) uses some web page metadata called Open Graph. Twitter is using part of this data and some additional metadata called Twitter Cards. No matter if you want to share your text with Facebook or Twitter, MkDocs Publisher is here to help you with this task and is doing it (almost) fully automatically. You don't have to edit any template like it's needed when you would like to use similar functionality from Material for MkDosc theme (at least it's true for v9.1.5). At this time (MkDocs Publisher v0.5.0 ) it's not possible to auto-generate a whole social card (this task is added to the backlog). However, it's possible to add your image as a preview with additional description, etc.

Document metadata¶

More about document metadata you can read in the document related to setting up the meta plugin.

Some data used by social cards is global (like site name) but some are unique per document. Data needed and optional that is needed by social card is:

(required)title - document title (30–65 characters),
(required) description - short document description (120–350 characters),
(optional) image - link to an image (1200×630 pixels).

example.md

---
title: Your document title
description: A short description of document content that encourage to read it
image: /some/url/to/an/image.jpg
---

Warning

If any of the required keys is missing, social card will not be included in a web page.

Title¶

As mentioned above, title is required to be set, so it's passed to social card and can be seen. Usually, the title is quite short and usually can also be used to identify from which page it came from. It's useful especially, when your page didn't have a logo, that is added to the image that is used image.

There are 3 possibilities to set up title with site name:

Site name before titleTitle only Site name after title (default)

Let's consider this set up:

mkdocs.yml

site_name: Site name

plugins:
    - pub-social:
        - site_name_in_title:
            - location: before

document.md

---
title: Document title
---

This will produce the following social card title:

Site name - Document title

Let's consider this set up:

mkdocs.yml

site_name: Site name

plugins:
    - pub-social:
        - site_name_in_title:
            - location: none

document.md

---
title: Document title
---

Document title

Let's consider this set up:

mkdocs.yml

site_name: Site name

plugins:
    - pub-social:
        - site_name_in_title:
            - location: after

document.md

---
title: Document title
---

This will produce the following social card title:

Document title - Site name

More setting can be found here.

Configuration¶

To enable the built-in social cards plugin, the following lines have to be added to mkdocs.yml file:

mkdocs.yml

plugins:
  - pub-social

Open Graph cards¶

mkdocs.yml

plugins:
  - pub-social:
      og:
        enabled: true
        locale: en_us

This option gives you an ability to enable or disable an Open Graph cards.

This option gives you an ability to set a locale of an Open Graph cards. There is a limited set of possible values.

Twitter cards¶

mkdocs.yml

plugins:
  - pub-social:
      twitter:
        enabled: true
        website: @website
        author: @author

This option gives you an ability to enable or disable a Twitter Cards.

This option gives you an ability to add a Twitter website account name.

This option gives you an ability to add a Twitter author account name.

Metadata keys names¶

You can change a name of the keys used to store metadata used to create social cards.

mkdocs.yml

plugins:
  - pub-social:
      meta_keys:
         title_key: title
         description_key: description
         image_key: image

This option gives you an ability to change a metadata title key used to create a social card.

This option gives you an ability to change a metadata description key used to create a social card.

This option gives you an ability to change a metadata image key used to create a social card.

Site name in title¶

mkdocs.yml

plugins:
  - pub-social:
      site_name_in_title:
        location: after
        delimiter: " - "

This option gives you an ability to control where site name should be placed in social card title.

This option gives you an ability to change a delimiter placed between name and title.

Backlinks:

v0.5.0 - 2023-04-04

For more details about this release, read more below or jump directly to pub-socialplugin documentation.

v1.4.0 - 2024-07-17

There is also a small update inside the social plugin for how titles are created titles are createdin social cards. So far, title was just created based on title metadata, but in most cases other tools use a bit different approach. They create a title by joining title and site name, so it helps a bit a SEO stuff and site recognition (especially when there is no logo or site name in the image). From now one, this is a default behavior, but you have control over it ../03_setup/03_seo_and_sharing/01_setting-up-social-cards.md.

There is also a small update inside the social plugin for how titles are created ../03_setup/03_seo_and_sharing/01_setting-up-social-cards.mdin social cards. So far, title was just created based on title metadata, but in most cases other tools use a bit different approach. They create a title by joining title and site name, so it helps a bit a SEO stuff and site recognition (especially when there is no logo or site name in the image). From now one, this is a default behavior, but you have control over it have control over it.