From 6e50c0ced9cc52960096ea681d6090ae9c021577 Mon Sep 17 00:00:00 2001
From: squidfunk <martin.donath@squidfunk.com>
Date: Wed, 20 Oct 2021 23:02:55 +0200
Subject: [PATCH] Improved social cards documentation

---
 docs/setup/setting-up-social-cards.md | 91 +++++++++++++++++++--------
 1 file changed, 64 insertions(+), 27 deletions(-)

diff --git a/docs/setup/setting-up-social-cards.md b/docs/setup/setting-up-social-cards.md
index 3a751786a..ef89ef1f1 100644
--- a/docs/setup/setting-up-social-cards.md
+++ b/docs/setup/setting-up-social-cards.md
@@ -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