Jekyll中文文档__Liquid

杜经艺

2023-12-01

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

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

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

Liquid Filters

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

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

Description Filter and Output

Description	Filter and Output
Relative URL Prepend `baseurl` config value to the input to convert a URL path into a relative URL. This is recommended for a site that is hosted on a subpath of a domain.	`{{ "/assets/style.css" \| relative_url }}` `/my-baseurl/assets/style.css`
Absolute URL Prepend `url` and `baseurl` values to the input to convert a URL path to an absolute 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 Select all the objects in an array where the key has the given value.	`{{ site.members \| where:"graduation_year","2014" }}`
Where Expression Select all the objects in an array where the expression is 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 Return the first object in an array for which the queried attribute has the given value or return `nil` if no item in the array satisfies the given criteria. 4.1.0	`{{ site.members \| find: "graduation_year", "2014" }}`
Find Expression Return the first object in an array for which the given expression evaluates to true or return `nil` if no item in the array satisfies the evaluated expression. 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 Group an array's items by a given property.	`{{ site.members \| group_by:"graduation_year" }}` `[{"name"=>"2013", "items"=>[...]}, {"name"=>"2014", "items"=>[...]}]`
Group By Expression Group an array's items using a Liquid expression. 3.4.0	`{{ site.members \| group_by_exp: "item", "item.graduation_year \| truncate: 3, ''" }}` `[{"name"=>"201", "items"=>[...]}, {"name"=>"200", "items"=>[...]}]`
XML Escape Escape some text for use in XML.	`{{ page.content \| xml_escape }}`
CGI Escape CGI escape a string for use in a URL. Replaces any special characters with appropriate `%XX` replacements. CGI escape normally replaces a space with a plus `+` sign.	`{{ "foo, bar; baz?" \| cgi_escape }}` `foo%2C+bar%3B+baz%3F`
URI Escape Percent encodes any special characters in a URI. URI escape normally replaces a space with `%20`. Reserved characters will not be escaped.	`{{ "http://foo.com/?q=foo, \bar?" \| uri_escape }}` `http://foo.com/?q=foo,%20%5Cbar?`
Number of Words Count the number of words in some text. From v4.1.0, this filter takes an optional argument to control the handling of Chinese-Japanese-Korean (CJK) characters in the `input` string. Passing `'cjk'` as the argument will count every CJK character detected as one word irrespective of being separated by whitespace. Passing `'auto'` (auto-detect) works similar to `'cjk'` but is more performant if the filter is used on a variable string that may or may not contain CJK chars.	`{{ "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 Convert an array into a sentence. Useful for listing tags. Optional argument for connector.	`{{ page.tags \| array_to_sentence_string }}` `foo, bar, and baz` `{{ page.tags \| array_to_sentence_string: "or" }}` `foo, bar, or baz`
Markdownify Convert a Markdown-formatted string into 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 Convert a string into a lowercase URL "slug". See below for options.	`{{ "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 Replace any occurrence of whitespace with a single space.	`{{ "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 Pick a random value from an array. Optionally, pick multiple values.	`{{ site.pages \| sample }}` `{{ site.pages \| sample: 2 }}`
To Integer Convert a string or boolean to integer.	`{{ some_var \| to_integer }}`
Array Filters Push, pop, shift, and unshift elements from an Array. These are NON-DESTRUCTIVE, i.e. they do not mutate the array, but rather make a copy and mutate that.	`{{ page.tags \| push: "Spokane" }}` `["Seattle", "Tacoma", "Spokane"]` `{{ page.tags \| pop }}` `["Seattle"]` `{{ page.tags \| shift }}` `["Tacoma"]` `{{ page.tags \| unshift: "Olympia" }}` `["Olympia", "Seattle", "Tacoma"]`
Inspect Convert an object into its String representation for debugging.	`{{ some_var \| inspect }}`
======================================	=============================================================

Relative URL

Prepend baseurl config value to the input to convert a URL path into a relative URL. This is recommended for a site that is hosted on a subpath of a domain.

{{ "/assets/style.css" | relative_url }}

/my-baseurl/assets/style.css

Absolute URL

Prepend url and baseurl values to the input to convert a URL path to an absolute 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

Select all the objects in an array where the key has the given value.

{{ site.members | where:"graduation_year","2014" }}

Where Expression

Select all the objects in an array where the expression is 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

Return the first object in an array for which the queried attribute has the given value or return nil if no item in the array satisfies the given criteria. 4.1.0

{{ site.members | find: "graduation_year", "2014" }}

Find Expression

Return the first object in an array for which the given expression evaluates to true or return nil if no item in the array satisfies the evaluated expression. 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

Group an array's items by a given property.

{{ site.members | group_by:"graduation_year" }}

[{"name"=>"2013", "items"=>[...]}, {"name"=>"2014", "items"=>[...]}]

Group By Expression

Group an array's items using a Liquid expression. 3.4.0

{{ site.members | group_by_exp: "item", "item.graduation_year | truncate: 3, ''" }}

[{"name"=>"201", "items"=>[...]}, {"name"=>"200", "items"=>[...]}]

XML Escape

Escape some text for use in XML.

{{ page.content | xml_escape }}

CGI Escape

CGI escape a string for use in a URL. Replaces any special characters with appropriate %XX replacements. CGI escape normally replaces a space with a plus + sign.

{{ "foo, bar; baz?" | cgi_escape }}

foo%2C+bar%3B+baz%3F

URI Escape

Percent encodes any special characters in a URI. URI escape normally replaces a space with %20. Reserved characters will not be escaped.

{{ "http://foo.com/?q=foo, \bar?" | uri_escape }}

http://foo.com/?q=foo,%20%5Cbar?

Number of Words

Count the number of words in some text.
From v4.1.0, this filter takes an optional argument to control the handling of Chinese-Japanese-Korean (CJK) characters in the input string.
Passing 'cjk' as the argument will count every CJK character detected as one word irrespective of being separated by whitespace.
Passing 'auto' (auto-detect) works similar to 'cjk' but is more performant if the filter is used on a variable string that may or may not contain CJK chars.

{{ "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

Convert an array into a sentence. Useful for listing tags. Optional argument for connector.

{{ page.tags | array_to_sentence_string }}

foo, bar, and baz

{{ page.tags | array_to_sentence_string: "or" }}

foo, bar, or baz

Markdownify

Convert a Markdown-formatted string into 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

Convert a string into a lowercase URL "slug". See below for options.

{{ "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

Replace any occurrence of whitespace with a single space.

{{ "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

Pick a random value from an array. Optionally, pick multiple values.

{{ site.pages | sample }}

{{ site.pages | sample: 2 }}

To Integer

Convert a string or boolean to integer.

{{ some_var | to_integer }}

Array Filters

Push, pop, shift, and unshift elements from an Array. These are NON-DESTRUCTIVE, i.e. they do not mutate the array, but rather make a copy and mutate that.

{{ page.tags | push: "Spokane" }}

["Seattle", "Tacoma", "Spokane"]

{{ page.tags | pop }}

["Seattle"]

{{ page.tags | shift }}

["Tacoma"]

{{ page.tags | unshift: "Olympia" }}

["Olympia", "Seattle", "Tacoma"]

Inspect

Convert an object into its String representation for debugging.

{{ some_var | inspect }}

====================================== =============================================================

Options for the `slugify` filter

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

none: 没有字符
raw: 空格
default: 空格和"非字母数字"字符
pretty: 空格和"非字母数字"字符，但除了 ._~!$&'()+,;=@
ascii: 空格, "非字母数字"字符, 以及非 ASCII 字符
latin: 类似 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文档中示例的链接。

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

要链接到文章、页面、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 %})

返回目录

Jekyll中文文档__Liquid

Liquid Filters

Options for the `slugify` filter

Detecting `nil` values with `where` filter (4.0)

Binary operators in `where_exp` filter (4.0)

Standard Liquid Filters

Tags

Includes

Code snippet highlighting

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

Line numbers

Marking specific lines (4.4.0)

Stylesheets for syntax highlighting

Links

Linking to pages

Linking to posts

相关阅读

相关文章

相关问答

相关文档

Jekyll中文文档__Liquid

Liquid Filters

Options for the slugify filter

Detecting nil values with where filter (4.0)

Binary operators in where_exp filter (4.0)

Standard Liquid Filters

Tags

Includes

Code snippet highlighting

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

Line numbers

Marking specific lines (4.4.0)

Stylesheets for syntax highlighting

Links

Linking to pages

Linking to posts

相关阅读

相关文章

相关问答

相关文档

Options for the `slugify` filter

Detecting `nil` values with `where` filter (4.0)

Binary operators in `where_exp` filter (4.0)