自定义卡片¶

社交插件允许您定义自定义布局，以满足您的特定需求，如果配置选项不足。例如，您可能希望定义一个社交卡片来宣传您产品的新版本。它应该有一个指示发布公告的图标，以及卡片上显示的版本号。

设置¶

您可以从头开始设计自定义布局，也可以使用现有布局作为基础进行添加或修改。在本教程中，您将使用默认布局作为基础。

复制默认布局以进行自定义

从您安装的 Material for MkDocs 中复制默认社交卡片布局到一个新的目录 layouts。以下说明假设您在项目根目录中，并且在其中有一个虚拟环境。您机器上的路径当然可能会有所不同。

$ mkdir layouts
$ cp venv/lib/python3.12/site-packages/material/plugins/social/templates/default/variant.yml \
  layouts/release.yml

在自定义社交卡片之前，您需要告诉插件在哪里找到它们，并告诉 MkDocs 监视任何更改。将以下内容添加到您的 mkdocs.yml 中的插件配置中：

plugins:
  - social:
      cards_layout_dir: layouts

watch:
  - layouts

查看 release.yml 的内容。您将看到：

从网站提取的一些内容定义，
最终出现在每个页面的页面头部的 meta 元素中的标签定义，
由多个层组成的规范，社交插件按定义的顺序将其应用于彼此之上。

定义页面元数据¶

接下来，您将向社交卡片添加版本号。这假设您有一个包含每个版本信息的变更日志页面。将最新版本的版本号添加到页面头部（这样就不需要从 Markdown 内容中解析出来）：

定义发布数据

创建一个页面 docs/changelog.md，内容如下：

---
icon: material/rocket-launch-outline
social:
  cards_layout: release
  cards_layout_options:
    title: New release!
latest: 1.2.3
---

# Releases

提取页面元数据¶

在页面头部定义了数据后，您现在可以向布局中添加代码，以提取这些数据并使其在后续渲染中可用。这是为了将数据处理与实际布局指令分开，从而使布局文件更易于阅读。

添加数据定义

在布局文件的顶部添加以下内容：

definitions:
  - &latest >-
    {%- if 'latest' in page.meta %}
        {{ page.meta['latest']}}
    {%- else -%}
        No release version data defined!
    {%- endif -%}

这里提供的代码检查页面头部是否包含必要的条目，如果没有，则在社交卡片中输出一条消息。不幸的是，没有简单的方法来引发异常或记录错误，因此消息仅在生成的社交卡片中出现。

添加发布版本层¶

下一步是使用这些数据定义创建一个新层，并将其添加到已有的层中。

渲染发布版本

最后，将以下内容添加到自定义布局的末尾：

  - size: { width: 990, height: 50 }
    offset: { x: 50, y: 360 }
    typography:
      content: *latest
      align: start
      color: *color

现在，您应该看到社交插件在您设置的变更日志页面上使用自定义布局。

调整布局¶

最后，用于变更日志页面的火箭图标位置不太正确。找到使用 page_icon 变量创建页面图标层的位置，并将水平位置调整为 600，而不是 800。

调试布局文件

如果您发现您的布局导致 MkDocs 构建失败，您可以做以下几件事：

使用 --verbose 选项运行 Mkdocs，以获得更详细的报告。
注释掉您最近添加的或怀疑是原因的内容。
使用 pip install Jinja2 安装 jinja2 命令行工具，并在您的布局文件上运行，例如：jinja2 event.yml。

接下来是什么？¶

如果您还没有博客，为什么不查看一下博客教程，学习如何设置一个呢？社交插件将帮助您在社交媒体上吸引人们关注您的帖子。

查看我们为您准备的其他教程。