diff --git a/docs/tutorials/social/basic.md b/docs/tutorials/social/basic.md new file mode 100644 index 00000000000..00fb5f5c7ba --- /dev/null +++ b/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 + +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 + +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)?