mirror of
https://github.com/squidfunk/mkdocs-material.git
synced 2024-06-14 11:52:32 +03:00
145 lines
4.4 KiB
Markdown
145 lines
4.4 KiB
Markdown
---
|
||
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
|
||
MkDocs can generate beautiful social cards automatically, using the [colors][1],
|
||
[fonts][2] and [logo][3][^1] defined in `mkdocs.yml`.
|
||
|
||
[^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.
|
||
|
||
[1]: changing-the-colors.md#primary-color
|
||
[2]: changing-the-fonts.md#regular-font
|
||
[3]: changing-the-logo-and-icons.md#logo
|
||
|
||
## Configuration
|
||
|
||
### Built-in social cards
|
||
|
||
[:octicons-file-code-24: Source][4] ·
|
||
[:octicons-cpu-24: Plugin][4] ·
|
||
:octicons-beaker-24: Experimental ·
|
||
[:octicons-heart-fill-24:{ .mdx-heart } Insiders only][4]{ .mdx-insiders }
|
||
|
||
The [built-in social cards plugin][4] generates a social card image for every
|
||
page and adds the necessary meta tags, so it's displayed on social media when
|
||
shared. Enable it via `mkdocs.yml`:
|
||
|
||
``` yaml
|
||
plugins:
|
||
- social
|
||
```
|
||
|
||
For example, the page on [setting up site analytics][5] renders as:
|
||
|
||
<figure markdown="1">
|
||
|
||
[![Social Cards][6]][6]
|
||
|
||
<figcaption markdown="1">
|
||
|
||
Want to try it out? Copy the current URL and paste it into [Twitter's Card
|
||
validator][7] to see how social cards look in action.
|
||
|
||
</figcaption>
|
||
</figure>
|
||
|
||
This is a built-in plugin, which means that no third-party plugin needs to be
|
||
installed, as Material for MkDocs already bundles it. The following options
|
||
are available:
|
||
|
||
`cards_color`{ #cards_color } :material-new-box:
|
||
|
||
: :octicons-milestone-24: Default: _automatically set based on [primary
|
||
color][8]_ – This option specifies which colors to use for the background
|
||
`fill` and foreground `text` when generating the social card.
|
||
|
||
``` yaml
|
||
plugins:
|
||
- social:
|
||
cards_color:
|
||
fill: "#0FF1CE"
|
||
text: "#FFFFFF"
|
||
```
|
||
|
||
Note that the values for `fill` and `text` can either be HEX color values
|
||
(e.g. `#0FF1CE`, must be enclosed in quotes) or CSS color keywords (e.g.
|
||
`red`, `green`, etc.).
|
||
|
||
`cards_directory`{ #cards_directory }
|
||
|
||
: :octicons-milestone-24: Default: `assets/images/social` – This option
|
||
specifies where the generated social card images will be written to. It
|
||
should normally not be necessary to change this option.
|
||
|
||
``` yaml
|
||
plugins:
|
||
- social:
|
||
cards_directory: assets/images/social
|
||
```
|
||
|
||
[4]: ../insiders/index.md
|
||
[5]: setting-up-site-analytics.md
|
||
[6]: ../assets/screenshots/social-cards.png
|
||
[7]: https://cards-dev.twitter.com/validator
|
||
[8]: changing-the-colors.md#primary-color
|
||
|
||
#### Caching
|
||
|
||
When enabled, the [social cards plugin][9] 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][10], 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
|
||
```
|
||
|
||
[9]: #built-in-social-cards
|
||
[10]: ../publishing-your-site.md#with-github-actions
|
||
|
||
## Usage
|
||
|
||
If you want to adjust the title or set a custom description for the social card,
|
||
you can use the [Metadata][11] extension, which takes precedence over the
|
||
default values.
|
||
|
||
- [Changing the title][12]
|
||
- [Changing the description][13]
|
||
|
||
[11]: ../reference/meta-tags.md#metadata
|
||
[12]: ../reference/meta-tags.md#setting-the-page-title
|
||
[13]: ../reference/meta-tags.md#setting-the-page-description
|