生成社交媒体卡：Pelican插件

此插件生成带有您文章标题的图像。然后可以使用这些图像作为“卡片”元数据，并在您的帖子被分享到社交媒体时显示，使这些帖子更具视觉吸引力。最终效果可能看起来像这样

生成的图像路径添加到每个文章/页面中的og_image属性，因此在主题中易于使用。

请注意，该插件仅生成图像 - 您必须在输出HTML中引用它们，以便社交媒体平台可以获取它们。有一些主题和插件可以帮助完成这部分。请参阅"在输出HTML中引用文件"以获取所需更改和可用选项的简要概述。

• 生成社交媒体卡：Pelican插件
• 安装
• 用法
  • 初始配置
  • 准备模板文件
  • 调整卡片视觉
    • 字体
    • 行长度
    • 文本位置和对齐
  • 控制卡片上的文本
  • 在输出HTML中引用文件
  • 迭代卡片设计
• 配置选项
  • SOCIAL_CARDS_TEMPLATE
  • SOCIAL_CARDS_PATH
  • SOCIAL_CARDS_FORMAT_EXTENSION
  • SOCIAL_CARDS_FONT_FILENAME
  • SOCIAL_CARDS_FONT_SIZE
  • SOCIAL_CARDS_FONT_FILL
  • SOCIAL_CARDS_FONT_OUTLINE_SIZE
  • SOCIAL_CARDS_FONT_OUTLINE_FILL
  • SOCIAL_CARDS_CANVAS_WIDTH
  • SOCIAL_CARDS_CANVAS_HEIGHT
  • SOCIAL_CARDS_CANVAS_LEFT
  • SOCIAL_CARDS_CANVAS_TOP
  • SOCIAL_CARDS_HORIZONTAL_ALIGNMENT
  • SOCIAL_CARDS_VERTICAL_ALIGNMENT
  • SOCIAL_CARDS_LEADING
  • SOCIAL_CARDS_WRAPPING_FUNCTION
  • SOCIAL_CARDS_CHARS_PER_LINE
  • SOCIAL_CARDS_KEY_NAME
  • SOCIAL_CARDS_INCLUDE_SITEURL
  • SOCIAL_CARDS_INCLUDE_DRAFTS
  • SOCIAL_CARDS_INCLUDE_HIDDEN
  • SOCIAL_CARDS_FORCE_SAVE
• 贡献

安装

可以从PyPI安装插件

pip install pelican-social-cards

用法

初始配置

首先，你需要一个将作为模板的图片。对于每篇文章，插件将复制此文件并在其上绘制文本。使用 SOCIAL_CARDS_TEMPLATE 设置指定此文件的位置

SOCIAL_CARDS_TEMPLATE = "content/misc/card-template.png"

文件将创建在你的Pelican内容目录的 social-cards 子目录中（你可以使用 SOCIAL_CARDS_PATH 设置更改此位置）。你应该将此目录添加到你的 STATIC_PATHS，以便Pelican可以找到这些图像并将它们复制到输出目录。

STATIC_PATHS = ['social-cards']

就这样！如果你现在构建你的网站，它将比平时花费更多的时间，因为插件正在为你创建所有卡片。然后，你可以在 content/social-cards/ 和 output/static/social-cards/ 中看到你的卡片。别担心 - 下次构建将和以前一样快，因为插件不会重新创建已经存在的图像。

如果你使用git版本控制系统维护你的网站，你可能想将 social-cards/ 添加到你的 .gitignore 文件中。

阅读 "调整卡片视觉" 了解你可能想要更改的设置概述，以及 "配置选项" 了解所有可用设置列表。

准备模板文件

每个社交媒体平台对其与共享链接关联的图像都有各自的要求。一个共同元素是卡片图像的尺寸应保持1.91:1的比例，或者至少接近这个比例。Twitter可以接受144 x 144 px大小的小图像；Facebook接受至少200 x 200 px的图像，但建议至少600 x 315 px；LinkedIn期望图像至少为1200 x 627 px。

总的来说，1200 x 630 px 是模板图像的好默认大小。然而，插件不会对你的模板施加任何规则，所以你可以使用任何你想要的尺寸。

模板文件代表的内容（外观）完全由你决定。大多数社交媒体专家都会建议卡片保持与你的网站视觉的一致性。保持相同的背景颜色，并在某个地方放置你的标志/站点名称是好的起点。显然，你需要留下一些空白空间，这样文本就不会覆盖你的图像的其他元素。

模板文件必须是 Pillow 可以读取的格式。JPEG和PNG是不错的选择。

SOCIAL_CARDS_TEMPLATE 设置的内容直接传递给 PIL.Image.open()，这意味着你可以将模板文件放在你的文件系统的任何位置。建议将其与网站源文件一起保存，可能在 content 或 theme 目录中。

调整卡片视觉

字体

SOCIAL_CARDS_FONT_FILENAME 指定将使用的字体。此设置的值直接传递给 PIL.ImageFont.truetype()，因此所有这些函数的限制和要求都适用。这应该是TTF文件的路径，或者只是字体文件的名称 - Pillow将尝试在全局操作系统字体存储中找到它。

SOCIAL_CARDS_FONT_SIZE 指定字体的像素大小。

SOCIAL_CARDS_FONT_FILL 设置文本颜色。此设置的值将直接传递给 PIL.ImageColor。Pillow 支持多种颜色格式，但 #rrggbb 或 CSS 人性化名称 可能更容易使用。

SOCIAL_CARDS_LEADING 设置行间距，有时也称为“行间距”或“行间距”，即从一行文本的底部到下一行文本顶部的距离。通常，较大的字体大小需要较大的行间距。

行长度

SOCIAL_CARDS_CHARS_PER_LINE 设置一行中字符的最大数量。在底层使用 textwrap.wrap()，该函数尝试在最大长度之前在最后一个空白字符处断行。此设置作为函数的 width 参数传递。

SOCIAL_CARDS_WRAPPING_FUNCTION 允许您指定要替代 textwrap.wrap 的函数。如果您的文本换行要求非常具体，此设置可能很有用。有关详细信息，请参阅下文中的 "控制卡片上的文本"。

文本位置和对齐

应在其中绘制文本的图像区域称为“画布”。插件不会强制文本实际适合该区域，但如果文本超出指定区域，它将发出警告。如果您遇到多个此类警告，可能需要调整画布大小、字体大小或每行字符数。如果您仅遇到少数此类警告，请参阅下文中的 "控制卡片上的文本"，以按文章设置自定义文本。

SOCIAL_CARDS_CANVAS_WIDTH 是文本区域的宽度，以像素为单位。

SOCIAL_CARDS_CANVAS_HEIGHT 是文本区域的高度，以像素为单位。

SOCIAL_CARDS_CANVAS_LEFT 是文本区域的左边缘，即从图像左侧边框到画布左侧边框的距离。插件将尝试不在此处写入任何文本，但可能无法做到，当您的文本不是左对齐且行宽大于画布宽度时。

SOCIAL_CARDS_CANVAS_TOP 是文本区域的顶部边距，即从图像顶部边框到画布顶部边框的距离。插件将尝试不在此处写入任何文本，但可能无法做到，当您的文本不是顶部对齐且文本行总高度大于画布高度时。

SOCIAL_CARDS_HORIZONTAL_ALIGNMENT 是画布内文本的对齐方式。有效值是 "left"、"center" 和 "right"。以下为各种设置的视觉表示。

SOCIAL_CARDS_VERTICAL_ALIGNMENT 是画布内文本的对齐方式。有效值是 "top"、"center" 和 "bottom"。以下为各种设置的视觉表示。

控制卡片上的文本

默认情况下，图像上写入的文本将是文章/页面标题。但是，您可以通过向文件标题添加 og_image_text 自定义元数据来按文章更改此设置。当您想在社会媒体卡片上使用标题的简短版本，或当您希望在没有推出自己的换行函数的情况下对文本换行有更精细的控制时，这可能很有用。

当插件遇到 og_image_text 键时，它所做的唯一一件事是按 \n 字符分割值。不会对文本进行进一步处理。这意味着您可以使用 \n 强制文本换行到新行；这也意味着，如果您想使用印刷正确的字符（例如，使用 “” 而不是 ""），您必须自己输入它们。

在输出HTML中引用文件

除了创建用作社交媒体卡片图像的图像外，您还必须确保社交媒体平台可以找到您的图像。为此，您需要在输出 HTML 文件的头部部分中包含 og:image 元数据。

<meta property="og:image" content="URL_OF_IMAGE"/>

包含此 HTML 的方法之一是使用了解开放图谱标签的主题。pelican-themes 存储库中的一些主题内置了对开放图谱图像的支持。要查找这些主题，请克隆存储库并使用类似 grep -l -R 'og:image' 的命令。

另一种方法是使用pelican-seo插件。该插件可以与任何主题一起使用，因为它修改了生成的HTML。在版本1.1.0中添加了对开放图标签的支持。要生成开放图标签，您需要将SEO_ENHANCER_OPEN_GRAPH设置设置为True - 然而，您需要在虚拟环境内的pelican/plugins/seo/settings.py文件中这样做。

迭代卡片设计

生成单个图像可能需要高达几百毫秒的时间，因此在大型网站（数百篇文章）上，整个过程可能需要几分钟。显然，当您仍在尝试找到模板的最佳设置时，您不希望等待这么长时间。这里有两条处理此问题的建议。

您可以做的事情之一是让插件为您生成所有图像，选择一个您想要工作的图像，并将其从content/social-cards目录中删除。下次您构建网站时，插件将跳过所有已存在的图像，并生成一张缺失的卡片。然后您可以查看其外观，删除它，调整设置，然后再次构建网站。一旦您对结果满意，您就会删除所有图像，并允许插件再次生成它们。

另一个选项是使用ARTICLE_PATHS Pelican 设置，这是Pelican应该生成文章的路径列表（或包含文章的目录）。您可以设置此设置以指向单个文章，插件将只为这篇文章生成图像。一旦您对获得的结果满意，删除此设置，并为所有文章生成图像。

还有PAGE_PATHS，如果您的网站有比文章更多的页面，您可以使用它。

配置选项

SOCIAL_CARDS_TEMPLATE

作为卡片模板的图像的路径。对于每篇文章，插件都会复制此文件并在其上绘制文本。

此设置的值将被原样传递到PIL.Image.open()，因此文件必须存在，并且是Pillow可以读取的格式之一。

这是唯一必需的设置，因此如果未定义，则具有禁用插件的效果，而无需卸载它。

默认值: None

SOCIAL_CARDS_PATH

卡图像将保存的目录的路径，相对于Pelican PATH设置。如果不存在，将创建目录。

默认值: "social-cards/"

SOCIAL_CARDS_FORMAT_EXTENSION

生成图像的文件扩展名。因此，这也指定了图像格式，并且必须是Pillow可以写入的格式之一。

请注意，尽管此设置不必与SOCIAL_CARDS_TEMPLATE文件的格式匹配，但模板文件必须在此设置中指定的格式支持的模式下。也就是说，尝试使用带有alpha通道的PNG文件作为模板，并将目标格式设置为JPEG将导致致命错误，因为RGBA模式不能转换为JPEG。

JPEG通常写入速度更快，但PNG支持alpha通道，因此默认使用PNG。

默认值: "png"

SOCIAL_CARDS_FONT_FILENAME

要使用的字体名称。此设置的值将被原样传递到PIL.ImageFont.truetype()，因此此函数的限制和要求也适用。这应该是TTF文件的路径，或者只是字体文件的名称 - Pillow将尝试在全局操作系统字体存储中找到它。

默认值: "Arial.ttf"

SOCIAL_CARDS_FONT_SIZE

字体的像素大小。

默认值: 70

SOCIAL_CARDS_FONT_FILL

文本颜色。此设置的值将被原样传递到PIL.ImageColor。Pillow支持多种颜色格式，但#rrggbb和CSS人类友好的名称可能最容易使用。

默认值: "#000000"

SOCIAL_CARDS_FONT_OUTLINE_SIZE

字体轮廓宽度，以像素为单位。此效果也称为“文本描边”，结果文本周围会环绕着一圈可能不同颜色的线条（参见 示例图片）。此设置的值将原样传递给Pillow。

0的值会导致不绘制轮廓。

默认值：0

SOCIAL_CARDS_FONT_OUTLINE_FILL

字体轮廓的颜色。此设置的值将原样传递给PIL.ImageColor。Pillow支持多种颜色格式，但#rrggbb和CSS人类友好名称可能更容易使用。

当SOCIAL_CARDS_FONT_OUTLINE_SIZE设置为正整数时，此设置才生效。

默认值: "#000000"

SOCIAL_CARDS_CANVAS_WIDTH

"画布"的宽度，以像素为单位。画布是文本将要绘制的特殊区域。根据字体样式、字体大小和行中的字符数，文本实际上可能绘制在此区域之外 - 但插件会在这种情况下发出警告。

默认值：1200

SOCIAL_CARDS_CANVAS_HEIGHT

"画布"的高度，以像素为单位。画布是文本将要绘制的特殊区域。根据字体大小、行间距和行数，文本实际上可能绘制在此区域之外 - 但插件会在这种情况下发出警告。

默认值：630

SOCIAL_CARDS_CANVAS_LEFT

从图像左侧边框到画布左侧边框的距离（画布的左边距）。插件将尝试不在那里写入任何文本，但可能无法做到，当您的文本不是左对齐且行宽大于画布宽度时。

默认值：0

SOCIAL_CARDS_CANVAS_TOP

从图像顶部边框到画布顶部边框的距离（画布的顶部边距）。插件将尝试不在那里写入任何文本，但可能无法做到，当您的文本不是顶部对齐且文本行总高度大于画布高度时。

默认值：0

SOCIAL_CARDS_HORIZONTAL_ALIGNMENT

画布内文本的对齐方式。有效值是"left"、"center"和"right"。参见上方的"文本定位和对齐"部分，以了解各种设置的视觉表示。

默认值："center"

SOCIAL_CARDS_VERTICAL_ALIGNMENT

画布内文本的对齐方式。有效值是"top"、"center"和"bottom"。参见上方的"文本定位和对齐"部分，以了解各种设置的视觉表示。

默认值："center"

SOCIAL_CARDS_LEADING

从一行文本的底部到下一行文本的顶部的距离，以像素为单位。术语行间距来自排版，并可能被各种DTP软件供应商所混淆，有时也称为“行间距”或“行间间距”。

默认值：15

SOCIAL_CARDS_WRAPPING_FUNCTION

用于包装文本的函数，即将长字符串转换为较短字符串的列表。文章/页面标题在绘制到图像之前将通过它。请注意，这必须是实际的Python函数，而不是函数名称的字符串。

此函数将用于代替textwrap.wrap，因此它必须保持相同的接口。具体来说，它必须接受单个位置参数text（要处理的字符串）和一个单个关键字参数width（每行的最大字符数）。SOCIAL_CARDS_CHARS_PER_LINE设置的值将作为width参数传递。函数必须返回字符串列表，每个元素都是要绘制的文本行，且不包含换行符。

默认值：textwrap.wrap

SOCIAL_CARDS_CHARS_PER_LINE

一行中的最大字符数。此值将作为width关键字参数传递给SOCIAL_CARDS_WRAPPING_FUNCTION函数。SOCIAL_CARDS_WRAPPING_FUNCTION默认为textwrap.wrap()。

默认值：30

SOCIAL_CARDS_KEY_NAME

包含生成的图像路径（相对于Pelican设置OUTPUT_PATH）的文章/页面属性名称。

Open Graph元数据从未是Pelican标准内容元数据集的一部分，因此不同的主题和插件作者对如何指定这些数据有不同的想法。og_image似乎是最受欢迎的选择，但一些作者决定使用featured_image、image或header_cover。如果你使用的是使用这些属性之一的主题，此设置允许你在不更改主题的情况下使用插件。

请注意，此值也会影响上面“控制卡片上的文本”部分中描述的og_image_text属性。实际上，插件在使用文章标题作为文本来源之前，会先检查f"{SOCIAL_CARDS_KEY_NAME}_text"属性。因此，如果你将此设置更改为"featured_image"，则可以通过featured_image_text键按文章覆盖文本。

默认值: "og_image"

SOCIAL_CARDS_INCLUDE_SERIES

如果设置为True，则文章系列名称将包含在卡片上写入的文本中的标题之前。

系列名称由“Series”元数据键定义，如pelican-series插件所理解。

请注意，即使你没有安装系列插件，系列名称包含也会生效。如果你的帖子标题已经有了系列标识符，请将其设置为False。

默认值: False

SOCIAL_CARDS_SERIES_FORMAT

文章系列名称的字符串模板。

将使用Python format()方法调用此字符串，系列名称作为唯一参数。{}将被系列名称替换。使用{{替换字面{和}}替换字面}。如果你想要用大括号包围系列名称，请将其设置为{{{}}} 。

默认值: "{}: "

SOCIAL_CARDS_INCLUDE_SITEURL

如果设置为True，生成的图像路径（文章/页面og_image属性）将包含SITEURL设置值。

Open Graph元数据从未是Pelican标准内容元数据集的一部分，因此不同的主题和插件作者对每个帖子的og_image元数据是否应该是相对于构建网站根目录的路径，或完全指定的URL有不同的看法。相对路径似乎是更受欢迎的选择。然而，如果你使用的是期望og_image属性为完全指定URL的主题，此设置允许你在不更改主题的情况下使用插件。

默认值: False

SOCIAL_CARDS_INCLUDE_DRAFTS

为草稿文章和页面生成卡片图像。

默认值: False

SOCIAL_CARDS_INCLUDE_HIDDEN

为隐藏页面生成卡片图像。

默认值: False

SOCIAL_CARDS_FORCE_SAVE

如果存在同名文件，插件将跳过生成图像。此设置主要用于调试目的，但也可以用于当你更改SOCIAL_CARDS_TEMPLATE值时，更改设置比删除现有图像更容易，或者当你使用计算机加热并需要保持高CPU负载时。

默认值: False

贡献

欢迎并非常感谢贡献。每一点帮助都很大。你可以通过报告你遇到的问题、改进此文档以及提交代码更改来做出贡献。

我们主要遵循Pelican的一般指南，因此你可以从为Pelican做出贡献的文档开始，从“贡献代码”部分开始。