基本社交卡¶
¥Basic social cards¶
社交卡片是其他系统（例如社交媒体）可以显示为链接内容预览的图像。社交插件的使用非常简单，完全符合 Material with MkDocs 的座右铭：“功能齐全”。
¥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¶
开始之前，只需安装几个依赖项。这些是插件生成社交卡片所需的图像处理库，以及它们的 Python 绑定。
¥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.
满足这些先决条件后，只需激活插件即可：
¥With those prerequisites met, it is simply a matter of activating the plugin, which will:
为您网站的每个页面制作 PNG 图像形式的社交卡片；
¥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.
添加社交卡
¥Add social cards
只需将社交插件添加到您的插件列表中：
¥Simply add the social plugin to your list of plugins:
现在，运行mkdocs build并查看site目录，你会发现assets/images/social下包含子文件夹，这些子文件夹反映了 Markdown 文件的结构。每个页面都有一个对应的 PNG 文件，其中包含社交卡片图片。
¥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.
查看生成的 HTML，您将看到在head元素中生成的元数据，其中包括一个指向图像的条目。
¥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¶
社交插件提供配置选项，可用于更改颜色、图片、字体、徽标、标题甚至描述等方面。您可以在mkdocs.yml中为所有社交卡片配置这些选项，在 Insiders 版本中，还可以在单个页面的页眉中覆盖这些选项。
¥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, in the Insiders Edition, they can be overridden in the page header for individual pages.
更改背景颜色
¥Change the background color
要将背景颜色更改为引人注目的粉红色，您可以添加：
¥To change the background color to an attention-grabbing hot pink, you might add:
徽标¶
¥Logos¶
默认情况下，插件会使用您为整个网站设置的徽标，可以通过theme.logo或theme.icon.logo设置。两者的区别在于， theme.icon.logo版本会直接将徽标的 SVG 代码嵌入到 HTML 中，从而允许其继承 CSS 颜色设置。当您使用theme.logo时，Material 会将徽标作为图像包含在内。
¥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.
您还可以为社交卡片设置专属的徽标。使用的路径是相对于项目根目录的路径，并且需要指向一个 SVG 文件或像素图像。它应该是矩形，并且具有透明背景。
¥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.
设置您自己的徽标
¥Set your own logo
背景图像¶
¥Background images¶
除了添加自己的logo之外，最有效的个性化社交卡片方法是添加背景图片，而不是默认的纯色背景。确保选择的背景图片能够与卡片的其他元素形成鲜明对比。
¥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.
此外，背景色会渲染在背景图像之上，这样你就可以使用透明色来给图像着色。如果只使用图像，请使用颜色值transparent 。
¥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.
添加背景图片
¥Add background image
背景图片的路径是从项目根目录解析的，因此您应该在此处创建layouts目录并放置背景图片。插件附带的社交卡片默认尺寸为 1200x630 像素，因此请选择适合该尺寸或能够完美缩放的图片。
¥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¶
Insiders Edition 提供了额外的布局以及为不同（类型）页面配置不同样式的选项。
¥The Insiders Edition provides additional layouts as well as the option to configure different styles for different (kinds of) pages.
Insiders 版附带多种社交卡片布局。例如， default/variant布局会在卡片中添加一个页面图标。您可以使用该图标在视觉上区分不同的社交卡片，具体取决于您共享的页面类型。
¥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.
活动页面的社交卡片
¥Social cards for event pages
首先，在您的docs目录中创建一个目录来保存事件页面：
¥First, create a directory in your docs directory to hold the event pages:
然后，在这个新目录中添加一个.meta.yml文件，其中包含页面图标和在社交媒体上醒目的亮粉色背景颜色的设置。请注意，您可以通过在此处将背景图像设置为null来覆盖它，因为由于颜色不透明，它无论如何都是不可见的。
¥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.
---
icon: material/calendar-plus
social:
cards_layout_options:
background_image: null
background_color: "#ff1493"
---
现在在docs/events目录中添加一个页面。它不需要包含任何特殊内容，只需添加一个顶级标题即可。
¥Now add a page within the docs/events directoy. It does not need to have any special content, just a top level header.
要在mkdocs.yml中打开default/variant布局，请添加cards_layout选项并添加元插件：
¥To turn on the default/variant layout in mkdocs.yml, add the cards_layout option and also add the meta plugin:
运行mkdocs build后，您可以看到site/assets/images/social/events/index.png上的社交卡片具有页面图标。
¥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.
每页设置¶
¥Per-page settings¶
在 Insiders 版本中，您可以通过在页面标题中添加设置来自定义每个页面的卡片布局。您在上一个练习中已经有效地完成了此操作，只不过这次使用了元插件来影响整个页面集。
¥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 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.
覆盖页眉中的卡片样式
¥Override card style in page header
将以下内容添加到docs/events页面顶部或创建一个新页面：
¥Add the following to the top of the page in docs/events or create a new one:
下一步是什么？¶
¥What's next?¶
如果上述配置选项无法满足您的需求，您还可以在 Insiders 版本中自定义布局。如果您想了解如何操作，请继续阅读自定义社交卡片教程。
¥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 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?