Jekyll中的Liquid

Jekyll使用 Liquid 模板语言来处理模板。

通常在 Liquid 中，您使用两个大括号（例如 {{ variable }} ）输出内容，并通过用大括号百分号（例如 {% if statement %} ）包围它们来执行逻辑语句。要了解更多关于Liquid的信息，请查看 official Liquid Documentation 。

Jekyll 提供了许多有用的 Liquid 附加项，可以帮助您建立网站：

Liquid Filters

支持所有标准 Liquid filters（见下文）。

为了简化常见任务，Jekyll 甚至添加了一些自己的方便过滤器，所有这些都可以在这个页面上找到。您也可以使用 plugins 创建自己的过滤器。

Description	Filter and Output
Relative URL 将 baseurl 配置值前置到输入，以将URL路径转换为相对URL。对于托管在域的子路径上的网站，建议这样做。	{{ "/assets/style.css" | relative_url }} /my-baseurl/assets/style.css
Absolute URL 将 url 和 baseurl 值前置到输入，以将 url 路径转换为绝对 url 。	{{ "/assets/style.css" | absolute_url }} http://example.com/my-baseurl/assets/style.css
Date to XML Schema Convert a Date into XML Schema (ISO 8601) format	{{ site.time | date_to_xmlschema }} 2008-11-07T13:07:54-08:00
Date to RFC-822 Format Convert a Date into the RFC-822 format used for RSS feeds	{{ site.time | date_to_rfc822 }} Mon, 07 Nov 2008 13:07:54 -0800
Date to String Convert a date to short format	{{ site.time | date_to_string }} 07 Nov 2008
Date to String in ordinal US style Format a date to ordinal, US, short format(3.8.0)	{{ site.time | date_to_string: "ordinal", "US" }} Nov 7th, 2008
Date to Long String Format a date to long format	{{ site.time | date_to_long_string }} 07 November 2008
Date to Long String in ordinal UK style Format a date to ordinal, UK, long format(3.8.0)	{{ site.time | date_to_long_string: "ordinal" }} 7th November 2008
Where 选择数组中"键"具有给定值的所有对象。	{{ site.members | where:"graduation_year","2014" }} 7th November 2008
Where Expression 选择数组中表达式为 true 的所有对象。(3.2.0)	{{ site.members | where_exp:"item","item.graduation_year == 2014" }} {{ site.members | where_exp:"item","item.graduation_year < 2014" }} {{ site.members | where_exp:"item","item.projects contains 'foo'" }}
Find 返回数组中查询的属性具有给定值的第一个对象，或者如果数组中没有项满足给定条件，则返回 nil 。(4.1.0)	{{ site.members | find: "graduation_year", "2014" }}
Find Expression 返回数组中给定表达式计算结果为 true 的第一个对象，如果数组中没有项满足计算结果的表达式，则返回 nil 。(4.1.0)	{{ site.members | find_exp:"item","item.graduation_year == 2014" }} {{ site.members | find_exp:"item","item.graduation_year < 2014" }} {{ site.members | find_exp:"item","item.projects contains 'foo'" }}
Group By 根据给定的属性对数组的项进行分组。	{{ site.members | group_by:"graduation_year" }} [{"name"=>"2013", "items"=>[...]},{"name"=>"2014", "items"=>[...]}]
Group By Expression 使用 Liquid 表达式对数组的项进行分组。(3.4.0)	{{ site.members | group_by_exp: "item","item.graduation_year | truncate: 3, ''" }} [{"name"=>"201", "items"=>[...]},{"name"=>"200", "items"=>[...]}]
XML Escape 转义一些文本以用于XML。	{{ page.content | xml_escape }}
CGI Escape CGI对字符串进行转义，以便在URL中使用。用适当的 %XX 替换符来替换任何特殊字符。CGI转义通常用加号+ 替换空格。	{{ "foo, bar; baz?" | cgi_escape }} foo%2C+bar%3B+baz%3F
URI Escape Percent对URI中的任何特殊字符进行编码。URI转义通常用 %20 替换空格 。Reserved characters 将不会被转义。	{{ "http://foo.com/?q=foo, \bar?" | uri_escape }} http://foo.com/?q=foo,%20%5Cbar?
Number of Words 计算某些文本中的字数。从v4.1.0开始，此筛选器使用一个可选参数来控制输入字符串中"中日韩"（CJK）字符的处理。传递'CJK'作为参数将把检测到的每个CJK字符计算为一个单词，而不考虑是否用空格分隔。传递'auto'（自动检测）的工作原理与'CJK'类似，但如果过滤器用于可能包含也可能不包含CJK字符的变量字符串，则性能会更好。	{{ "Hello world!" | number_of_words }} 2 {{ "你好hello世界world" | number_of_words }} 1 {{ "你好hello世界world" | number_of_words: "cjk" }} 6 {{ "你好hello世界world" | number_of_words: "auto" }} 6
Array to Sentence 将数组转换成句子。用于列出 tags 。连接器的可选参数。	{{ page.tags | array_to_sentence_string }} foo, bar, and baz {{ page.tags | array_to_sentence_string: "or" }} foo, bar, or baz
Markdownify 将Markdown格式的字符串转换为HTML。	{{ page.excerpt | markdownify }}
Smartify Convert "quotes" into “smart quotes.”	{{ page.title | smartify }}
Converting Sass/SCSS Convert a Sass- or SCSS-formatted string into CSS.	{{ some_sass | sassify }} {{ some_scss | scssify }}
Slugify 将字符串转换为小写URL 'slug'。请参阅以下选项。	{{ "The _config.yml file" | slugify }} the-config-yml-file {{ "The _config.yml file" | slugify: "pretty" }} the-_config.yml-file {{ "The _cönfig.yml file" | slugify: "ascii" }} the-c-nfig-yml-file {{ "The cönfig.yml file" | slugify: "latin" }} the-config-yml-file
Data To JSON Convert Hash or Array to JSON.	{{ site.data.projects | jsonify }}
Normalize Whitespace 用单个空格替换任何出现的空格。	{{ "a \n b" | normalize_whitespace }}
Sort Sort an array. Optional arguments for hashes 1. property name 2. nils order (first or last).	{{ page.tags | sort }} {{ site.posts | sort: "author" }} {{ site.pages | sort: "title", "last" }}
Sample 从数组中选择一个随机值。（可选）选择多个值。	{{ site.pages | sample }} {{ site.pages | sample: 2 }}
To Integer 将字符串或布尔值转换为整数。	{{ some_var | to_integer }}
Array Filters 从数组中Push, pop, shift, 以及 unshift元素。这些是非破坏性的，即它们不会使数组发生突变，而是复制并使其发生突变。	{{ page.tags | push: "Spokane" }} ["Seattle", "Tacoma", "Spokane"] {{ page.tags | pop }} ["Seattle"] {{ page.tags | shift }} ["Tacoma"] {{ page.tags | unshift: "Olympia" }} ["Olympia", "Seattle", "Tacoma"]
Inspect 将对象转换为其字符串表示形式以进行调试。	{{ some_var | inspect }}
=====================================	================================================================

Options for the slugify filter

slugify过滤器接受一个选项，每个选项都指定要过滤的内容。默认值为 default 。它们如下（以及它们过滤的内容）：

• none: no characters
• raw: spaces
• default: spaces and non-alphanumeric characters
• pretty: spaces and non-alphanumeric characters except for ._~!$&'()+,;=@
• ascii: spaces, non-alphanumeric, and non-ASCII characters
• latin: like default, 除了拉丁字符是第一个音译的 (e.g. àèïòü to aeiou) (3.7.0)

Detecting nil values with where filter (4.0)

您可以使用where筛选器检测属性为为 nil or "" 的文档和页面。例如

// Using `nil` to select posts that either do not have `my_prop`
// defined or `my_prop` has been set to `nil` explicitly.
{% assign filtered_posts = site.posts | where: 'my_prop', nil %}

// Using Liquid's special literal `empty` or `blank` to select
// posts that have `my_prop` set to an empty value.
{% assign filtered_posts = site.posts | where: 'my_prop', empty %}

Binary operators in where_exp filter (4.0)

可以在传递给 where_exp 过滤器的表达式中使用Liquid二进制运算 or and and ，以便在操作中使用多个条件。

例如，要获得 English horror flicks 的文档列表，可以使用以下片段：

{{ site.movies | where_exp: "item", "item.genre == 'horror' and item.language == 'English'" }}

或者，要获得基于 comic-book 的电影列表，可以使用以下内容：

{{ site.movies | where_exp: "item", "item.sub_genre == 'MCU' or item.sub_genre == 'DCEU'" }}

Standard Liquid Filters

为了方便您，以下是所有 Liquid filters 的列表，并附有官方Liquid文档中示例的链接。

• abs

• append

• at_least

• at_most

• capitalize

• ceil

• compact

• concat

• date

• default

• divided_by

• downcase

• escape

• escape_once

• first

• floor

• join

• last

• lstrip

• map

• minus

• modulo

• newline_to_br

• plus

• prepend

• remove

• remove_first

• replace

• replace_first

• reverse

• round

• rstrip

• size

• slice

• sort

• sort_natural

• split

• strip

• strip_html

• strip_newlines

• times

• truncate

• truncatewords

• uniq

• upcase

• url_decode

• url_encode

Tags

支持所有标准的 Liquid tags。Jekyll有一些内置tags可以帮助你建立你的网站。您也可以使用 plugins 创建自己的tags。

Includes

如果您有在整个网站上重复使用的页面片段，那么 include 是使其更易于维护的完美方法。

Code snippet highlighting

得益于 Rouge ，Jekyll内置了对100多种语言语法高亮显示的支持。Rouge是Jekyll 3及以上版本中默认的 highlighter 。

注意：
使用Pygments已被弃用，在Jekyll 4中不支持使用；配置设置 highlighter: pygments 现在自动恢复使用Rouge，Rouge是用Ruby编写的，与 Pygments 的样式表100%兼容。

要使用语法高亮显示来渲染代码块，请按如下方式环绕代码：

{% highlight ruby %}
def foo
  puts 'foo'
end
{% endhighlight %}

highlight tag 的参数（上例中的ruby）是语言标识符。要为要突出显示的语言找到合适的标识符，请在 Rouge wiki 上查找 “short name” 。

Jekyll在代码块中处理所有Liquid过滤器

如果您使用的语言包含大括号，则可能需要在代码周围放置 {%raw%} 和 {%endraw%} tags。自Jekyll 4.0以来，您可以在 front matter 中添加 render_with_liquid: false ，以完全禁用特定文档的 Liquid 。

Line numbers

还有第二个 highlight 的参数 linenos 是可选的。包含 linenos 参数将强制高亮显示的代码包含行号。例如，下面的代码块将在每行旁边包含行号:

{% highlight ruby linenos %}
def foo
  puts 'foo'
end
{% endhighlight %}

Marking specific lines (4.4.0)

您可以使用可选参数mark_lines来标记代码段中的特定行。此参数采用一个以空格分隔的行号列表，该列表必须用双引号括起来。例如，以下代码块将标记第1行和第2行，但不标记第3行：

{% highlight ruby mark_lines="1 2" %}
def foo
  puts 'foo'
end
{% endhighlight %}

hll 的默认类名将应用于标记的行。

Stylesheets for syntax highlighting

为了让高亮显示生效，您需要包含一个高亮显示样式表。对于Pygments或Rouge，您可以使用Pygments的样式表，您可以在 here 或 its repository 中找到示例库。

将CSS文件（例如 native.css ）复制到CSS目录中，并将语法高亮样式导入到 main.css 中：

@import "native.css";

Links

注意：
自从Jekyll 4.0以来，您不需要将 site.baseurl 加在 link 和 post_url tags 的前面。

Linking to pages {#link}

要链接到文章、页面、collection item或文件，link tag 将为您指定的路径生成正确的 permalink URL 。例如，如果您使用 link tag 链接到 mypage.html ，即使您更改了 permalink 样式以包含或省略文件扩展名，link tag 形成的URL也将始终有效。

使用 link tag 时，必须包含文件的原始扩展名。以下是一些例子：

{% link _collection/name-of-document.md %}
{% link _posts/2016-07-26-name-of-post.md %}
{% link news/index.html %}
{% link /assets/files/doc.pdf %}

您也可以使用 link tag 在Markdown中创建链接，如下所示：

[Link to a document]({% link _collection/name-of-document.md %})
[Link to a post]({% link _posts/2016-07-26-name-of-post.md %})
[Link to a page]({% link news/index.html %})
[Link to a file]({% link /assets/files/doc.pdf %})

文章、页面或 collection 的路径定义为相对于文件根目录（配置文件所在的位置）的路径，而不是从现有页面到其他页面的路径。

例如，假设您正在 page_a.md (存储在pages/folder1/folder2中)中创建到 page_b.md(存储在pages/folder1中)的链接。你在链接中的路径不会是../page_b.html。相反，它将是/pages/folder1/page_b.md。

如果您不确定路径，请将{{ page.path }}添加到页面中，它将显示路径。

使用link 或 post_url tag的一个主要好处是链接验证。如果链接不存在，Jekyll就不会建立你的网站。这是一件好事，因为它会提醒你链接断开，这样你就可以修复它（而不是允许你构建和部署一个链接断开的网站）。

请注意，不能将筛选器添加到link tags中。例如，不能使用 Liquid filters 附加字符串，例如 {% link mypage.html | append: "#section1" %} 。要链接到页面上的 sections ，您需要使用常规的HTML或Markdown链接技术。

可以将要链接的文件名指定为变量，而不是实际的文件名。例如，假设您在页面的 front matter 中定义了一个变量，如下所示：

---
title: My page
my_variable: footer_company_a.html
---

然后，您可以在链接中引用该变量：

{% link {{ page.my_variable }} %}

在本例中，link tag 将渲染一个指向文件 footer_company_a.html 的链接。

Linking to posts

如果你想在网站上包含一个文章链接，post_url tag 会为你指定的文章生成正确的 permalink URL 。

{% post_url 2010-07-21-name-of-post %}

如果你在子目录中组织你的文章，你需要引入文章的子目录路径：

{% post_url /subdir/2010-07-21-name-of-post %}

使用 post_url tag 时，不需要包含文件扩展名。

您也可以使用此 tag 创建指向Markdown中文章的链接，如下所示：

[Name of Link]({% post_url 2010-07-21-name-of-post %})

上一页	目录	下一页