From 662006bcafa14cb559c67f74bc254aaa26f59757 Mon Sep 17 00:00:00 2001 From: squidfunk Date: Sun, 25 Jul 2021 20:36:30 +0200 Subject: [PATCH] Updated documentation for social cards plugin --- CHANGELOG | 22 +++---- docs/insiders/index.md | 4 +- docs/reference/meta-tags.md | 8 +++ docs/setup/setting-up-social-cards.md | 88 +++++++++++++++++++++++---- 4 files changed, 97 insertions(+), 25 deletions(-) diff --git a/CHANGELOG b/CHANGELOG index 69ca3526e..5ddec03ee 100644 --- a/CHANGELOG +++ b/CHANGELOG @@ -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) diff --git a/docs/insiders/index.md b/docs/insiders/index.md index 8de6299ca..165201859 100644 --- a/docs/insiders/index.md +++ b/docs/insiders/index.md @@ -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 diff --git a/docs/reference/meta-tags.md b/docs/reference/meta-tags.md index 30b90c990..2ad99c86e 100644 --- a/docs/reference/meta-tags.md +++ b/docs/reference/meta-tags.md @@ -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 diff --git a/docs/setup/setting-up-social-cards.md b/docs/setup/setting-up-social-cards.md index f566f8173..6755dfcd5 100644 --- a/docs/setup/setting-up-social-cards.md +++ b/docs/setup/setting-up-social-cards.md @@ -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:
-[![Social Cards][3]][3] +[![Social Cards][6]][6]
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.
@@ -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