内置社交插件¶

社交插件自动且智能地为项目的每个页面生成美观且高度可定制的社交卡片，采用不同的布局，在您或其他人分享项目链接到社交媒体时以预览图像的形式呈现。

目标¶

工作原理¶

该插件为项目的每个页面自动生成可定制的社交卡片，当在社交媒体上分享项目链接时，它会作为预览图像出现，无需使用外部服务，只需a single line of configuration。

通过使用高效的[图像处理]库，该插件允许定义[自定义布局]用于社交卡片，这些布局可以适应您的项目风格和品牌。虽然从技术上讲，通过使用网络浏览器和自动化框架如Puppeteer¹生成社交卡片会简单得多，但这会给您的工具链增加额外的负担，可能会使构建管道变得更加复杂、资源消耗更大且显著减慢。

生成的社交卡片会被[缓存]并存储在site目录中，因此是自托管的，确保您的项目不依赖于外部服务。为了生成社交卡片图像，您的系统上需要有一些[依赖项]。

何时使用¶

有一种特定情况我们不推荐使用该插件：当您构建离线可用文档以提供下载时。否则，启用该插件总是有意义的，因为在社交媒体上分享的文档链接会显得更具吸引力。

更有趣的是，该插件可以与Material for MkDocs提供的其他内置插件结合使用，以创建针对您的项目量身定制的复杂构建管道：

配置¶

8.5.0 social – built-in

要开始使用社交插件，只需将以下行添加到mkdocs.yml中，然后观察Material for MkDocs为您生成美丽的社交卡片：

plugins:
  - social

社交插件是Material for MkDocs内置的，不需要安装。

然而，为了生成社交卡片图像，如果您的系统上尚未安装[图像处理]的依赖项，则需要安装这些依赖项。链接的指南包含多个操作系统的说明，并提到一些替代环境。

一般设置¶

以下设置可用：

enabled¶

8.5.0 true

使用此设置在构建项目时启用或禁用插件。如果您想禁用插件，例如，在本地构建时，可以在mkdocs.yml中使用环境变量：

plugins:
  - social:
      enabled: !ENV [CI, false]

此配置仅在持续集成（CI）期间启用插件。

concurrency¶

9.7.0 available CPUs - 1

有更多的CPU可用时，插件可以并行处理更多工作，从而更快完成社交卡片生成。如果您想完全禁用并发处理，请使用：

plugins:
  - social:
      concurrency: 1

默认情况下，插件使用所有可用的CPU - 1，最小为1。

缓存¶

该插件实现了智能缓存机制，确保社交卡片仅在其内容更改或未包含在缓存中时才会重新生成。如果布局中使用的任何变量发生变化，插件会检测到并重新生成社交卡片。

以下设置可用于缓存：

cache¶

9.7.0 true

使用此设置指示插件绕过缓存，以便为所有页面重新生成社交卡片，即使缓存可能并不陈旧。通常不需要指定此设置，除非在调试插件本身时。可以通过以下方式禁用缓存：

plugins:
  - social:
      cache: false

cache_dir¶

8.5.0 .cache/plugin/social

通常不需要指定此设置，除非您想更改社交卡片图像缓存的路径。如果您想更改它，请使用：

plugins:
  - social:
      cache_dir: my/custom/dir

如果您使用多个实例的插件，为两个实例设置不同的缓存目录可能是个好主意，以免相互干扰。

日志记录¶

以下设置可用于日志记录：

log¶

9.7.0 true

使用此设置控制插件在生成社交卡片时是否仅记录错误而不终止构建，例如，图标的无效引用。要终止构建，请使用：

plugins:
  - social:
      log: false

log_level¶

9.7.0 warn

使用此设置控制插件在遇到错误时应使用的日志级别，这要求log设置已启用。以下日志级别可用：

plugins:
  - social:
      log_level: warn

plugins:
  - social:
      log_level: info

plugins:
  - social:
      log_level: ignore

社交卡片¶

以下设置可用于社交卡片生成：

cards¶

8.5.0 true

使用此设置启用或禁用社交卡片生成。目前，该插件的唯一目的是生成社交卡片，因此它等同于enabled设置，但将来可能会添加其他功能。如果您想禁用社交卡片生成，请使用：

plugins:
  - social:
      cards: false

cards_dir¶

8.5.0 assets/images/social

通常不需要指定此设置，除非您想更改社交卡片存储在site目录中的路径。如果您想更改它，请使用：

plugins:
  - social:
      cards_dir: my/custom/dir

此配置将生成的图像存储在site目录中的my/custom/dir。

cards_layout_dir¶

9.7.0 layouts

如果您想构建自定义社交卡片布局，请使用此设置更改存储自定义布局的文件夹，默认情况下为根目录中的layouts文件夹：

plugins:
  - social:
      cards_layout_dir: layouts

提供的路径是从根目录解析的。

.
├─ docs/
│  └─ *.md
├─ layouts/
│  └─ *.yml
└─ mkdocs.yml

cards_layout¶

9.7.0 default

该插件提供了一系列不断增长的default布局用于社交卡片。如果您创建了自定义社交卡片布局，可以指示插件将其用作包含的布局之一：

plugins:
  - social:
      cards_layout: my-custom-layout

提供的路径是从layouts目录解析的。

.
├─ docs/
│  └─ *.md
├─ layouts/
│  └─ my-custom-layout.yml
└─ mkdocs.yml

cards_layout_options¶

9.1.10

使用此设置为通过cards_layout指定的布局设置选项（如果布局支持），这使得布局易于完全可配置：

plugins:
  - social:
      cards_layout_options:
        <option>: <value>

在创建自定义布局时，您可以完全自由地定义布局中可以参数化的部分。插件中包含的default布局支持以下选项：

cards_include¶

9.7.0

使用此设置为项目的子部分启用社交卡片生成，例如，当使用多个实例的插件为不同子部分生成不同社交卡片时：

plugins:
  - social:
      cards_include:
        - blog/*

此配置启用社交卡片生成，适用于docs目录中blog文件夹及其子文件夹内的所有页面。

cards_exclude¶

9.7.0

使用此设置为项目的子部分禁用社交卡片生成，例如，当使用多个实例的插件为不同子部分生成不同社交卡片时：

plugins:
  - social:
      cards_exclude:
        - changelog/*

此配置禁用社交卡片生成，适用于docs目录中changelog文件夹及其子文件夹内的所有页面。

调试¶

该插件包含一个特殊的调试模式，非常适合在创建[自定义布局]时使用，因为它允许更快的迭代和更好地理解组合。

以下设置可用于调试：

debug¶

9.7.0 false

使用此设置启用调试布局的特殊模式，该模式为每个层渲染带有颜色轮廓的边框及其x和y偏移量，并覆盖一个点网格以便对齐，从而更容易理解布局的不同层是如何组合在一起的：

plugins:
  - social:
      debug: true

debug_on_build¶

9.7.0 false

默认情况下，插件在构建项目时会自动禁用debug模式，因此您可以确保调试覆盖不会被部署到生产环境。如果您想更改此设置，请使用：

plugins:
  - social:
      debug_on_build: true

通常不需要更改此设置，因为它只是作为安全网。

debug_grid¶

9.7.0 true

当debug模式启用时，此设置指定是否在所有层上方渲染点网格，以便更好地对齐。如果您想关闭网格，请使用：

plugins:
  - social:
      debug_grid: false

debug_grid_step¶

9.7.0 32

使用此设置指定点网格的步长（以像素为单位），如果启用，这对于创建完美对齐的层以实现理想组合非常有用。如果您想更改它，请使用：

plugins:
  - social:
      debug_grid_step: 64

debug_color¶

9.7.0 grey

使用此设置指定添加到每个层的轮廓和渲染在所有层上方的点网格的颜色。如果您需要更改它，请使用：

plugins:
  - social:
      debug_color: yellow

在少数情况下，如果点网格或轮廓难以区分，可能需要更改此设置，因为插件会自动调整颜色（如果未明确设置）。

使用¶

元数据¶

该插件允许通过元数据（前置内容）覆盖一部分设置，以自定义社交卡片生成，例如，为单个页面设置包含的default布局的选项，或甚至通过利用meta插件为项目的整个子部分设置。

以下属性可用：

cards¶

9.7.0

使用此属性覆盖给定页面的cards设置：

---
social:
  cards: false
---

# 页面标题
...

cards_layout¶

9.7.0

使用此属性覆盖给定页面的cards_layout设置：

---
social:
  cards_layout: my-custom-layout
---

# 页面标题
...

cards_layout_options¶

9.7.0

使用此属性覆盖给定页面的cards_layout_options设置：

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

# 页面标题
...

将选项设置为null将重置该选项。

布局¶

9.7.0

虽然构建[自定义布局]是可能且简单的，但该插件提供了几个预定义布局，所有布局都以default为前缀。包含以下布局：

plugins:
  - social:
      cards_layout: default

plugins:
  - social:
      cards_layout: default/variant

plugins:
  - social:
      cards_layout: default/accent

plugins:
  - social:
      cards_layout: default/invert

plugins:
  - social:
      cards_layout: default/only/image
      cards_layout_options:
        background_image: layouts/background.png

default布局非常灵活且易于使用，因为它们复制了插件的原始行为，从其他theme设置中获取所有选项的默认值。

以下选项可用：

background_color¶

9.1.10

使用此选项更改生成的社交卡片的背景颜色。该值可以设置为有效的颜色值supported by pillow，即用于卡片生成的图像库：

plugins:
  - social:
      cards_layout_options:
        background_color: "#ff1493" # (1)!

plugins:
  - social:
      cards_layout_options:
        background_color: rgb(255, 20, 147) # (1)!

plugins:
  - social:
      cards_layout_options:
        background_color: deeppink # (1)!

如果此选项与background_image一起使用，则颜色会渲染在图像上方，从而允许对图像进行着色。如果您想移除背景颜色，请使用：

plugins:
  - social:
      cards_layout_options:
        background_color: transparent

background_image¶

9.7.0

使用此选项为生成的社交卡片定义背景图像。请注意，图像会与background_color进行着色，该颜色也可以设置为transparent：

plugins:
  - social:
      cards_layout_options:
        background_image: layouts/background.png
        background_color: transparent

plugins:
  - social:
      cards_layout_options:
        background_image: layouts/background.png
        background_color: "#ff149366"

提供的路径是从根目录解析的。

color¶

9.1.10

使用此选项更改生成的社交卡片的前景颜色。该值可以设置为有效的颜色值supported by pillow，即用于卡片生成的图像库：

plugins:
  - social:
      cards_layout_options:
        color: "#ffffff" # (1)!

plugins:
  - social:
      cards_layout_options:
        color: rgb(255, 255, 255) # (1)!

plugins:
  - social:
      cards_layout_options:
        color: white # (1)!

font_family¶

9.1.10

使用此选项更改生成的社交卡片的字体系列。插件会自动从Google Fonts下载字体，因此字体必须指向现有的Google字体：

plugins:
  - social:
      cards_layout_options:
        font_family: Ubuntu

当您在Google Fonts上找到喜欢的字体时，可以直接从字体样本页面复制名称并将其用作此选项的值，无需进一步配置。

font_variant¶

9.7.0

使用此选项更改用于生成社交卡片的字体变体。如果下载的字体有Condensed或Expanded等变体，您可以使用：

plugins:
  - social:
      cards_layout_options:
        font_variant: Condensed

变体与自定义布局中使用的样式结合，因此插件会指示使用Condensed Regular或Expanded Bold等组合。

logo¶

9.7.0

使用此选项更改生成的社交卡片中使用的徽标。默认情况下，插件使用来自mkdocs.yml的theme.logo或theme.icon.logo设置。您可以通过以下方式更改它：

plugins:
  - social:
      cards_layout_options:
        logo: layouts/logo.png

提供的路径是从根目录解析的。

title¶

9.7.0

使用此选项更改生成的社交卡片的标题。这将覆盖MkDocs分配的计算页面标题，以及title元数据属性：

plugins:
  - social:
      cards_layout_options:
        title: My custom title

description¶

9.7.0

使用此选项更改生成的社交卡片的描述。这将覆盖设置的site_description（如果定义），以及description元数据属性：

plugins:
  - social:
      cards_layout_options:
        description: My custom description