Liquid标签

此Pelican插件允许通过{% ... %}标签插入Liquid风格的标签到Pelican文档中的Markdown，这种约定也用于扩展其他发布平台（如Octopress）中的Markdown。

这组扩展实际上并不与Liquid接口，但允许用户定义自己的Liquid风格标签，这些标签将被插入到Markdown预处理器流中。下面提供了一些内置的标签。

安装

可以通过以下方式安装此插件

python -m pip install pelican-liquid-tags

有关插件安装的更详细说明，请参阅Pelican插件文档。

配置

虽然此插件提供了一整套内置标签（见下文），但默认情况下，这些标签都不会被导入和启用。为了在您的帖子中使用特定的标签，您需要在设置文件中显式启用它们

LIQUID_TAGS = ["img", "literal", "video", "youtube",
               "vimeo", "include_code"]

自定义标签中的配置设置

标签无法访问完整的 Pelican 设置，而是安排将变量传递给标签。计划将标签作为树内标签添加的标签作者只需将需要的变量添加到 mdx_liquid_tags.py 中的数组即可。树外标签作者可以通过包含一个包含（变量，默认值，帮助文本）的元组来指定它们需要的变量，通过适当的 Pelican 设置

LIQUID_CONFIGS = (('PATH', '.', "The default path"), ('SITENAME', 'Default Sitename', 'The name of the site'))

此插件中的标签

图片标签

要插入具有尺寸和标签的图片，请启用 img 标签，并使用以下内容

{% img [class name(s)] path/to/image [lazy | eager] [width [height]] [title text | "title text" ["alt text"]] %}

配置变量 IMG_DEFAULT_LOADING 可以更改插件的默认行为。lazy 设置优先于默认的 eager。如果设置了 lazy，则所有图片都将接收该属性。这与 eager 不同，因为这是浏览器遇到图片时的默认行为。在 liquid-tags 的 img 中显式指定的参数始终具有优先级，并将始终转换为属性。

Base64 图片（内联图片）标签

b64img 基于该 img 标签，但它不是插入图像链接，而是将图像编码为 Base64 文本，并插入到 <img src= 属性中。

要使用它

1. 启用 b64img
2. 插入标签如下：{% b64img [class name(s)] path/to/image [width [height]] [title text | "title text" ["alt text"]] %}

图像在生成时进行编码，因此您可以使用任何本地路径（只需确保图像在后续站点生成中保持在同一位置即可）。

Instagram 标签

要通过短代码（如 pFI0CAIZna）在文档中插入具有尺寸和标签的 Instagram 图片，请启用 gram 标签并使用以下内容

{% gram shortcode [size] [width] [class name(s)] [title text | "title text" ["alt text"]] %}

您可以使用 t、m 或 l 指定大小。

Flickr 标签

要将 Flickr 图片插入帖子，请按照以下步骤操作

1. 启用 flickr

2. 从 Flickr 获取 API 密钥

3. 将 FLICKR_API_KEY 添加到您的设置文件

4. 将其添加到您的源文档中

   {% flickr image_id [small|medium|large] ["alt text"|'alt text'] %}
   

Giphy 标签

要将 Giphy GIF 插入帖子，请按照以下步骤操作

1. 启用 giphy

2. 从 Giphy 获取 API 密钥

3. 将 GIPHY_API_KEY 添加到您的设置文件

4. 将其添加到您的源文档中

   {% giphy gif_id ["alt text"|'alt text'] %}
   

Soundcloud 标签

要将 Soundcloud 小部件插入到您的内容中，请按照以下步骤操作

1. 启用 soundcloud

2. 将其添加到您的源文档中

   {% soundcloud track_url %}
   

YouTube 标签

要将 YouTube 视频插入到您的内容中，请启用 youtube 插件并将以下内容添加到您的源文档中

{% youtube youtube_id [width] [height] %}

宽度和高度以像素为单位，是可选的。如果未指定，则尺寸将为 640（宽）x 390（高）。

如果您遇到代码生成问题（例如，缺少闭合标签），您可能需要在设置文件中添加 SUMMARY_MAX_LENGTH = None。

仅嵌入缩略图

如果您不希望在您的页面上添加 1+ 兆字节的 JS 代码，则可以嵌入链接缩略图。为此，在设置文件中设置一个 YOUTUBE_THUMB_ONLY 变量。变量 YOUTUBE_THUMB_SIZE 控制缩略图尺寸，有四种尺寸可供选择

name	xres	yres
maxres	1280	720
sd	640	480
hq	480	360
mq	320	180

嵌入的缩略图具有 CSS 类 youtube_video，可以用来添加一个 播放 按钮。

Vimeo 标签

要将 Vimeo 视频插入到您的内容中，请启用 vimeo 插件并将以下内容添加到您的源文档中

{% vimeo vimeo_id [width] [height] %}

宽度和高度以像素为单位，是可选的。如果未指定，则尺寸将为 640（宽）x 390（高）。

如果您遇到代码生成问题（例如，缺少闭合标签），您可能需要在设置文件中添加 SUMMARY_MAX_LENGTH = None。

Speakerdeck 标签

要将 Speakerdeck 查看器插入到您的内容中，请按照以下步骤操作

1. 启用 soundcloud 插件
2. 将其添加到您的源文档中

{% speakerdeck speakerdeck_id [ratio] %}

备注

• 比例是一个小数，是可选的。
• 比例必须是小数，小数点后的任何数字都是可选的。
• 如果没有指定比例，则默认为 1.33333333333333（4/3）。
• 常见的比例值为 1.77777777777777（16/9）。

视频标签

要将HTML5兼容的视频插入到您的内容中，启用video插件，并将以下内容添加到源文档中

{% video /url/to/video.mp4 [width] [height] [/path/to/poster.png] %}

宽度和高度以像素为单位，是可选的。如果未指定，则将使用原生视频尺寸。海报图像是视频播放前的预览图像。要链接到视频文件，请确保它位于静态目录中，已传输到您的服务器，并且可在指定的URL中访问。

音频标签

要将HTML5音频插入到帖子中，启用audio插件，并将以下内容添加到源文档中

{% audio url/to/audio [url/to/audio] [url/to/audio] %}

此标签支持最多三个音频URL参数，因此您可以添加不同的音频文件版本，因为不同的浏览器支持不同的文件格式。

要链接到音频文件，请确保它位于静态目录中，已传输到您的服务器，并且可在指定的URL中访问。

包含代码

要将文件中的代码包含到您的文档中，并可选地链接到原始文件，启用include_code插件，并将以下内容添加到源文档中

{% include_code path/to/code.py [lang:python] [lines:X-Y] [:hidefilename:] [:hidelink:] [:hideall:] [title] %}

path/to/code.py是源代码文件的路径，相对于内容文件夹中的CODE_DIR子目录。默认情况下CODE_DIR为code，您可以在设置文件中修改它。

CODE_DIR = 'code'

此外，为了使生成的超链接能够正常工作，此目录必须列在STATIC_PATHS设置中。例如

STATIC_PATHS = ['images', 'code']

所有其他参数都是可选的，但必须按照上述顺序指定。以下示例将显示文件的前十行。

{% include_code path/to/code.py lines:1-10 Test Example %}

要隐藏文件名，请使用:hidefilename:。当指定此标志时，必须提供标题。

您可以通过添加:hidelink:只隐藏下载链接，同时保留文件名。

如果您想要隐藏所有三个（标题、文件名和下载链接），请使用:hideall:。

以下示例隐藏了文件名

{% include_code path/to/code.py lines:1-10 :hidefilename: Test Example %}

IPython笔记本

要将IPython笔记本插入到您的帖子中，启用notebook插件，并将以下内容添加到源文档中

{% notebook filename.ipynb %}

文件应指定为相对于内容目录的notebooks子目录。可选地，您可以在设置文件中指定此子目录

NOTEBOOK_DIR = 'notebooks'

由于笔记本的转换和渲染相当复杂，此插件需要一些额外的步骤。首先，您必须安装IPython

  pip install ipython==2.4.1

在Pelican上运行包含IPython笔记本标签的内容后，主目录中将生成一个名为_nb_header.html的文件。此文件的內容应包含到您主题的头部中。一个简单的方法是在主题的头部模板中添加以下内容…

  {% if EXTRA_HEADER %}
  {{ EXTRA_HEADER }}
  {% endif %}

… 在您的设置文件中，包括以下行

  from io import open
  EXTRA_HEADER = open('_nb_header.html', encoding='utf-8').read()

这将向您的生成文档中插入正确的CSS格式化。

笔记本标签的可选参数

笔记本标签还有两个可选参数：cells和language。

• 您可以指定要包含的单元格的切片

  {% notebook filename.ipynb cells[2:8] %}

• 您还可以指定Pygments用于突出显示代码单元格的语言名称。有关Pygments可以突出显示的语言简写名称的列表，请参阅Pygments lexer列表。

  {% notebook filename.ipynb language[julia] %}

  这对于使用IJulia或支持其他语言的笔记本的用户可能很有帮助，特别是随着IPython项目扩大其范围以支持其他语言。默认的突出显示语言为ipython。

• 这些选项可以单独使用，一起使用，或者完全不使用。但是，如果同时使用这两个标签，那么cells必须在language之前。

  {% notebook filename.ipynb cells[2:8] language[julia] %}

IPython Notebooks中的可折叠代码

IPython插件还启用了可折叠代码输入框。为了使其工作，您必须首先将文件pelicanhtml_3.tpl（用于IPython 3.x）或pelicanhtml_2.tpl（用于IPython 2.x）复制到您内容目录的顶级位置。包含注释行`#

`的笔记本输入单元格将在HTML页面加载时折叠，并且可以通过点击它们来展开。包含注释行# <!-- collapse=False -->的单元格将在加载时展开，但可以通过点击它们的标题来折叠。没有折叠注释的单元格将作为标准代码输入单元格渲染。

兼容性

与Jinja2Content插件兼容

Jinja2Content插件允许您在Pelican文章和页面上使用Jinja2指令。当同时使用Liquid标签和Jinja2Content时，您可能会遇到问题，因为Liquid Tag的{% tag %}语法也是有效的Jinja2模板语法。

Jinja2Content会首先处理文件，然后仅处理由Jinja2渲染的内容。为了确保Liquid标签的顺畅运行，请确保{% tag %}语法出现在文件由Jinja2渲染之后。这可以通过Jinja2转义来实现。

 {% raw %}{% my_liquid_tag arguments %}{% endraw %}

 {{ '{%' }} my_liquid_tag arguments {{ '%}' }}

测试

要运行插件测试套件，请设置您的开发环境并运行

cd path/to/liquid_tags
invoke tests

要测试插件在多个环境中运行，请安装并使用Tox

tox

贡献

欢迎并非常感谢贡献。每一点帮助都很有价值。您可以通过改进文档、添加缺失功能以及修复错误来贡献。您还可以通过审查和评论现有问题来帮助。

要开始为此插件做出贡献，请查看Pelican贡献文档，从贡献代码部分开始。

感谢

感谢Jake Vanderplas创建此插件，该插件随后被数十位贡献者增强。