设置社交卡片¶

MkDocs 的 Material 可以自动为您的文档创建美观的社交卡片，这些卡片在社交媒体平台上显示为链接预览。您可以从多个 预设计布局 中选择，或创建 [自定义布局] 以匹配您的独特风格和品牌。

如何构建自定义社交卡片 由 @james-willett – 24分钟 – 学习如何自动创建完全自定义的社交卡片，使每个页面完美匹配您的品牌！

配置¶

内置社交插件¶

8.5.0 create-social-cards

内置社交插件会自动为每个页面生成自定义预览图像。安装所有 图像处理依赖项 并将以下行添加到 mkdocs.yml 中：

plugins:
  - social

有关所有设置的列表，请参考 插件文档。

site_url: https://example.com

用法¶

如果您想调整社交卡片的标题或设置自定义描述，可以设置前置信息 title 和 description 属性，这些属性优先于默认值，或者使用：

• cards_layout_options.title
• cards_layout_options.description

选择字体¶

某些字体不包含 CJK 字符，例如 默认字体 Roboto。如果您的 site_name、site_description 或页面标题包含 CJK 字符，请从 Google Fonts 中选择另一种包含 CJK 字符的字体，例如 Noto Sans 字体系列中的一种：

plugins:
  - social:
      cards_layout_options:
        font_family: Noto Sans SC

plugins:
  - social:
      cards_layout_options:
        font_family: Noto Sans TC

plugins:
  - social:
      cards_layout_options:
        font_family: Noto Sans JP

plugins:
  - social:
      cards_layout_options:
        font_family: Noto Sans KR

更改布局¶

9.7.0

如果您想为单个页面（例如您的登录页面）使用不同的布局，可以使用 social 前置信息属性与 cards_layout 键一起使用，正如在 mkdocs.yml 中一样：

---
social:
  cards_layout: custom
---

# 页面标题
...

您可以对文档的整个子树应用这些更改，例如，通过使用 内置元插件 为您的博客和 API 参考生成不同的社交卡片。

参数化布局¶

9.7.0

除了更改整个布局外，您还可以覆盖布局所暴露的所有选项。这意味着您可以使用自定义前置信息属性参数化社交卡片，例如 tags、date、author 或任何您能想到的内容。只需定义 cards_layout_options：

---
social:
  cards_layout_options:
    background_color: blue # 更改背景颜色
    background_image: null # 移除背景图像
---

# 页面标题
...

您可以对文档的整个子树应用这些更改，例如，通过使用 内置元插件 为您的博客和 API 参考生成不同的社交卡片。

禁用社交卡片¶

9.7.0

如果您希望禁用某个页面的社交卡片，只需将以下内容添加到 Markdown 文档的前置信息中：

---
social:
  cards: false
---

# 页面标题
...

自定义¶

9.7.0

层 0

层 1

层 2

层 3

层 4

层 5

社交卡片由多个层组成，类似于它们在图形设计软件（如 Adobe Photoshop）中的表示方式。由于每个页面生成的卡片中有许多层是相同的（例如背景或徽标），内置社交插件可以自动去重层并仅渲染一次，从而显著加快卡片生成速度。生成的卡片会被缓存，以确保仅在其内容更改时重新生成。

布局使用 YAML 语法编写。在开始创建自定义布局之前，最好先 研究预设计布局，以便更好地理解它们的工作原理。然后，创建一个新布局并在 mkdocs.yml 中引用它：

size: { width: 1200, height: 630 }
layers: []

plugins:
  - social:
      cards_layout_dir: layouts
      cards_layout: custom
      debug: true

请注意，.yml 文件扩展名应省略。接下来，运行 mkdocs serve，查看 .cache 目录如何填充生成的卡片。在编辑器中打开任何卡片，以便您可以立即看到更改。由于我们尚未定义任何层，因此卡片是透明的。

以下部分解释如何创建自定义布局。

尺寸和偏移¶

每个层都有一个关联的尺寸和偏移量，单位为像素。size 由 width 和 height 属性定义，offset 由 x 和 y 属性定义：

size: { width: 1200, height: 630 }
layers:
  - size: { width: 1200, height: 630 }
    offset: { x: 0, y: 0 }

如果省略 size，则默认为布局的大小。如果省略 offset，则默认为左上角，即默认的 origin。保存布局并重新加载渲染：

由于我们在 mkdocs.yml 中启用了 debug 模式，因此可以看到层的轮廓和网格。左上角显示层索引和偏移量，这对于对齐和构图非常有用。

原点¶

9.7.0

x 和 y 值的 origin 可以更改，以便将层对齐到布局的边缘或角落之一，例如，将其对齐到布局的右下角：

size: { width: 1200, height: 630 }
layers:
  - size: { width: 1200, height: 630 }
    offset: { x: 0, y: 0 }
    origin: end bottom

下表显示了支持的值：

背景¶

每个层可以分配一个背景颜色和图像。如果同时给出两者，则颜色将在图像上渲染，从而允许半透明的着色背景：

size: { width: 1200, height: 630 }
layers:
  - background:
      color: "#4051b5"

size: { width: 1200, height: 630 }
layers:
  - background:
      image: layouts/background.png

size: { width: 1200, height: 630 }
layers:
  - background:
      image: layouts/background.png
      color: "#4051b5ee" # (1)!

背景图像会自动缩放以适应层，同时保持纵横比。请注意，我们省略了 size 和 offset，因为我们希望填充社交卡片的整个区域。

排版¶

现在，我们可以添加动态排版，这些排版来自 Markdown 文件——这是 内置社交插件 的实际存在理由。Jinja 模板 用于渲染文本字符串，然后添加到图像中：

size: { width: 1200, height: 630 }
layers:
  - size: { width: 832, height: 310 }
    offset: { x: 62, y: 160 }
    typography:
      content: "{{ page.title }}" # (1)!
      align: start
      color: white
      line:
        amount: 3
        height: 1.25
      font:
        family: Roboto
        style: Bold

1. 在 Jinja 模板 中可以使用以下变量：

   • config.*
   • page.*
   • [layout.*][layout options]

   作者可以自由定义 layout.* 选项，这些选项可以用于从 mkdocs.yml 向布局传递任意数据。

这将渲染一个文本层，显示页面的标题，行高为 1.25，最大行数为 3 行。插件会自动根据行高、行数和字体度量（如上升和下降）计算字体大小。¹ 这将渲染：

溢出¶

如果文本溢出层，则有两种可能的行为：文本要么自动截断并用省略号缩短，要么自动缩小文本以适应层：

# 如果我们使用一个非常长的标题，我们可以看到文本将如何被截断

虽然使用省略号截断是默认行为，但可以通过将 overflow 设置为 shrink 来启用自动缩小：

size: { width: 1200, height: 630 }
layers:
  - size: { width: 832, height: 310 }
    offset: { x: 62, y: 160 }
    typography:
      content: "{{ page.title }}"
      overflow: shrink
      align: start
      color: white
      line:
        amount: 3
        height: 1.25
      font:
        family: Roboto
        style: Bold

对齐¶

文本可以对齐到层的所有角落和边缘。例如，如果我们想将文本对齐到层的中间，可以将 align 设置为 start center，这将渲染为：

下表显示了支持的值：

字体¶

内置社交插件 与 Google Fonts 集成，并会自动为您下载字体文件。font 属性接受 family 和 style 属性，其中 family 必须设置为字体名称，style 设置为支持的字体样式之一。例如，将 family 设置为 Roboto 将自动下载以下文件：

.cache/plugins/social/fonts
└─ Roboto/
    ├─ Black.ttf
    ├─ Black Italic.ttf
    ├─ Bold.ttf
    ├─ Bold Italic.ttf
    ├─ Italic.ttf
    ├─ Light.ttf
    ├─ Light Italic.ttf
    ├─ Medium.ttf
    ├─ Medium Italic.ttf
    ├─ Regular.ttf
    ├─ Thin.ttf
    └─ Thin Italic.ttf

在这种情况下，作者可以使用 Bold 或 Medium Italic 作为 style。如果层中指定的字体样式不是字体系列的一部分，则字体始终回退到 Regular，并在 debug 模式下打印警告，因为 Regular 包含在所有字体系列中。

图标¶

作者可以利用 Material for MkDocs 提供的所有图标，甚至可以通过使用主题扩展并按照 附加图标 指南中的过程提供自定义图标。图标甚至可以通过使用 color 属性进行着色：

size: { width: 1200, height: 630 }
layers:
  - background:
      color: "#4051b5"
  - size: { width: 144, height: 144 }
    offset: { x: 992, y: 64 }
    icon:
      value: material/cat
      color: white

这将在社交卡片的右上角渲染图标：

可能性是无穷无尽的。例如，图标可以用于绘制形状，如圆形：

size: { width: 1200, height: 630 }
layers:
  - background:
      color: "#4051b5"
  - size: { width: 2400, height: 2400 }
    offset: { x: -1024, y: 64 }
    icon:
      value: material/circle
      color: "#5c6bc0"
  - size: { width: 1800, height: 1800 }
    offset: { x: 512, y: -1024 }
    icon:
      value: material/circle
      color: "#3949ab"

这将在背景中添加两个圆形：

标签¶

新的 内置社交插件 提供了完全灵活的元标签，可以添加到您的网站，这些标签对于指示服务如 X 或 Discord 如何显示您的社交卡片是必要的。所有默认布局使用以下标签集，您可以将其复制到您的布局并进行调整：

definitions:

  - &page_title_with_site_name >-
    {%- if not page.is_homepage -%}
      {{ page.meta.get("title", page.title) }} - {{ config.site_name }}
    {%- else -%}
      {{ page.meta.get("title", page.title) }}
    {%- endif -%}

  - &page_description >-
    {{ page.meta.get("description", config.site_description) or "" }}

tags:

  og:type: website
  og:title: *page_title_with_site_name
  og:description: *page_description
  og:image: "{{ image.url }}"
  og:image:type: "{{ image.type }}"
  og:image:width: "{{ image.width }}"
  og:image:height: "{{ image.height }}"
  og:url: "{{ page.canonical_url }}"

  twitter:card: summary_large_image
  twitter:title: *page_title_with_site_name
  twitter:description: *page_description
  twitter:image: "{{ image.url }}"

请注意，此示例使用了 YAML 锚点 来减少重复。definitions 属性仅用于定义可以通过锚点引用的别名。

您是否缺少某些内容？请 开启讨论 并告诉我们！