Jekyll Liquid Filters 完全指南：内置过滤器、自定义扩展与源码级原理解析

Jekyll Liquid Filters 完全指南内置过滤器、自定义扩展与源码级原理解析【免费下载链接】jekyll:globe_with_meridians: Jekyll is a blog-aware static site generator in Ruby项目地址: https://gitcode.com/gh_mirrors/je/jekyll本篇技术指南围绕 Jekyll 文档中心 docs/_docs/liquid/filters.md 展开系统梳理 Jekyll 对标准 Liquid 过滤器的完整支持、Jekyll 自研的三十余个实用过滤器URL 处理、日期格式化、集合查询、分组、转义与文本转换等、slugify的六种模式、where/where_exp的进阶用法并结合仓库源码与测试用例讲解其底层实现。读完本文你将能熟练地在模板中使用这些过滤器完成 URL 生成、日期排版、数据筛选、文本清洗等常见任务并掌握通过插件注册自定义过滤器的标准方法。一、概览两层过滤器体系Jekyll 的模板引擎基于 Liquid因此模板中天然拥有一整套 Liquid 官方过滤器。在此基础上Jekyll 又为常见任务补充了一批自研过滤器二者共同构成了模板层可用的过滤器全集标准 Liquid 过滤器由 Liquid 引擎提供Jekyll 全部支持见下文第三节完整清单Jekyll 自研过滤器定义于 lib/jekyll/filters.rb 及其子模块 lib/jekyll/filters/url_filters.rb、lib/jekyll/filters/date_filters.rb、lib/jekyll/filters/grouping_filters.rb在文件末尾通过Liquid::Template.register_filter(Jekyll::Filters)见 lib/jekyll/filters.rb注册到 Liquid 运行时。官方文档用一张由数据文件 docs/_data/jekyll_filters.yml 驱动的表格完整列出了每个 Jekyll 自研过滤器的名称、说明与输入/输出示例。该 YAML 文件本身就是一份可维护的过滤器文档清单每个条目包含name必填、description必填、version_badge可选标注引入版本和examples必填含input与可选output四个键。下文各节将逐一展开这些过滤器的用法与原理。二、URL 处理过滤器relative_url、absolute_url、strip_index2.1relative_url拼接baseurl生成站内相对路径功能将baseurl配置值前置到输入路径把 URL 路径转换为相对 URL。官方推荐将站点部署在域名子路径下时使用。{{ /assets/style.css | relative_url }} !-- 当 _config.yml 中 baseurl: /my-baseurl 时输出 -- !-- /my-baseurl/assets/style.css --源码原理见 lib/jekyll/filters/url_filters.rb。实现会先读取site.config[baseurl]空或 nil 时按处理sanitized_baseurl会去掉末尾斜杠然后通过Addressable::URI.parse(...).normalize规范化拼接结果。该过滤器带缓存site.filter_cache[:relative_url]相同输入只计算一次若输入本身已是带主机部分的绝对 URL则原样返回。2.2absolute_url拼接urlbaseurl生成绝对 URL功能将url与baseurl两个配置值前置到输入得到完整的绝对 URL。{{ /assets/style.css | absolute_url }} !-- 当 url: http://example.com 且 baseurl: /my-baseurl 时输出 -- !-- http://example.com/my-baseurl/assets/style.css --源码原理见 lib/jekyll/filters/url_filters.rb。compute_absolute_url先判断输入是否已是绝对 URLAddressable::URI.parse(input.to_s).absolute?是则直接返回否则若site.config[url]为 nil 或空串则退化为调用relative_url。同样带有结果缓存且返回前dup一份避免缓存值被后续过滤器误修改。需要注意这个过滤器依赖_config.yml中正确配置url与baseurl否则结果可能与预期不符。2.3strip_index去掉 URL 尾部的/index.html功能移除 URL 末尾的/index.html或/index.htm用于生成更美观的漂亮链接。{{ /about/index.html | strip_index }} !-- 输出 /about/ --源码原理见 lib/jekyll/filters/url_filters.rb实现为input.sub(%r!/index\.html?$!, /)——用/替换尾部/index.html保证路径语义完整。三、日期格式化过滤器族Jekyll 在 lib/jekyll/filters/date_filters.rb 中实现了 6 个日期过滤器全部基于 Ruby 标准库的时间格式化能力过滤器说明示例site.time为 2008-11-07 13:07:54 -0800date_to_xmlschema转为 XML SchemaISO 8601格式常用于 sitemap2008-11-07T13:07:54-08:00date_to_rfc822转为 RSS 订阅源使用的 RFC-822 格式Mon, 07 Nov 2008 13:07:54 -0800date_to_string短格式07 Nov 2008date_to_string: ordinal, US序数 美式短格式3.8.0 起Nov 7th, 2008date_to_long_string长格式07 November 2008date_to_long_string: ordinal序数 英式长格式3.8.0 起7th November 2008源码原理date_to_string与date_to_long_string分别对应strftime的%b缩写月份与%B全称月份模板type ordinal时通过ordinal(number)辅助方法生成st/nd/rd/th后缀11–13 一律为th见 lib/jekyll/filters/date_filters.rbstyle US时输出月份在前的%b %ordinal_day, %Y形式。输入为空字符串时过滤器会原样返回而不报错无效日期会抛出Errors::InvalidDateErrorlib/jekyll/filters/date_filters.rb。四、集合查询过滤器where、where_exp、find、find_exp4.1where按属性值筛选数组功能选出数组中指定键等于给定值的所有对象。{{ site.members | where: graduation_year, 2014 }}4.0 起支持检测nil与空值。原文档特别强调可以使用where检测属性为nil或空串的文档/页面——nil用于选中未定义my_prop或显式将其设为nil的文章而 Liquid 特殊字面量empty/blank用于选中属性为空值的文章{% assign filtered_posts site.posts | where: my_prop, nil %}{% assign filtered_posts site.posts | where: my_prop, empty %}源码原理见 lib/jekyll/filters.rb。实现的比较逻辑位于compare_property_vs_targetlib/jekyll/filters.rb目标值为NilClass时仅当属性本身为 nil 才匹配目标值为Liquid::Expression::MethodLiteral即empty/blank字面量时将属性与其字符串形式或将属性Array(property).join后的结果比较。此外where采用以输入哈希 属性 目标值为键的多级缓存同一组参数只筛选一次这是 Jekyll 对大型站点性能的常见优化手段。注意若目标值是 Array 或 Hash 实例过滤器会直接返回原输入源码注释说明原因是其to_s会得到inspect字符串比较没有意义。4.2where_exp用表达式筛选数组功能传入变量名与表达式选出表达式为真的所有对象。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 }}4.0 起支持二元操作符and/or。原文档给出两个示例筛选英语恐怖片需要同时满足两个条件用and连接筛选漫改电影MCU 或 DCEU 任一子类型则用or连接{{ 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 }}源码原理表达式解析逻辑位于 lib/jekyll/filters.rb是对 Liquidif标签解析器的移植与扩展parse_binary_comparison循环读取and/or关键字把每个子比较构造成Liquid::Condition并用condition.send(binary_operator, child_condition)链接成条件树where_exp在context.stack中逐项求值lib/jekyll/filters.rb。求值顺序遵循 Liquid 条件语义读者可自行在测试文件 test/test_filters.rbwhere filter与where_exp相关用例中查看覆盖情况。4.3find与find_exp返回第一个匹配项4.1.0 起新增。find返回数组中查询属性等于给定值的第一个对象find_exp返回表达式求值为真的第一个对象找不到时均返回nil。适合替代先where再取first的两步写法。{{ site.members | find: graduation_year, 2014 }} {{ site.members | find_exp: item, item.graduation_year 2014 }}源码原理见 lib/jekyll/filters.rb。find同样带多级缓存并使用占位字符串__NO MATCH__来区分已缓存的无匹配结果与未计算的 nil因为find本身可能返回nil或false无法直接用作缓存键。五、分组过滤器group_by与group_by_exp功能group_by按给定属性把数组分组group_by_exp3.4.0 起可用按 Liquid 表达式的结果分组。输出为 Hash 数组每个 Hash 形如{name 分组名, items 该组元素, size 组内元素数}。{{ site.members | group_by: graduation_year }} !-- [{name2013, items[...]}, {name2014, items[...]}] -- {{ site.members | group_by_exp: item, item.graduation_year | truncate: 3, }} !-- [{name201, items[...]}, {name200, items[...]}] --源码原理见 lib/jekyll/filters/grouping_filters.rb。group_by用input.group_by { |item| item_property(item, property).to_s }按属性字符串分组group_by_exp把表达式编译为Liquid::Variable在context.stack中对每个元素求值后分组grouped_array统一包装出带size的 Hash 结构。模板中常与for循环配合输出按年份归档的列表。六、转义与清洗过滤器6.1xml_escape、cgi_escape、uri_escape三者分别针对 XML、URL 查询串、URI 三种场景做转义{{ page.content | xml_escape }} {{ foo, bar; baz? | cgi_escape }} !-- foo%2Cbar%3Bbaz%3F空格转成 -- {{ http://foo.com/?qfoo, \bar? | uri_escape }} !-- 空格转成 %20保留 URI 保留字符 --源码原理见 lib/jekyll/filters.rb。xml_escape借助 Ruby 编码的:xml :attr模式并去除首尾引号cgi_escape直接委托CGI.escapeuri_escape使用Addressable::URI.normalize_component因此空格编码为%20而非且 RFC 3986 保留字符不会被转义注意上例中反斜杠被编码为%5C逗号与问号保留。6.2normalize_whitespace空白折叠功能把输入中任意连续空白替换为单个空格并去除首尾空白。{{ a \n b | normalize_whitespace }} !-- a b --源码原理input.to_s.gsub(%r!\s!, ).tap(:strip!)lib/jekyll/filters.rb。七、文本与内容转换过滤器7.1markdownify、smartify、sassify、scssify这组过滤器把模板中的字符串交给对应的 Jekyll 转换器处理常用于把page.excerpt等变量渲染成 HTML{{ page.excerpt | markdownify }} {{ page.title | smartify }} !-- 把 quotes 变成智能引号 -- {{ some_sass | sassify }} !-- Sass 字符串 → CSS -- {{ some_scss | scssify }} !-- SCSS 字符串 → CSS --源码原理见 lib/jekyll/filters.rb。四个过滤器均通过context.registers[:site].find_converter_instance(...)取得对应转换器实例Jekyll::Converters::Markdown、Jekyll::Converters::SmartyPants、Jekyll::Converters::Sass/Scss再执行convert因此在模板中调用的转换行为与构建站点时完全一致。7.2number_of_words统计单词数含 CJK 支持功能统计文本中的单词数。4.1.0 起接受可选参数控制中日韩CJK字符的计数方式{{ Hello world! | number_of_words }} !-- 2 -- {{ 你好hello世界world | number_of_words }} !-- 1整串算 1 个词 -- {{ 你好hello世界world | number_of_words: cjk }} !-- 6每个 CJK 字符计 1 词 -- {{ 你好hello世界world | number_of_words: auto }} !-- 6自动检测 --源码原理见 lib/jekyll/filters.rb。实现用 Unicode 属性正则\p{Han}\p{Katakana}\p{Hiragana}\p{Hangul}界定 CJK 字符集cjk模式把 CJK 字符与其余单词分开计数auto模式先统计 CJK 字符若为 0 则退化为普通split计数因此对可能含也可能不含 CJK 的变量字符串更高效默认模式直接input.split.length。7.3array_to_sentence_string数组转自然语言句子功能把字符串数组拼接成英文句子常用于罗列标签。第二个参数可自定义连接词默认and。{{ page.tags | array_to_sentence_string }} !-- foo, bar, and baz -- {{ page.tags | array_to_sentence_string: or }} !-- foo, bar, or baz --源码原理见 lib/jekyll/filters.rb。0 个元素返回空串、1 个返回元素本身、2 个用连接词相连、3 个以上按逗号分隔 连接词 末项拼接。八、slugify过滤器及其六种模式slugify把字符串转换为小写 URL 友好的slug是 Jekyll 页面/文章 URL 生成的基础设施之一。它接受一个可选参数指定过滤模式默认模式为default六种模式的含义如下均来自原文档模式过滤范围none不过滤任何字符raw仅过滤空格空格 → 连字符default过滤空格与非字母数字字符pretty过滤空格与非字母数字字符但保留._~!$(),;ascii过滤空格、非字母数字字符与非 ASCII 字符latin类似default但先将拉丁字符转写为纯字母如àèïòü→aeiou3.7.0 起可用官方示例见 docs/_data/jekyll_filters.yml 的slugify条目{{ 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ö → o --源码原理slugify委托给Utils.slugifylib/jekyll/filters.rb。核心实现在 lib/jekyll/utils.rb配套常量见 lib/jekyll/utils.rblatin模式先通过I18n.transliterate去除重音符号非拉丁字符会变成?之后按模式选择正则raw为\sdefault为[^\p{M}\p{L}\p{Nd}]保留字母、数字与组合记号pretty为[^\p{M}\p{L}\p{Nd}._~!$(),;]ascii为[^A-Za-z0-9]连续匹配统一替换为连字符随后去掉首尾连字符并downcase!若生成的 slug 为空会通过Jekyll.logger.warn输出警告Emptysluggenerated传入未识别的模式时不做任何替换仅小写后返回。测试用例 test/test_filters.rb 中的slugify filter分组验证了 Q*bert says !#?!在默认与pretty模式下的输出差异。九、其他实用过滤器速查以下过滤器同样由 Jekyll 提供日常模板开发中非常常用jsonify把 Hash/Array 转为 JSON 字符串{{ site.data.projects | jsonify }}常用于在页面中嵌入数据。实现见 lib/jekyll/filters.rb会先把对象经to_liquid逐层液化防止递归再to_json。sort排序数组支持按属性排序与 nil 值位置控制——第二参数为属性名第三参数为first默认nil 在前或lastnil 在后{{ site.posts | sort: author }}、{{ site.pages | sort: title, last }}。实现见 lib/jekyll/filters.rb内部使用 Schwartzian 变换sort_input提升效率并会把数字字符串解析为数值以保证排序正确。sample随机取一个元素可传数量取多个{{ site.pages | sample }}、{{ site.pages | sample: 2 }}。to_integer字符串或布尔值转整数true→1false→0见 lib/jekyll/filters.rb。push/pop/shift/unshift数组增删元素的非破坏性版本——不修改原数组而是复制后操作内部array.dup见 lib/jekyll/filters.rb{{ 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 }}实现会先inspect再xml_escape以保证输出安全。十、标准 Liquid 过滤器全集Jekyll 完整支持以下 50 个标准 Liquid 过滤器原文档在 docs/_docs/liquid/filters.md 的 front matter 中维护了这份清单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。这些过滤器由 Liquid 引擎自身实现可以直接与上文介绍的 Jekyll 自研过滤器混用例如site.posts | map: title | join: , 或where_exp表达式中内嵌truncate管道见第五节示例。十一、扩展创建你自己的过滤器原文档明确指出当内置过滤器不满足需求时可以通过插件注册自定义过滤器。标准做法是在站点的_plugins目录下新建 Ruby 文件仓库测试夹具目录 test/fixtures/source/_plugins 中即有这样的示例插件# _plugins/my_filters.rb module Jekyll module MyFilters def my_filter(input) # 自定义处理逻辑 end end end Liquid::Template.register_filter(Jekyll::MyFilters)注册后即可在任意模板中使用{{ value | my_filter }}。插件过滤器能访问当前渲染上下文context从而读取site、page等全局数据——这正是 Jekyll 内置过滤器读取站点配置的方式。更详细的插件开发指引可参考 docs/_docs/plugins/filters.md。十二、测试与源码索引若想深入验证本文所述行为可在仓库中直接查看以下位置核心过滤器实现lib/jekyll/filters.rb文本、转义、集合查询、排序、数组操作、inspect等以及最后的过滤器注册语句 lib/jekyll/filters.rbURL 子模块lib/jekyll/filters/url_filters.rbrelative_url/absolute_url/strip_index日期子模块lib/jekyll/filters/date_filters.rbdate_to_*系列分组子模块lib/jekyll/filters/grouping_filters.rbgroup_by/group_by_expslugify底层逻辑与正则常量lib/jekyll/utils.rb 与 lib/jekyll/utils.rb官方文档表格数据源docs/_data/jekyll_filters.yml单元测试test/test_filters.rb覆盖smartify、normalize_whitespace、absolute_url、relative_url、strip_index、jsonify、group_by、where、find、sort、to_integer、inspect、push/pop/shift/unshift、sample、number_of_words、slugify等过滤器。结语Jekyll 的过滤器体系标准 Liquid 自研扩展双轨并行50 个标准过滤器覆盖字符串、数学、数组等通用操作30 余个自研过滤器则针对静态站点生成场景提供了 URL 拼接、日期排版、集合查询、分组归档、内容转换等开箱即用的能力。理解它们的输入输出约定与源码实现缓存、非破坏性、配置依赖等细节能帮助你在模板中写出更简洁、更高效的 Liquid 代码而_plugins机制则为无法覆盖的场景保留了充分的扩展空间。【免费下载链接】jekyll:globe_with_meridians: Jekyll is a blog-aware static site generator in Ruby项目地址: https://gitcode.com/gh_mirrors/je/jekyll创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考