Skip to content

自定义卡片

¥Custom cards

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

¥The Insiders Edition allows you to define custom layouts for your social cards to suit your specific needs if the configuration options are not enough. For example, you may want to define a social card to advertise a new release of your product. It should have an icon indicating a launch announcement as well as the version number of the release on the card.

设置

¥Setup

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

¥You can either design a custom layout from scratch or use an existing layout as the basis that you add to or otherwise modify. In this tutorial, you will use the default layout as the basis.

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

¥Copy default layout to customize

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

¥Copy the default social card layout from your installation of Material for MkDocs to a new directory layouts. The instructions below assume you are in your project root and have a virtual environment within this. The path on your machine, of course, may differ.

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

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

¥Before customizing the social cards, you need to tell the plugin where to find them as well as tell MkDocs to watch for any changes. Add the following to the plugin configuration in your mkdocs.yml:

plugins:
  - social:
      cards_layout_dir: layouts

watch:
  - layouts

查看release.yml的内容。你会看到以下内容：

¥Have a look at the contents of release.yml. You will see that there are:

  • 从网站中提取的一些内容的定义，

    ¥a number of definitions of content pulled from the site,

  • 每个页面页眉中的meta元素中标签的定义，

    ¥definitions of tags that end up in the meta elements in the page header of each page,

  • 一种规范，由多个层组成，社交插件按照定义的顺序将这些层应用到彼此之上。

    ¥a specification that consists of a number of layers that the social plugin applies on top of each other in the order in which they are defined.

定义页面元数据

¥Define page metadata

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

¥In the following, you will add a version number to the social card. This assumes you have a changelog page with information about each release. Add the version number of the latest version to the page header (so it does not need to be parsed out of the Markdown content):

定义发布数据

¥Defining the release data

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

¥Create a page docs/changelog.md with the following content:

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

# Releases

提取页面元数据

¥Extract page metadata

有了页眉中定义的数据，您现在可以向布局中添加代码，以便提取数据并使其稍后可供渲染。这样做是为了将数据操作与实际的布局指令分开，从而使布局文件更易于阅读。

¥With the data defined in the page header, you can now add code to the layout that pulls it out and makes it available to render later on. This is to separate the data manipulation from the actual layout instructions and so make the layout file easier to read.

添加数据定义

¥Adding data definitions

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

¥Add the following at the top of the layout file:

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

这里的代码会检查页眉是否包含必要的条目，如果没有，则会向社交卡片发送一条消息。遗憾的是，没有直接抛出异常或记录错误的方法，因此这些消息只会显示在生成的社交卡片中。

¥The code presented here checks whether the page header contains the necessary entries and spits out a message to the social card if not. Unfortunately, there is no straightforward way to raise an exception or log an error, so the messages merely appear in the social card produced.

添加发布版本层

¥Add release version layer

下一步是在新层中使用这些数据定义并将其添加到现有层中。

¥The next step is to use these data definitions in a new layer and add it to the ones already present.

渲染发布版本

¥Render release version

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

¥Finally, add the following to end of the custom layout:

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

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

¥You should now see the social plugin use the custom layout on the changelog page you set up.

调整布局

¥Adjust layout

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

¥Finally, the rocket icon used for the changelog page is not quite in the right position. Find the please where the page_icon variable is used to create the page icon layer and adjust the horizontal position to 600 instead of 800.

调试布局文件

¥Debugging layout files

如果您发现布局导致 MkDocs 构建失败，您可以采取以下措施：

¥Should you find that your layouts are causing your MkDocs build to fail, there are a number of things you can do:

  1. 使用--verbose选项运行 Mkdocs 以获取更详细的报告。

    ¥Run Mkdocs with the --verbose option to get more detailed reporting.

  2. 注释掉你最近添加的内容或你怀疑是原因的内容

    ¥Comment out things you recently added or that you suspect are the cause

  3. 使用pip install Jinja2安装jinja2命令行工具并在布局文件上运行它，例如： jinja2 event.yml 。

    ¥Install the jinja2 command-line tool with pip install Jinja2 and run it over your layout file, for example: jinja2 event.yml.

下一步是什么？

¥What's next?

如果您还没有博客，不妨看看博客教程，学习如何创建博客。社交插件能帮您在社交媒体上吸引更多人关注您的帖子。

¥If you do not have a blog yet, why not check out the blog tutorials and learn how to set one up? The social plugin will help you draw attention to your posts on social media.

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

¥Check out the other tutorials we have prepared for you.