mirror of
https://github.com/squidfunk/mkdocs-material.git
synced 2024-11-24 07:30:12 +01:00
323 lines
11 KiB
Markdown
323 lines
11 KiB
Markdown
# 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][^1] defined in `mkdocs.yml`,
|
||
e.g.:
|
||
|
||
<figure markdown>
|
||
|
||
[![Social cards preview]][Social cards preview]
|
||
|
||
<figcaption markdown>
|
||
|
||
The social preview image for the page on [setting up site analytics].
|
||
[Twitter's Card validator] shows how it will look when shared.
|
||
|
||
</figcaption>
|
||
</figure>
|
||
|
||
[^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. Note that custom logos and icons must reside in the `docs_dir` for
|
||
the plugin to find them. For guidance, see #4920. This limitation will be
|
||
lifted in the future when the social plugin will receive its next update.
|
||
|
||
[colors]: changing-the-colors.md#primary-color
|
||
[fonts]: changing-the-fonts.md#regular-font
|
||
[logo]: changing-the-logo-and-icons.md#logo
|
||
[Social cards preview]: ../assets/screenshots/social-cards.png
|
||
[setting up site analytics]: setting-up-site-analytics.md
|
||
[Twitter's Card validator]: https://cards-dev.twitter.com/validator
|
||
|
||
## Configuration
|
||
|
||
### Built-in social plugin
|
||
|
||
[:octicons-tag-24: 8.5.0][Social cards support] ·
|
||
:octicons-cpu-24: Plugin ·
|
||
:octicons-beaker-24: Experimental
|
||
|
||
First, ensure you've installed all [dependencies] and have a valid [`site_url`]
|
||
[site_url], as social preview images must be referenced via absolute URLs.
|
||
Then, add the following lines to `mkdocs.yml`:
|
||
|
||
``` yaml
|
||
plugins:
|
||
- social
|
||
```
|
||
|
||
The following configuration options are available:
|
||
|
||
[`cards`](#+social.cards){ #+social.cards }
|
||
|
||
: :octicons-milestone-24: Default: `true` – This option specifies whether
|
||
to generate social card images. If you want to switch the plugin off, e.g.
|
||
for local builds, you can use an [environment variable]:
|
||
|
||
``` yaml
|
||
plugins:
|
||
- social:
|
||
cards: !ENV [CARDS, false]
|
||
```
|
||
|
||
[`cards_color`](#+social.cards_color){ #+social.cards_color }
|
||
|
||
: :octicons-milestone-24: Default: [`theme.palette.primary`][palette.primary]
|
||
– This option specifies the colors for the background `fill` and foreground
|
||
`text` when generating the social card:
|
||
|
||
``` yaml
|
||
plugins:
|
||
- social:
|
||
cards_color:
|
||
fill: "#0FF1CE" # (1)!
|
||
text: "#FFFFFF"
|
||
```
|
||
|
||
1. Colors can either be defined as HEX colors, or as [CSS color keywords].
|
||
Note that HEX colors must be enclosed in quotes.
|
||
|
||
[`cards_font`](#+social.cards_font){ #+social.cards_font }
|
||
|
||
: :octicons-milestone-24: Default: [`theme.font.text`][font.text] – This
|
||
option specifies which font to use for rendering the social card, which can
|
||
be any font hosted on [Google Fonts]:
|
||
|
||
``` yaml
|
||
plugins:
|
||
- social:
|
||
cards_font: Roboto
|
||
```
|
||
|
||
!!! question "Why do social cards render boxes for CJK languages?"
|
||
|
||
Some fonts do not contain CJK characters, like for example the
|
||
[default font, `Roboto`][font.text]. In case your `site_name`,
|
||
`site_description`, or [page title] contain CJK characters, choose
|
||
another font from [Google Fonts] which comes with CJK characters, e.g.
|
||
one from the `Noto Sans` font family:
|
||
|
||
=== "Chinese (Simplified)"
|
||
|
||
``` yaml
|
||
plugins:
|
||
- social:
|
||
cards_font: Noto Sans SC
|
||
```
|
||
|
||
=== "Chinese (Traditional)"
|
||
|
||
``` yaml
|
||
plugins:
|
||
- social:
|
||
cards_font: Noto Sans TC
|
||
```
|
||
|
||
=== "Japanese"
|
||
|
||
``` yaml
|
||
plugins:
|
||
- social:
|
||
cards_font: Noto Sans JP
|
||
```
|
||
|
||
=== "Korean"
|
||
|
||
``` yaml
|
||
plugins:
|
||
- social:
|
||
cards_font: Noto Sans KR
|
||
```
|
||
|
||
[`cards_dir`](#+social.cards_dir){ #+social.cards_dir }
|
||
|
||
: :octicons-milestone-24: Default: `assets/images/social` – This option
|
||
specifies where the generated social card images will be written to. It's
|
||
normally not necessary to change this option:
|
||
|
||
``` yaml
|
||
plugins:
|
||
- social:
|
||
cards_dir: path/to/folder
|
||
```
|
||
|
||
[Social cards support]: https://github.com/squidfunk/mkdocs-material/releases/tag/8.5.0
|
||
[dependencies]: #dependencies
|
||
[site_url]: https://www.mkdocs.org/user-guide/configuration/#site_url
|
||
[palette.primary]: changing-the-colors.md#primary-color
|
||
[font.text]: changing-the-fonts.md#regular-font
|
||
[environment variable]: https://www.mkdocs.org/user-guide/configuration/#environment-variables
|
||
[CSS color keywords]: https://developer.mozilla.org/en-US/docs/Web/CSS/color_value#color_keywords
|
||
[Google Fonts]: https://fonts.google.com
|
||
[page title]: ../reference/index.md#setting-the-page-title
|
||
|
||
#### Dependencies
|
||
|
||
Two Python libraries must be installed alongside Material for MkDocs to generate
|
||
the social preview images, both of which are based on [Cairo Graphics] –
|
||
[Pillow] and [CairoSVG]:
|
||
|
||
```
|
||
pip install pillow cairosvg
|
||
```
|
||
|
||
Both libraries are built with native extensions which need to be installed as
|
||
well. The [Docker image] comes with all dependencies pre-installed. If you don't
|
||
want to use Docker, see the following section which explains how to install all
|
||
dependencies on your system:
|
||
|
||
=== ":material-apple: macOS"
|
||
|
||
Make sure [Homebrew] is installed, which is a modern package manager for
|
||
macOS. Next, use the following command to install all necessary
|
||
dependencies:
|
||
|
||
```
|
||
brew install cairo freetype libffi libjpeg libpng zlib
|
||
```
|
||
|
||
=== ":fontawesome-brands-windows: Windows"
|
||
|
||
As stated in the [installation guide], the easiest way to get up and running
|
||
with the [Cairo Graphics] library on Windows is by installing [GTK+], since
|
||
it has Cairo as a dependency. You can also download and install a
|
||
precompiled [GTK runtime].
|
||
|
||
=== ":material-linux: Linux"
|
||
|
||
There are several package managers for Linux with varying availability per
|
||
distribution. The [installation guide] explains how to install the [Cairo
|
||
Graphics] library for your distribution:
|
||
|
||
=== ":material-ubuntu: Ubuntu"
|
||
|
||
```
|
||
apt-get install libcairo2-dev libfreetype6-dev libffi-dev libjpeg-dev libpng-dev libz-dev
|
||
```
|
||
|
||
=== ":material-fedora: Fedora"
|
||
|
||
```
|
||
yum install cairo-devel freetype-devel libffi-devel libjpeg-devel libpng-devel zlib-devel
|
||
```
|
||
|
||
=== ":fontawesome-brands-suse: openSUSE"
|
||
|
||
```
|
||
zypper install cairo-devel freetype-devel libffi-devel libjpeg-devel libpng-devel zlib-devel
|
||
```
|
||
|
||
[Cairo Graphics]: https://www.cairographics.org/
|
||
[Pillow]: https://pillow.readthedocs.io/
|
||
[CairoSVG]: https://cairosvg.org/
|
||
[Docker image]: https://hub.docker.com/r/squidfunk/mkdocs-material/
|
||
[Homebrew]: https://brew.sh/
|
||
[installation guide]: https://www.cairographics.org/download/
|
||
[GTK+]: https://www.gtk.org/docs/installations/windows/
|
||
[GTK runtime]: https://github.com/tschoonj/GTK-for-Windows-Runtime-Environment-Installer/releases
|
||
|
||
#### Caching <small>recommended</small> { #caching data-toc-label="Caching" }
|
||
|
||
The [built-in social 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:
|
||
|
||
``` 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
|
||
```
|
||
|
||
[built-in social plugin]: #built-in-social-plugin
|
||
[publishing guide]: ../publishing-your-site.md#with-github-actions
|
||
|
||
#### Meta tags
|
||
|
||
The [built-in social plugin] automatically sets all necessary `meta` tags,
|
||
equivalent to the following two customizations, which you can set manually when
|
||
you don't want to use it:
|
||
|
||
=== ":material-graph: Open Graph"
|
||
|
||
``` html
|
||
{% extends "base.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 %}
|
||
{% 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
|
||
{% extends "base.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 %}
|
||
{% 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
|
||
|
||
## Usage
|
||
|
||
If you want to adjust the title or set a custom description for the social card,
|
||
you can set the front matter `title` and `description` properties, which take
|
||
precedence over the default values.
|
||
|
||
- [Changing the title]
|
||
- [Changing the description]
|
||
|
||
[Changing the title]: ../reference/index.md#setting-the-page-title
|
||
[Changing the description]: ../reference/index.md#setting-the-page-description
|