配置社交卡片
Material for MkDocs 可以自动生成漂亮的社交卡片，这些卡片在社交媒体平台上作为链接预览显示。您可以选择多种[预设计布局][默认布局]或创建自定义布局以匹配您独特的风格和品牌。
如何构建自定义社交卡片 by @james-willett – 学习如何自动为每个页面创建完全自定义的社交卡片，完美地与您的品牌匹配！
配置
内置社交插件
插件 | 实验性
内置的社交插件会为每个页面自动生成自定义预览图像。安装所有图像处理的依赖项1并将以下行添加到mkdocs.yml中：
Info
出于这个原因，Material for MkDocs 再次遵循了其使其尽可能简单和强大的核心原则，提供了一个易于使用的框架，使用 Python 图像处理库来构建自定义布局。
可以使用以下配置选项：
enabled
默认值：true – 此选项指定在构建项目时是否启用插件。如果要加快本地构建速度，可以使用环境变量：
``` yaml
plugins:
- social:
enabled: !ENV [CI, false]
```
concurrency
默认值：CPU 数量 – 插件在生成社交卡片时允许使用的 CPU 数量。使用更多的 CPU，插件可以在相同的时间内完成更多的工作，从而更快地完成生成。可以使用以下方式禁用并行处理：
``` yaml
plugins:
- social:
concurrency: 1
```
社交卡片
可以为卡片生成配置选项：
cards
默认值：true – 此选项指定是否生成社交卡片图像。如果要关闭插件，例如在本地构建中，可以使用环境变量：
``` yaml
plugins:
- social:
cards: !ENV [CI, false]
```
cards_dir
默认值：assets/images/social – 此选项指定生成的社交卡片的存储位置。通常情况下，不需要更改此选项，可以使用以下方式更改：
``` yaml
plugins:
- social:
cards_dir: assets/images/social
```
cards_color
已弃用，使用[cards_layout_options][布局选项]
默认值：theme.palette.primary – 此选项指定生成社交卡片时的背景fill和前景text的颜色：
``` yaml
plugins:
- social:
cards_color:
fill: "#0FF1CE"
text: "#FFFFFF"
```
cards_font
已弃用，使用[cards_layout_options][布局选项]
默认值：theme.font.text – 此选项指定渲染社交卡片时要使用的字体，可以是Google Fonts上托管的任何字体：
``` yaml
plugins:
- social:
cards_font: Ubuntu
```
cards_layout_dir
默认值：无 – 此选项指定社交插件应从中解析自定义布局，优先于已包含的布局：
``` yaml
plugins:
- social:
cards_layout_dir: layouts
```
cards_layout
已于 2023 年 5 月 8 日添加
默认值：default – 指定社交卡片应使用的布局规范。插件包含以下布局，这些布局使用了颜色调色板和字体：
default/only/image
plugins:
- social:
cards_layout: default/only/image
cards_layout_options:
background_image: layouts/background.png
此布局仅显示给定的背景图像并按比例缩放：
所有[default][默认布局]布局都使用以下[模板变量]：
config.site_namepage.meta.title或page.titlepage.meta.description或config.site_descriptiontheme.logo或theme.icon.logo
cards_layout_options
默认值：无 – 此选项允许设置布局规范提供的[参数]。对于自定义布局，可以使用此键提供特定于布局的选项，使布局完全可配置。
所有[default][默认布局]布局都公开以下参数：
background_color
设置背景颜色，可以是[CSS 颜色关键字]，也可以是 3、4、6 或 8 位 HEX 颜色代码。支持透明度通道：
background_image
设置背景图像。如果设置了background_color，例如[default][默认布局]布局，图像将使用颜色进行着色（覆盖）。因此，图像的背景颜色必须（部分）透明，以使图像可见：
plugins:
- social:
cards_layout_options:
background_color: "#00000000"
background_image: layouts/background.png
图像的路径必须相对于项目根目录定义。
color
设置前景颜色，可以是[CSS 颜色关键字]，也可以是 3、4、6 或 8 位 HEX 颜色代码。颜色主要用于着色文本和图标：
font_family
设置字体系列。这将覆盖作为主题配置的字体。内置社交插件将自动从Google Fonts下载字体文件：
cards_include
默认值：无 – 此选项允许仅为文档的某些子部分生成社交卡片，例如为多个插件实例的不同子文件夹生成不同的卡片：
cards_exclude
默认值：无 – 此选项允许从生成社交卡片中排除某些文档的子部分：
调试
以下调试配置选项可用：
debug
默认值：false – 此选项启用特殊的调试模式，该模式使用轮廓和x和y偏移量来渲染每个图层，以便了解布局的组成方式，并可选择呈现网格以更轻松地对齐：
启用调试模式
禁用
debug_on_build
默认值：false – 构建站点时是否自动禁用调试模式。可以使用以下方式更改：
此设置仅用于作为安全措施，以确保在构建站点时社交卡片绝对不会意外包含点网格或图层轮廓。
debug_grid
默认值：true – 此选项在启用debug模式时启用点网格的渲染（参见上面的屏幕截图）。可以使用以下方式关闭网格：
debug_grid_step
默认值：32 – 此选项指定网格的步长（以像素为单位），如果启用，可以用于对齐元素。可以使用以下方式更改：
debug_color
默认值：grey – 此选项设置在启用debug模式时渲染的图层轮廓和网格的颜色。可以使用以下方式更改：
缓存
内置社交插件实现了智能缓存机制，确保只有在缓存中不存在社交卡片或其内容发生更改时才重新生成社交卡片。以下是缓存的配置选项：
cache
默认值：true – 插件在开始生成作业之前是否查询其缓存以查找现有的生成结果。通常情况下，不需要更改此设置，除非调试插件本身。可以使用以下方式禁用缓存：
cache_dir
默认值：.cache/plugins/social – 此选项指定插件缓存的文件系统位置。通常情况下，不需要更改此设置，除非调试插件本身。可以使用以下方式更改缓存目录：
默认情况下，所有实现缓存的内置插件都会在与mkdocs.yml相同的文件夹中创建一个.cache文件夹，并创建子文件夹以避免相互干扰。如果使用多个插件实例，则可能需要更改此设置。
[发布指南]: ../publishing-your-site.md#使用 GitHub Actions 发布
用法
如果要调整标题或为社交卡片设置自定义描述，可以设置前置属性title和description，这些属性优先于默认值。
选择字体
某些字体不包含 CJK 字符，比如默认字体Roboto。如果您的site_name、site_description或页面标题包含 CJK 字符，请从Google Fonts中选择一个包含 CJK 字符的字体，例如Noto Sans字体系列之一：
更改布局
实验性
如果要为单个页面（例如您的首页）使用不同样的社交卡片布局，您可以在mkdocs.yml中使用以下配置选项来更改布局：
上述配置将使用名为custom.html的自定义布局模板。您可以创建一个名为layouts的文件夹，并在其中放置您的自定义布局模板文件。然后，您可以根据自己的需求编辑该模板文件，以实现完全自定义的社交卡片布局。
请注意，自定义布局需要一些 HTML 和 CSS 编程知识。您可以参考自定义社交卡片布局文档以获取更多详细信息和示例。