2021-07-25 16:40:40 +03:00
|
|
|
|
---
|
|
|
|
|
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
|
2021-10-10 20:22:13 +03:00
|
|
|
|
MkDocs can generate beautiful social cards automatically, using the [colors]
|
|
|
|
|
[palette.primary], [fonts][font.text] and [logo][^1] defined in `mkdocs.yml`.
|
2021-07-25 21:36:30 +03:00
|
|
|
|
|
|
|
|
|
[^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.
|
|
|
|
|
|
2021-10-10 20:22:13 +03:00
|
|
|
|
[palette.primary]: changing-the-colors.md#primary-color
|
|
|
|
|
[font.text]: changing-the-fonts.md#regular-font
|
|
|
|
|
[logo]: changing-the-logo-and-icons.md#logo
|
2021-07-25 16:40:40 +03:00
|
|
|
|
|
|
|
|
|
## Configuration
|
|
|
|
|
|
|
|
|
|
### Built-in social cards
|
|
|
|
|
|
2021-10-03 21:28:52 +03:00
|
|
|
|
[:octicons-heart-fill-24:{ .mdx-heart } Insiders][Insiders]{ .mdx-insiders } ·
|
2021-10-10 20:22:13 +03:00
|
|
|
|
[:octicons-tag-24: insiders-2.12.0][Insiders] ·
|
2021-10-03 21:28:52 +03:00
|
|
|
|
:octicons-cpu-24: Plugin ·
|
2021-10-10 20:22:13 +03:00
|
|
|
|
:octicons-beaker-24: Experimental
|
2021-07-25 16:40:40 +03:00
|
|
|
|
|
2021-10-10 20:22:13 +03:00
|
|
|
|
The built-in social cards plugin generates a social preview image for every page
|
|
|
|
|
and adds the necessary meta tags, so it's displayed on social media when shared.
|
2021-10-10 22:04:22 +03:00
|
|
|
|
First, ensure you've set [`site_url`][site_url] in `mkdocs.yml`.[^2] Then, add
|
|
|
|
|
the following lines to `mkdocs.yml` to enable the plugin:
|
|
|
|
|
|
|
|
|
|
[^2]:
|
|
|
|
|
When using this plugin, the [`site_url`][site_url] setting is mandatory, as
|
|
|
|
|
social preview images don't work with relative URLs.
|
2021-07-25 16:40:40 +03:00
|
|
|
|
|
|
|
|
|
``` yaml
|
|
|
|
|
plugins:
|
|
|
|
|
- social
|
|
|
|
|
```
|
|
|
|
|
|
2021-10-10 20:22:13 +03:00
|
|
|
|
For example, the page on [setting up site analytics] renders as:
|
2021-07-25 16:40:40 +03:00
|
|
|
|
|
2021-10-05 00:36:31 +03:00
|
|
|
|
<figure markdown>
|
2021-07-25 16:40:40 +03:00
|
|
|
|
|
2021-10-10 20:22:13 +03:00
|
|
|
|
[![Social cards preview]][Social cards preview]
|
2021-07-25 16:40:40 +03:00
|
|
|
|
|
2021-10-05 00:36:31 +03:00
|
|
|
|
<figcaption markdown>
|
2021-07-25 16:40:40 +03:00
|
|
|
|
|
2021-07-25 21:37:57 +03:00
|
|
|
|
Want to try it out? Copy the current URL and paste it into [Twitter's Card
|
2021-10-10 20:22:13 +03:00
|
|
|
|
validator] to see how social cards look in action.
|
2021-07-25 16:40:40 +03:00
|
|
|
|
|
|
|
|
|
</figcaption>
|
|
|
|
|
</figure>
|
|
|
|
|
|
2021-10-10 20:22:13 +03:00
|
|
|
|
The following configuration options are available:
|
2021-07-25 16:40:40 +03:00
|
|
|
|
|
2021-10-10 20:22:13 +03:00
|
|
|
|
`cards_color`{ #cards-color }
|
2021-08-07 14:12:05 +03:00
|
|
|
|
|
2021-10-10 20:22:13 +03:00
|
|
|
|
: :octicons-milestone-24: Default: [primary color][palette.primary] + header
|
|
|
|
|
text color – This option specifies which colors to use for the background
|
|
|
|
|
`fill` and foreground `text` when generating the social card:
|
2021-08-07 14:12:05 +03:00
|
|
|
|
|
|
|
|
|
``` yaml
|
|
|
|
|
plugins:
|
|
|
|
|
- social:
|
|
|
|
|
cards_color:
|
2021-10-10 20:22:13 +03:00
|
|
|
|
fill: "#0FF1CE" # (1)
|
2021-08-07 14:12:05 +03:00
|
|
|
|
text: "#FFFFFF"
|
|
|
|
|
```
|
|
|
|
|
|
2021-10-10 20:22:13 +03:00
|
|
|
|
1. Colors can either be defined as HEX colors, or as [CSS color keywords].
|
|
|
|
|
Note that HEX colors must be enclosed in quotes.
|
2021-08-07 14:12:05 +03:00
|
|
|
|
|
2021-10-10 13:19:14 +03:00
|
|
|
|
`cards_directory`{ #cards-directory }
|
2021-07-25 16:40:40 +03:00
|
|
|
|
|
|
|
|
|
: :octicons-milestone-24: Default: `assets/images/social` – This option
|
2021-10-10 20:22:13 +03:00
|
|
|
|
specifies where the generated social card images will be written to. It's
|
|
|
|
|
normally not necessary to change this option:
|
2021-07-25 16:40:40 +03:00
|
|
|
|
|
|
|
|
|
``` yaml
|
|
|
|
|
plugins:
|
|
|
|
|
- social:
|
|
|
|
|
cards_directory: assets/images/social
|
|
|
|
|
```
|
|
|
|
|
|
2021-10-03 21:28:52 +03:00
|
|
|
|
[Insiders]: ../insiders/index.md
|
2021-10-10 22:04:22 +03:00
|
|
|
|
[site_url]: https://www.mkdocs.org/user-guide/configuration/#site_url
|
2021-10-10 20:22:13 +03:00
|
|
|
|
[setting up site analytics]: setting-up-site-analytics.md
|
|
|
|
|
[Social cards preview]: ../assets/screenshots/social-cards.png
|
|
|
|
|
[Twitter's Card validator]: https://cards-dev.twitter.com/validator
|
2021-10-10 22:04:22 +03:00
|
|
|
|
[meta tags]: #meta-tags
|
2021-10-10 20:22:13 +03:00
|
|
|
|
[CSS color keywords]: https://developer.mozilla.org/en-US/docs/Web/CSS/color_value#color_keywords
|
2021-07-25 21:36:30 +03:00
|
|
|
|
|
2021-10-10 22:04:22 +03:00
|
|
|
|
#### Caching <small>recommended</small> { #caching data-toc-label="Caching" }
|
2021-07-25 21:36:30 +03:00
|
|
|
|
|
2021-10-10 23:32:32 +03:00
|
|
|
|
The [built-in social cards] plugin automatically fetches the fonts you define
|
2021-10-10 20:22:13 +03:00
|
|
|
|
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
|
2021-07-25 21:36:30 +03:00
|
|
|
|
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:
|
|
|
|
|
|
2021-10-10 13:19:14 +03:00
|
|
|
|
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
|
2021-10-10 20:22:13 +03:00
|
|
|
|
[publishing guide], add the following lines:
|
2021-07-25 21:36:30 +03:00
|
|
|
|
|
|
|
|
|
``` yaml hl_lines="15-18"
|
|
|
|
|
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
|
|
|
|
|
```
|
|
|
|
|
|
2021-10-10 23:32:32 +03:00
|
|
|
|
[built-in social cards]: #built-in-social-cards
|
2021-10-10 20:22:13 +03:00
|
|
|
|
[publishing guide]: ../publishing-your-site.md#with-github-actions
|
2021-07-25 21:36:30 +03:00
|
|
|
|
|
2021-10-10 20:22:13 +03:00
|
|
|
|
#### Meta tags
|
2021-07-25 21:36:30 +03:00
|
|
|
|
|
2021-10-10 23:32:32 +03:00
|
|
|
|
The [built-in social cards] plugin automatically sets all necessary `meta` tags,
|
2021-10-10 20:22:13 +03:00
|
|
|
|
equivalent to the following two customizations, which you can set manually when
|
|
|
|
|
you don't want to use it:
|
2021-10-10 14:17:39 +03:00
|
|
|
|
|
|
|
|
|
=== ":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 %}
|
2021-10-10 20:22:13 +03:00
|
|
|
|
{% set title = title ~ " - " ~ page.title %}
|
2021-10-10 14:17:39 +03:00
|
|
|
|
{% 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 %}
|
2021-10-10 20:22:13 +03:00
|
|
|
|
{% set title = title ~ " - " ~ page.title %}
|
2021-10-10 14:17:39 +03:00
|
|
|
|
{% endif %}
|
|
|
|
|
<meta name="twitter:card" content="summary_large_image" />
|
|
|
|
|
<meta name="twitter:title" content="{{ title }}" />
|
|
|
|
|
<meta name="twitter:description" content="{{ config.site_description }}" />
|
|
|
|
|
<meta name="twitter:image" content="<url>" />
|
|
|
|
|
{% endblock %}
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
[Twitter Cards]: https://developer.twitter.com/en/docs/tweets/optimize-with-cards/overview/abouts-cards
|
2021-10-10 20:22:13 +03:00
|
|
|
|
|
|
|
|
|
## 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]
|
|
|
|
|
|
|
|
|
|
[Metadata]: extensions/python-markdown.md#metadata
|
|
|
|
|
[Changing the title]: ../reference/meta-tags.md#setting-the-page-title
|
|
|
|
|
[Changing the description]: ../reference/meta-tags.md#setting-the-page-description
|