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 key is missing, social card will not be included in a web page.

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.

Backlinks:

Home

- social cards metadata creation based on document metadata ( pub-social plugin - 06_blog/v050-social.md),

v0.5.0 - 2023-04-04

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