Updated documentation for social cards plugin

Author: squidfunk

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,23 +65,23 @@ 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
 
 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)
 

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
+[email protected]. 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
 

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

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:
 
 <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