mirror of
https://github.com/squidfunk/mkdocs-material.git
synced 2024-06-14 11:52:32 +03:00
Improved social cards documentation
This commit is contained in:
squidfunk
parent
55609b8a04
commit
6e50c0ced9
@ -7,7 +7,20 @@ template: overrides/main.html
|
||||
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]
|
||||
[palette.primary], [fonts][font.text] and [logo][^1] defined in `mkdocs.yml`.
|
||||
[palette.primary], [fonts][font.text] 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`)
|
||||
@ -18,6 +31,9 @@ MkDocs can generate beautiful social cards automatically, using the [colors]
|
||||
[palette.primary]: changing-the-colors.md#primary-color
|
||||
[font.text]: 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
|
||||
|
||||
@ -28,36 +44,29 @@ MkDocs can generate beautiful social cards automatically, using the [colors]
|
||||
:octicons-cpu-24: Plugin ·
|
||||
:octicons-beaker-24: Experimental
|
||||
|
||||
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.
|
||||
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.
|
||||
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
|
||||
```
|
||||
|
||||
For example, the page on [setting up site analytics] renders as:
|
||||
|
||||
<figure markdown>
|
||||
|
||||
[![Social cards preview]][Social cards preview]
|
||||
|
||||
<figcaption markdown>
|
||||
|
||||
Want to try it out? Copy the current URL and paste it into [Twitter's Card
|
||||
validator] to see how social cards look in action.
|
||||
|
||||
</figcaption>
|
||||
</figure>
|
||||
|
||||
The following configuration options are available:
|
||||
|
||||
`cards`{ #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 [SOCIAL_CARDS, false]
|
||||
```
|
||||
|
||||
`cards_color`{ #cards-color }
|
||||
|
||||
: [:octicons-tag-24: insiders-2.13.0][Insiders] · :octicons-milestone-24:
|
||||
@ -89,13 +98,41 @@ The following configuration options are available:
|
||||
```
|
||||
|
||||
[Insiders]: ../insiders/index.md
|
||||
[dependencies]: #dependencies
|
||||
[site_url]: https://www.mkdocs.org/user-guide/configuration/#site_url
|
||||
[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
|
||||
[meta tags]: #meta-tags
|
||||
[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
|
||||
|
||||
#### Dependencies
|
||||
|
||||
Two Python packages are installed alongside to generate the social preview
|
||||
images, both of which are based on the [Cairo Graphics] library:
|
||||
|
||||
- [Pillow] – Python imaging library
|
||||
- [CairoSVG] – Converter for `*.svg` files
|
||||
|
||||
In order for the [built-in social cards] plugin to work, follow the
|
||||
[installation guide] for the [Cairo Graphics] library for your operating system,
|
||||
and make sure that `zlib`, `libjpeg`, `libfreetype` and `libffi` are installed.
|
||||
Otherwise you might see warnings such as:
|
||||
|
||||
```
|
||||
no library called "cairo" was found
|
||||
no library called "libcairo-2" was found
|
||||
cannot load library 'libcairo.so.2': error 0x7e
|
||||
cannot load library 'libcairo.2.dylib': error 0x7e
|
||||
cannot load library 'libcairo-2.dll': error 0x7e
|
||||
```
|
||||
|
||||
_Don't want to bother? The [Docker image] for Insiders comes with all
|
||||
dependencies pre-installed._
|
||||
|
||||
[Cairo Graphics]: https://www.cairographics.org/
|
||||
[Pillow]: https://pillow.readthedocs.io/
|
||||
[CairoSVG]: https://cairosvg.org/
|
||||
[installation guide]: https://www.cairographics.org/download/
|
||||
[Docker image]: ../insiders/getting-started.md#with-docker
|
||||
|
||||
#### Caching <small>recommended</small> { #caching data-toc-label="Caching" }
|
||||
|
||||
The [built-in social cards] plugin automatically fetches the fonts you define
|
||||
|
||||
Loading…
Reference in New Issue
Block a user