Improve this page

Liquid Filters

所有标准的 Liquid 过滤器 都受支持（请参见下文）。

为了简化常见任务，Jekyll 甚至添加了一些实用的过滤器，所有这些过滤器你可以在本页面找到。你还可以使用 插件 创建自己的过滤器。

描述 过滤器（Filter） 和 输出（Output）

相对 URL

在输入路径前添加 baseurl 配置值，将一个 URL 路径转换为相对 URL。 如果你的网站托管在域名的子路径下，建议使用这种方式。

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

/my-baseurl/assets/style.css

绝对 URL

在输入路径前添加 url 和 baseurl 的值，将一个 URL 路径转换为绝对 URL。

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

http://example.com/my-baseurl/assets/style.css

日期转为 XML Schema 格式

将一个日期转换为 XML Schema（ISO 8601）格式。

{{ site.time | date_to_xmlschema }}

2008-11-07T13:07:54-08:00

日期转为 RFC-822 格式

将一个日期转换为 RSS 订阅中使用的 RFC-822 格式。

{{ site.time | date_to_rfc822 }}

Mon, 07 Nov 2008 13:07:54 -0800

日期转为简短字符串

将日期转换为简短格式。

{{ site.time | date_to_string }}

07 Nov 2008

日期转为美式序数简短格式

将日期格式化为序数形式的美国简短格式。 3.8.0

{{ site.time | date_to_string: "ordinal", "US" }}

Nov 7th, 2008

日期转为长字符串

将日期格式化为长格式。

{{ site.time | date_to_long_string }}

07 November 2008

日期转为英式序数长格式

将日期格式化为序数形式的英国长格式。 3.8.0

{{ site.time | date_to_long_string: "ordinal" }}

7th November 2008

条件筛选（where）

从数组中选出所有某个键具有指定值的对象。

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

表达式筛选（Where Expression）

从数组中选出所有使表达式成立的对象。 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）

返回数组中第一个使给定表达式成立的对象， 若无匹配项则返回 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 转义（XML Escape）

对文本进行转义以用于 XML。

{{ page.content | xml_escape }}

CGI 转义（CGI Escape）

对字符串进行 CGI 转义以用于 URL。将任何特殊字符替换为相应的 %XX 编码。 通常会将空格替换为加号 +。

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

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

URI 转义（URI Escape）

对 URI 中的特殊字符进行百分号编码。 通常会将空格替换为 %20。 保留字符 不会被转义。

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

将数组转换为语句形式，适用于列出标签。 可选参数用于指定连接词。

{{ page.tags | array_to_sentence_string }}

foo, bar, and baz

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

foo, bar, or baz

Markdown 转 HTML（Markdownify）

将 Markdown 格式的字符串转换为 HTML。

{{ page.excerpt | markdownify }}

智能引号（Smartify）

将 "直角引号" 转换为 “智能引号”。

{{ page.title | smartify }}

Sass/SCSS 转换（Converting Sass/SCSS）

将 Sass 或 SCSS 格式的字符串转换为 CSS。

{{ some_sass | sassify }}

{{ some_scss | scssify }}

Slug 化（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

数据转 JSON（Data To JSON）

将 Hash 或数组转换为 JSON 格式。

{{ site.data.projects | jsonify }}

空白规范化（Normalize Whitespace）

将所有空白字符替换为单个空格。

{{ "a \n b" | normalize_whitespace }}

排序（Sort）

对数组进行排序。对哈希排序时可选两个参数： 1. 属性名称 2. 空值位置（first 或 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 }}

slugify 过滤器的选项

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

  • none: 不过滤任何字符
  • raw: 过滤空格
  • default: 过滤空格和非字母数字字符
  • pretty: 过滤空格和非字母数字字符，但保留 ._~!$&'()+,;=@
  • ascii: 过滤空格、非字母数字字符和非 ASCII 字符
  • latin: 类似于 default，但首先会将拉丁字符进行音译（例如，将 àèïòü 转换为 aeiou）3.7.0 。

使用 where 过滤器检测 nil 值4.0

你可以使用 where 过滤器来检测属性为 nil 或 "" 的文档和页面。例如，

// 使用 `nil` 来选择那些没有定义 `my_prop` 
// 或者 `my_prop` 已经明确设置为 `nil` 的帖子。
{% assign filtered_posts = site.posts | where: 'my_prop', nil %}

// 使用 Liquid 的特殊字面量 `empty` 或 `blank` 来选择
// `my_prop` 被设置为空值的帖子。
{% assign filtered_posts = site.posts | where: 'my_prop', empty %}

where_exp 过滤器中的二元运算符4.0

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

例如，要获取英文恐怖片的文档列表，可以使用以下代码：

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

或者，要获取基于漫画书的电影列表，可以使用以下代码：

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

标准 Liquid 过滤器

为了方便你使用，这里列出了所有的 Liquid 过滤器，并提供了指向按照官方 Liquid 文档翻译后的示例链接。