+ basic social cards tutorial

docs/tutorials/social/basic.md

@@ -0,0 +1,196 @@
+# Social cards tutorial
+
+Social cards are images that other systems such as social media can display as
+a preview for content linked to. It is easy to get started with the social
+plugin, true to the motto of Material with MkDocs: "batteries included."
+
+## Basics
+
+Before you start, there are just a couple of [dependencies to install]. These
+are libraries for image processing that the plugin needs to produce the social
+cards, as well as their Python bindings.
+
+[dependencies to install]: https://squidfunk.github.io/mkdocs-material/plugins/requirements/image-processing/
+
+With those prerequisites met, it is simply a matter of activating the plugin,
+which will:
+
+* produce the social cards as PNG images for each page in your site;
+* create page meta data in the header that will provide social media systems
+  with key information and tell them how to find the social card image.
+
+!!! example "Add social cards"
+
+    Simply add the social plugin to your list of plugins:
+
+    ```yaml hl_lines="3"
+        plugins:
+            - search
+            - social
+            - ...
+    ```
+
+    Now, then you run `mkdocs build` and look at the `site` directory, you will
+    see that it contains subfolders under `assets/images/social` that reflect
+    the structure of your Markdown files. Each page has a corresponding PNG file
+    that contains the social card image.
+
+    Have a look at the generated HTML and you will see the metadata produced in
+    the `head` element, including one entry that points to the image.
+
+## Background color
+
+The social plugin configuration options for changing aspects such as colors,
+images, fonts, logos, the title, even the description. You can configure them
+for all social cards in the `mkdocs.yml` and, in the Insiders Edition, they can
+be overridden in the page header for individual pages.
+
+!!! example "Change the background color"
+
+    To change the background color to an attention-grabbing hot pink,
+    you might add:
+
+    ```yaml hl_lines="4-5"
+    plugins:
+    ...
+    - social:
+        cards_layout_options:
+            background_color: "#ff1493"
+    ```
+
+## Logos
+
+By default, the plugin uses the logo that set for the whole site, either
+through the `theme.logo` or the `theme.icon.logo` setting. You can set your
+own logo specific for the social cards if you want this to be different. The
+path used is relative to your project root and needs to point to an SVG file
+or a pixel image of appropriate size and with transparent background.
+
+!!! tip "Question"
+    **@squidfunk**, not sure about the last sentence, what are the requirements?
+
+!!! example "Set your own logo"
+
+    ```yaml hl_lines="3-4"
+    plugins:
+    - social:
+        cards_layout_options:
+          logo: docs/assets/images/ourlogo.png
+    ```
+
+## Background images
+
+In addition to adding your own logo, the most impactful way to personalize your
+social cards is to add a background image instead of the default solid color
+background. Make sure you choose one that will contrast well with the other
+elements of the card.
+
+!!! example "Add background image"
+
+    ```yaml hl_lines="4 5"
+    plugins:
+    - social:
+        cards_layout_options:
+          background_image: layouts/background.png
+          background_color: transparent
+    ```
+
+## Additional layouts and styles <!-- md:sponsors -->
+
+The Insiders Edition provides additional layouts as well as the option to
+configure different styles for different (kinds of) pages.
+
+The Insiders Edition comes with a number of additional layouts for the social
+cards. For example, the `default/variant` layout adds a page icon to the card.
+You can use this to distinguish social cards visually, depending on what kind
+of page you are sharing.
+
+For example, imagine you have a set of pages that advertise events and you want
+to include a calendar icon as a visual indication that a card advertises an
+event. In the following, you will set up a directory for event pages and use
+the meta plugin to assign them a calendar icon.
+
+!!! example "Social cards for event pages"
+
+    First, create a directory in your `docs` directory to hold the event pages:
+
+    ```
+    mkdir docs/events
+    ```
+
+    Then, add a file `.meta.yml` inside this new directory with settings for
+    the page icon and a hot pink background color that will stand out on
+    social media:
+
+    ```yaml
+    ---
+    icon: material/calendar-plus
+    social:
+      cards_layout_options:
+        background_color: "#ff1493"
+    ---
+    ```
+
+    Now add a page within the `docs/events` directoy. It does not need to have
+    any special content, just a top level header.
+
+    To turn on the `default/variant` layout in `mkdocs.yml`, add the
+    `cards_layout` option and also add the meta plugin:
+
+    ```yaml
+    plugins:
+      - meta
+      - social:
+          cards_layout: default/variant
+    ```
+
+    After running `mkdocs build`, you can see that the social card at
+    `site/assets/images/social/events/index.png` features the page icon.
+
+Note that the icon will also appear next to the navigation element for the
+page. If that is not what you want then you will need to modify the social
+card template to gets its icons from another source. You can learn how to
+do this in the [custom social cards tutorial](custom.md).
+
+## Per-page settings <!-- md:sponsors -->
+
+With the Insiders Edition, you can customize the card layout for each
+page by adding settings to the page header. You have effectively done this
+in the previous exercise, but using the meta plugin so simplify things.
+Say that in addition to regular events you also have the odd webinar and
+for this you want to set a different icon and also set the description to
+indicate that the event is part of the webinar series.
+
+!!! example "Override card style in page header"
+
+    Add the following to the top of the page in `docs/events` or create a new
+    one:
+
+    ```yaml
+    ---
+    icon: material/web
+    social:
+    cards_layout_options:
+        description: Our Webinar Series
+    ---
+    ```
+
+## Using include and exclude
+
+!!! tip "Question"
+
+    **@suidfunk**, do you have a killer use case for the `card_include`
+    and `cards_exclude` options? I realize that what I did above with the
+    meta plugin could also be done using these.
+
+## What's next?
+
+With the Insiders Edition, you can also define custom layouts if the
+configuration options introduced above as not enough to meet your needs.
+Continue to the [custom social cards tutorial](custom.md) if you want to
+find out how to do this.
+
+Social cards are particularly useful for blog posts. If you have a blog,
+you need to do nothing more than to turn on both plugins to create social cards
+to advertise your latest blog posts. If you do not have one yet but would like
+to, why not check out the [blog tutorials](../index.md#blogs)?