Add AI documentation skills
This commit is contained in:
@@ -0,0 +1,199 @@
|
||||
# Basic social cards
|
||||
|
||||
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 meta data in the headers of your site's pages 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, when 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 has 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, 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 you set for the whole site, either
|
||||
through the `theme.logo` or the `theme.icon.logo` setting. The difference
|
||||
between the two is that the `theme.icon.logo` version will directly embed the
|
||||
logo's SVG code into the HTML, allowing it to inherit CSS color settings. When
|
||||
you use `theme.logo`, the Material includes the logo as an image.
|
||||
|
||||
You can set your own logo specific for the social cards as well. The path used
|
||||
is relative to your project root and needs to point to an SVG file or a pixel
|
||||
image. It should be rectangular and have a transparent background.
|
||||
|
||||
!!! 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.
|
||||
|
||||
Also, the background color gets rendered *on top of* the background image,
|
||||
allowing you to use a transparent color to tint an image. To use just the image,
|
||||
use the color value `transparent`.
|
||||
|
||||
!!! example "Add background image"
|
||||
|
||||
```yaml hl_lines="4 5"
|
||||
plugins:
|
||||
- social:
|
||||
cards_layout_options:
|
||||
background_image: layouts/background.png
|
||||
background_color: transparent
|
||||
```
|
||||
|
||||
The path to the background image is resolved from the root of your project,
|
||||
so this is where you should make the `layouts` directory and place the
|
||||
background image. The default site of the social cards included with the plugin
|
||||
is 1200x630 pixels, so choose an image that size or one that scales well to it.
|
||||
|
||||
## Additional layouts and styles
|
||||
|
||||
The social plugin provides additional layouts as well as the option to configure
|
||||
different styles for different (kinds of) pages. It 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. Note that you can override the background image by setting it
|
||||
to `null` here since it is not visible anyway because of the opaque coloring.
|
||||
|
||||
```yaml
|
||||
---
|
||||
icon: material/calendar-plus
|
||||
social:
|
||||
cards_layout_options:
|
||||
background_image: null
|
||||
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
|
||||
|
||||
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 to affect a whole set of pages.
|
||||
|
||||
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
|
||||
---
|
||||
```
|
||||
|
||||
## What's next?
|
||||
|
||||
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)?
|
||||
@@ -0,0 +1,142 @@
|
||||
# Custom cards
|
||||
|
||||
The social plugin allows you to define custom layouts for your social cards
|
||||
to suit your specific needs if the configuration options are not enough.
|
||||
For example, you may want to define a social card to advertise a new release
|
||||
of your product. It should have an icon indicating a launch announcement as
|
||||
well as the version number of the release on the card.
|
||||
|
||||
## Setup
|
||||
|
||||
You can either design a custom layout from scratch or use an existing layout
|
||||
as the basis that you add to or otherwise modify. In this tutorial, you will
|
||||
use the default layout as the basis.
|
||||
|
||||
!!! example "Copy default layout to customize"
|
||||
|
||||
Copy the default social card layout from your installation of Material
|
||||
for MkDocs to a new directory `layouts`. The instructions below assume you
|
||||
are in your project root and have a virtual environment within this. The
|
||||
path on your machine, of course, may differ.
|
||||
|
||||
```
|
||||
$ mkdir layouts
|
||||
$ cp venv/lib/python3.12/site-packages/material/plugins/social/templates/default/variant.yml \
|
||||
layouts/release.yml
|
||||
```
|
||||
|
||||
Before customizing the social cards, you need to tell the plugin where to
|
||||
find them as well as tell MkDocs to watch for any changes. Add the following
|
||||
to the plugin configuration in your `mkdocs.yml`:
|
||||
|
||||
``` yaml hl_lines="2-6"
|
||||
plugins:
|
||||
- social:
|
||||
cards_layout_dir: layouts
|
||||
|
||||
watch:
|
||||
- layouts
|
||||
```
|
||||
|
||||
Have a look at the contents of `release.yml`. You will see that there are:
|
||||
|
||||
* a number of definitions of content pulled from the site,
|
||||
* definitions of tags that end up in the `meta` elements in the page header
|
||||
of each page,
|
||||
* a specification that consists of a number of layers that the social plugin
|
||||
applies on top of each other in the order in which they are defined.
|
||||
|
||||
## Define page metadata
|
||||
|
||||
In the following, you will add a version number to the social card. This
|
||||
assumes you have a changelog page with information about each release.
|
||||
Add the version number of the latest version to the page header (so it does
|
||||
not need to be parsed out of the Markdown content):
|
||||
|
||||
!!! example "Defining the release data"
|
||||
|
||||
Create a page `docs/changelog.md` with the following content:
|
||||
|
||||
```yaml
|
||||
---
|
||||
icon: material/rocket-launch-outline
|
||||
social:
|
||||
cards_layout: release
|
||||
cards_layout_options:
|
||||
title: New release!
|
||||
latest: 1.2.3
|
||||
---
|
||||
|
||||
# Releases
|
||||
```
|
||||
|
||||
## Extract page metadata
|
||||
|
||||
With the data defined in the page header, you can now add code to the layout
|
||||
that pulls it out and makes it available to render later on. This is to separate
|
||||
the data manipulation from the actual layout instructions and so make the
|
||||
layout file easier to read.
|
||||
|
||||
!!! example "Adding data definitions"
|
||||
|
||||
Add the following at the top of the layout file:
|
||||
|
||||
```yaml hl_lines="2-9"
|
||||
definitions:
|
||||
- &latest >-
|
||||
{%- if 'latest' in page.meta %}
|
||||
{{ page.meta['latest']}}
|
||||
{%- else -%}
|
||||
No release version data defined!
|
||||
{%- endif -%}
|
||||
```
|
||||
|
||||
The code presented here checks whether the page header contains the necessary
|
||||
entries and spits out a message to the social card if not. Unfortunately, there
|
||||
is no straightforward way to raise an exception or log an error, so the messages
|
||||
merely appear in the social card produced.
|
||||
|
||||
## Add release version layer
|
||||
|
||||
The next step is to use these data definitions in a new layer and add it to the
|
||||
ones already present.
|
||||
|
||||
!!! example "Render release version"
|
||||
|
||||
Finally, add the following to end of the custom layout:
|
||||
|
||||
```yaml
|
||||
- size: { width: 990, height: 50 }
|
||||
offset: { x: 50, y: 360 }
|
||||
typography:
|
||||
content: *latest
|
||||
align: start
|
||||
color: *color
|
||||
```
|
||||
|
||||
You should now see the social plugin use the custom layout on the changelog page
|
||||
you set up.
|
||||
|
||||
## Adjust layout
|
||||
|
||||
Finally, the rocket icon used for the changelog page is not quite in the right
|
||||
position. Find the please where the `page_icon` variable is used to create the
|
||||
page icon layer and adjust the horizontal position to 600 instead of 800.
|
||||
|
||||
!!! tip "Debugging layout files"
|
||||
|
||||
Should you find that your layouts are causing your MkDocs build to fail,
|
||||
there are a number of things you can do:
|
||||
|
||||
1. Run Mkdocs with the `--verbose` option to get more detailed reporting.
|
||||
2. Comment out things you recently added or that you suspect are the cause
|
||||
3. Install the `jinja2` command-line tool with `pip install Jinja2` and
|
||||
run it over your layout file, for example: `jinja2 event.yml`.
|
||||
|
||||
## What's next?
|
||||
|
||||
If you do not have a blog yet, why not check out the
|
||||
[blog tutorials](../index.md#blogs) and learn how to set one up? The social
|
||||
plugin will help you draw attention to your posts on social media.
|
||||
|
||||
Check out the [other tutorials](../index.md) we have prepared for you.
|
||||
Reference in New Issue
Block a user