设置社交卡¶

MkDocs的材料可以自动为您创建漂亮的社交卡文档，在社交媒体平台上显示为链接预览。你可以从多个[预先设计的布局][默认布局]中选择或创建 [自定义布局]以匹配您独特的风格和品牌。

How to build custom social cards by @james-willett – 24m – Learn how to create entirely custom social cards perfectly matching your branding for each page automatically!

Layout default variant — Social card of our formatting reference

配置¶

内置社交插件¶

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

plugins:
  - social

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

必须设置site_url设置

请注意，使用社交插件时必须设置site_url，否则生成的卡将无法正确链接。社交媒体服务像X和Facebook一样，要求社交预览指向绝对 URL，插件只能在设置'site_URL时计算。例子：

site_url: https://example.com

使用¶

如果你想调整社交卡的标题或设置自定义描述，您可以设置标题[更改标题]和 [description][更改description]属性，其优先级高于默认值，或使用：

选择字体¶

某些字体不包含CJK字符，例如默认字体，Roboto。如果您的“site_name”、“site_description”或页面标题包含CJK字符，请从[谷歌字体]中选择另一种字体带有CJK字符，例如“Noto Sans”字体家族中的一个字符：

Chinese (Simplified)Chinese (Traditional)JapaneseKorean

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

更改布局¶

如果你想对单个页面使用不同的布局（例如你的着陆页面），您可以将“社会”前沿属性与 [cards_layout]（../plugins/social.md#meta.social.cards_layout）键，与在mkdocs.yml中：

---
social:
  cards_layout: custom
---

# Page title
...

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

Parametrizing the layout¶

除了更改整个布局外，您还可以覆盖布局的所有选项暴露。这意味着您可以使用自定义前件对社交卡进行参数化属性，如标签、日期、作者或任何你能想到的东西。只需定义[cards_layout_options]（../plugins/social.md#meta.social.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
...

自定义¶

[内部人士]对[内置社交插件]进行了彻底的重写介绍了一种基于YAML和.NET的全新布局系统 [Jinja模板]–MkDocs的Material引擎用于HTML 模板–允许创建复杂的自定义布局：

社交卡片由多层组成，类似于它们在图形设计软件，如Adobe Photoshop。由于许多层是常见的在为每个页面生成的卡片（例如背景或徽标）中内置的社交插件可以自动删除重复层并呈现它们仅一次，大大加速了卡的生成。生成的卡片是缓存以确保它们仅在内容更改时重新生成。

布局是用YAML语法编写的。在开始创建自定义布局之前， [研究预先设计的布局]是个好主意（链接到[内部人士] 存储库），以便更好地了解它们是如何工作的。然后，创建一个新布局并在mkdocs.yml中引用它：

layouts/custom.yml 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 }

如果省略“大小”，则默认为布局的大小。如果'偏移` 如果省略，则默认为左上角，即默认的“原点”。保存布局并重新加载渲染：

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

起源¶

“x”和“y”值的“原点”可以更改，因此该层为与布局的边缘或角落对齐，例如右下角布局的一角：

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

下表显示了支持的值：

Origin
`start top`	`center top`	`end top`
`start center`	`center`	`end center`
`start bottom`	`center bottom`	`end bottom`

Supported values for origin

背景¶

可以为每一层指定背景颜色和图像。如果两者都给出颜色渲染在图像之上，允许半透明、着色背景：

Background colorBackground imageBackground image, tinted

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)!

颜色值可以设置为[CSS颜色关键字]，或3、4、6或8 字母HEX颜色代码，允许半透明层。

背景图像会自动缩放以适应图层，同时保留宽高比。请注意，我们省略了“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

以下变量可用于[Jinja模板]：
- config.*
- page.*
- [layout.*][layout options]
作者可以自由定义“layout.*”选项，这些选项可用于传递从mkdocs.yml向布局添加任意数据。

这呈现了一个文本层，其中页面标题的行高为1.25，最多3行。插件会自动计算字体大小从行高、行数和字体度量（如ascender和下行。¹这表示：

溢流¶

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

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

Ellipsis Shrink

虽然默认情况下使用省略号截断，但可以启用自动收缩通过将“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，这将呈现为：

下表显示了支持的值：

Alignment
`start top`	`center top`	`end top`
`start center`	`center`	`end center`
`start bottom`	`center bottom`	`end bottom`

Supported values for text alignment

Font¶

[内置社交插件]与[谷歌字体]集成，并将自动为您下载字体文件。font属性接受 family和style属性，其中family必须设置为将字体和“样式”转换为支持的字体样式之一。例如，设置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

在这种情况下，作者可以使用“粗体”或“中斜体”作为“风格”。如果图层中指定的字体样式不是字体族的一部分 font总是回退到“常规”，并在'debug中打印警告模式，因为“常规”包含在所有字体系列中。

图标¶

作者可以利用Material附带的全系列图标 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等服务所必需的或者不知道如何显示你的社交卡。所有默认布局都使用以下内容标签集，您可以将其复制到布局中并进行调整：

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属性仅用于定义别名然后可以用锚点引用。

Are you missing something? Please open a discussion and let us know!

如果插件要求作者指定字体大小和行手动调整高度，无法保证文本适合进入该层。出于这个原因，我们实现了一种声明性方法，其中作者指定了所需的行高和行数，以及插件会自动计算字体大小。 ↩