设置社交明信片¶

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

如何构建自定义社交卡片 by @james-willett – 24分钟 – 学习如何为每一页自动创建与您品牌形象完美匹配的完全自定义的社交卡片！

配置¶

内置社交插件¶

内置社交插件会自动为每一页生成一个自定义的预览图片。安装所有[图像处理依赖项][dependencies for image processing，并在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

更改布局¶

如果你想给不同的页面设置不同的布局 (例如：推广宣传页), 您可以使用在页面的元数据属性中使用 social cards_layout 设置，就像在mkdocs.yml中配置的一样：

---
social:
  cards_layout: custom
---

# Page title
...

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

参数化布局¶

除了改变整个布局之外，您还可以覆盖布局所公开的所有选项。这意味着您可以使用自定义的元数据属性（如tags（标签）、date（日期）、author（作者）或您能想到的任何其他属性）对社交卡片进行参数化设置。只需定义cards_layout_options即可。

---
social:
  cards_layout_options:
    background_color: blue # Change background color
    background_image: null # Remove background image
---

# Page title
...

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

禁用社交明信片¶

如果您希望禁用某个页面的社交名片，只需在该 Markdown 文档的元数据中添加以下内容：

---
social:
  cards: false
---

# Page title
...

自定义¶

Insiders 版本对内置社交插件进行了彻底的重写，并引入了一个全新的布局系统，该系统结合了 YAML 和 Jinja 模板 —— 与 Material-for-MkDocs 用于 HTML 模板化的同一引擎——从而允许创建复杂的自定义布局：

Layer 0

Layer 1

Layer 2

Layer 3

Layer 4

Layer 5

社交名片由多个图层组成，这与它们在 Adobe Photoshop 等图形设计软件中的表示方式类似。由于为每页生成的卡片中有很多图层是通用的（例如背景或徽标），内置社交插件可以自动去重图层并仅渲染一次，从而大大加快卡片的生成速度。生成的卡片会被缓存，以确保只有在内容发生变化时才会重新生成。

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

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

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

请注意，应省略.yml文件扩展名。接下来，运行mkdocs serve，并观察.cache目录是如何被生成的卡片填充的。在编辑器中打开任何一张卡片，这样您就可以立即看到所做的更改。由于我们还没有定义任何图层，所以这些卡片是透明的。

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

尺寸和偏移量¶

每个图层都有一个与之相关的尺寸和偏移量，它们都是以像素为单位定义的。尺寸由宽度（width）和高度（height）属性定义，而偏移量则由x和y属性定义：

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

如果省略了 size 尺寸，它将默认为布局的尺寸。如果省略了 offset偏移量，它将默认为左上角，即默认的原点 origin。保存布局并重新加载进行渲染：

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

原点 origin¶

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

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 templates 中使用：

- [`config.*`][config variable]
- [`page.*`][page variable]
- [`layout.*`][layout options]

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

这会在页面上渲染一个文本层，该文本层包含页面的标题，行高为1.25，最多3行。该插件会根据行高、行数以及上升部（ascender）和下降部（descender）等字体度量标准自动计算字体大小。¹ 渲染效果如下：

内容溢出 Overflow¶

如果文本超出了图层，会有两种可能的行为：要么文本自动截断并以省略号表示缩短，要么文本自动缩小以适应图层：

# If we use a very long headline, we can see how the text will be truncated

虽然使用省略号截断是默认行为，但通过将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样式包含在所有字体家族中。

Icons¶

作者可以利用 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"

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

Tags¶

新的内置社交插件为您的网站添加的元标签提供了极大的灵活性，这些元标签对于指导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属性仅用于定义可以通过锚点引用的别名。

您是否觉得遗漏了什么？请开启讨论并告诉我们！