Cool_Tools/mkdocs-material
1
0
Fork 0
mirror of https://github.com/squidfunk/mkdocs-material.git synced 2024-11-12 01:50:52 +01:00
Code Issues Releases Wiki Activity

Updated documentation for social cards plugin

Browse Source
This commit is contained in:
squidfunk 2021-07-25 20:36:30 +02:00
parent bb72dceda6
commit 662006bcaf
4 changed files with 97 additions and 25 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

22
CHANGELOG
View File

@ -1,4 +1,4 @@
mkdocs-material-7.2.1+insiders.2.12.0 (2021-07-25)
mkdocs-material-7.2.1+insiders-2.12.0 (2021-07-25)
* Added support for social cards
@ -12,11 +12,11 @@ mkdocs-material-7.2.0 (2021-07-21)
* Added support for search highlighting
* Added support for search sharing (i.e. deep linking)
mkdocs-material-7.1.11+insiders.2.11.1 (2021-07-20)
mkdocs-material-7.1.11+insiders-2.11.1 (2021-07-20)
* Fixed order of tags index, now sorted alphabetically
mkdocs-material-7.1.11+insiders.2.11.0 (2021-07-18)
mkdocs-material-7.1.11+insiders-2.11.0 (2021-07-18)
* Improved Mermaid.js intergration, now stable
* Added support for sequence diagrams
@ -28,7 +28,7 @@ mkdocs-material-7.1.11 (2021-07-18)
* Updated Spanish and Galician translations
mkdocs-material-7.1.10+insiders.2.10.0 (2021-07-10)
mkdocs-material-7.1.10+insiders-2.10.0 (2021-07-10)
* Added support for cookie consent
* Fixed #2807: Back-to-top button not hidden when using sticky tabs
@ -53,7 +53,7 @@ mkdocs-material-7.1.7 (2021-06-06)
* Improved screen reader support
mkdocs-material-7.1.6+insiders.2.9.2 (2021-05-30)
mkdocs-material-7.1.6+insiders-2.9.2 (2021-05-30)
* Moved tags to partial for easier customization
* Added support for hiding tags on any page
@ -65,11 +65,11 @@ mkdocs-material-7.1.6 (2021-05-30)
* Fixed #2429: Version selector not touch-friendly on Android devices
* Fixed #2703: Printed 'Initializing search' albeit ready on mobile
mkdocs-material-7.1.5+insiders.2.9.1 (2021-05-24)
mkdocs-material-7.1.5+insiders-2.9.1 (2021-05-24)
* Added missing guard for linking of content tabs
mkdocs-material-7.1.5+insiders.2.9.0 (2021-05-23)
mkdocs-material-7.1.5+insiders-2.9.0 (2021-05-23)
* Added support for linking of content tabs
@ -77,11 +77,11 @@ mkdocs-material-7.1.5 (2021-05-19)
* Fixed #2655: Details breaking page margins on print
mkdocs-material-7.1.4+insiders.2.8.0 (2021-05-12)
mkdocs-material-7.1.4+insiders-2.8.0 (2021-05-12)
* Added support for boosting pages in search
mkdocs-material-7.1.4+insiders.2.7.2 (2021-05-08)
mkdocs-material-7.1.4+insiders-2.7.2 (2021-05-08)
* Fixed #2638: Warnings shown when using tags plugin without directory URLs
@ -90,11 +90,11 @@ mkdocs-material-7.1.4 (2021-05-06)
* Added support for git-revision-date-localized plugin creation date
* Improved footnote styles on :target and :focus
mkdocs-material-7.1.3+insiders.2.7.1 (2021-05-03)
mkdocs-material-7.1.3+insiders-2.7.1 (2021-05-03)
* Fixed git-revision-date-localized plugin integration (2.7.0 regression)
mkdocs-material-7.1.3+insiders.2.7.0 (2021-05-01)
mkdocs-material-7.1.3+insiders-2.7.0 (2021-05-01)
* Added support for tags (with search integration)

4
docs/insiders/index.md
View File

@ -291,7 +291,9 @@ yearly billing cycle][37]. If for some reason you cannot do that, you could
also create a dedicated GitHub account with a yearly billing cycle, which you
only use for sponsoring (some sponsors already do that).
One-time payments are not eligible for Insiders.
If you have any problems or further questions, don't hesitate to contact me at
sponsors@squidfunk.com. Note that one-time payments are not eligible for
Insiders, but of course, very appreciated.
[37]: https://docs.github.com/en/github/setting-up-and-managing-billing-and-payments-on-github/changing-the-duration-of-your-billing-cycle

8
docs/reference/meta-tags.md
View File

@ -169,4 +169,12 @@ Some further examples, including [Open Graph][1] and [Twitter Cards][11]:
{% endblock %}
```
!!! tip "Automatically generated social cards"
If you don't want to bother with meta tags and social cards yourself, you
can might be interested in the [built-in social cards plugin][12], which
generates beautiful image previews for social media automatically during
the build.
[11]: https://developer.twitter.com/en/docs/tweets/optimize-with-cards/overview/abouts-cards
[12]: ../setup/setting-up-social-cards.md

88
docs/setup/setting-up-social-cards.md
View File

@ -6,19 +6,29 @@ 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,
fonts and logo defined in `mkdocs.yml`.
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][1] ·
[:octicons-cpu-24: Plugin][1] ·
[:octicons-file-code-24: Source][4] ·
[:octicons-cpu-24: Plugin][4] ·
:octicons-beaker-24: Experimental ·
[:octicons-heart-fill-24:{ .mdx-heart } Insiders only][1]{ .mdx-insiders }
[:octicons-heart-fill-24:{ .mdx-heart } Insiders only][4]{ .mdx-insiders }
The [built-in social cards plugin][1] generates a social card image for every
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`:
@ -27,16 +37,16 @@ plugins:
- social
```
For example, the page on [setting up site analytics][2] renders as:
For example, the page on [setting up site analytics][5] renders as:
<figure markdown="1">
[![Social Cards][3]][3]
[![Social Cards][6]][6]
<figcaption markdown="1">
Want to try it out? Copy the current URL and enter it into [Twitter's Card
validator][4] to see how social cards look in action.
validator][7] to see how social cards look in action.
</figcaption>
</figure>
@ -57,7 +67,59 @@ are available:
cards_directory: assets/images/social
```
[1]: ../insiders/index.md
[2]: setting-up-site-analytics.md
[3]: ../assets/screenshots/social-cards.png
[4]: https://cards-dev.twitter.com/validator
[4]: ../insiders/index.md
[5]: setting-up-site-analytics.md
[6]: ../assets/screenshots/social-cards.png
[7]: https://cards-dev.twitter.com/validator
#### Caching
When enabled, the [social cards plugin][8] 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][9], 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
```
[8]: #built-in-social-cards
[9]: ../publishing-your-site.md
## Usage
If you want to adjust the title or set a custom description for the social card,
you can use the [Metadata][10] extension, which takes precedence over the
default values.
- [Changing the title][11]
- [Changing the description][12]
[10]: ../reference/meta-tags.md#metadata
[11]: ../reference/meta-tags.md#setting-the-page-title
[12]: ../reference/meta-tags.md#setting-the-page-description