Jekyll Liquid模板语言完全指南：必备语法、内置Filters与自定义Tags一网打尽

Jekyll Liquid模板语言完全指南：必备语法、内置Filters与自定义Tags一网打尽

【免费下载链接】jekyll:globe_with_meridians: Jekyll is a blog-aware static site generator in Ruby项目地址: https://gitcode.com/gh_mirrors/je/jekyll

Jekyll 是一款用 Ruby 编写的博客感知型静态站点生成器，它的"灵魂"就是 Liquid 模板语言——你在 Jekyll 中写下的每一段页面逻辑，几乎都靠 Liquid 的变量、过滤器和标签来完成。这篇指南带你一次吃透 Liquid 模板语法：从最基础的双花括号变量，到 Jekyll 独家扩展的内置 Filters，再到 include、highlight 等 5 个实用内置 Tags，最后还教你如何用十几行 Ruby 代码写出属于自己的自定义 Tag。

1️⃣ Liquid 是什么？三套"符号"撑起模板

Jekyll 在处理 Markdown、HTML 文件时，会先用 Liquid 解析一遍。你只需要记住三套符号，就能读懂 90% 的模板：

官方对 Liquid 的定位非常明确："Jekyll uses the Liquid templating language to process templates"，详细文档可以直接看仓库里的 liquid.md。

2️⃣ 必备语法：变量、判断与循环

输出变量：{{ }}双花括号

Jekyll 会向你提供一批"全局变量"，最常用的是site和page：

你好，我是 {{ site.title }}，这是 {{ page.title }} 页面。

嵌套取值用点号即可，比如{{ site.data.authors[0].name }}。变量查不到时不会报错，只会输出为空——这让模板写起来非常"宽容"。

条件判断：{% if %}

{% if post.draft %} <span>草稿</span> {% elsif post.tags.size > 5 %} <span>标签超多</span> {% else %} <span>正常文章</span> {% endif %}

支持and、or、==、!=、>,<等常见比较运算符，是搭建"有文章就显示列表、没文章就显示空状态"这类页面的核心。

循环：{% for %}与{% assign %}

渲染一篇博客的文章列表，本质上就是一个 for 循环：

{% assign posts = site.posts | first: 3 %} {% for post in posts %} <li> <a href="{{ post.url }}">{{ post.title }}（{{ post.date | date: "%Y-%m-%d" }}）</a> </li> {% endfor %}

几个细节值得注意：

• forloop对象自带索引：{{ forloop.index }}（从 1 开始）、{{ forloop.rindex }}（倒数索引）、{{ forloop.first }}/{{ forloop.last }}
• {% assign %}可以创建局部变量，{% capture %}还能把一段渲染结果存起来
• 内置的first、last过滤器可以直接截取数组，配合循环非常顺手

💡 小提示：如果你在模板里要原样展示 Liquid 代码（比如写文档），用{% raw %} ... {% endraw %}包起来，Jekyll 就不会解析中间的内容。

3️⃣ 内置 Filters 详解：Jekyll 扩展的"瑞士军刀"

Liquid 本身自带 50 多个标准过滤器（date、truncate、sort、strip_html等，见 filters.md 中的完整清单），而 Jekyll 又扩展了一批"博客友好型"过滤器，源码集中在 lib/jekyll/filters.rb，并按职责拆分到 URL、日期、分组等子模块。

排版输出类

数据处理类

• where/find：按属性筛选文章集合。例如{% assign js_posts = site.posts | where: "category", "javascript" %}，还能用nil找出没写某个属性的文章
• where_exp/find_exp：更灵活的表达式版本，支持item.title contains "Jekyll"这类条件
• group_by：按字段把数组分组，做"按年份归档"、"按作者分类"必备
• array_to_sentence_string：把数组变成"苹果、香蕉和橘子"这样的自然句子

URL 与安全类

日期格式化：date过滤器

博客离不开日期，date过滤器使用strftime格式串：

发布：{{ post.date | date: "%Y年%m月%d日" }}

Jekyll 还内置了date_to_string、date_to_long_string等封装，以及针对 Windows 时区的兼容处理（win_tz.rb），保证日期显示不"穿越"。

4️⃣ 5 个内置 Tags：开箱即用

Jekyll 除了标准 Liquid 标签，还注册了 5 个内置 Tag（实现位于 lib/jekyll/tags/ 目录），官方文档见 tags.md：

①{% include %}—— 页面片段复用

把导航栏、页脚等重复片段放进_includes/目录，任何页面一行引入：

{% include nav.html %} {% include footer.html copyright="2026 My Site" %}

参数通过include变量传入片段内部使用，还支持动态文件名（用{{ }}变量拼接文件名），实现"根据语言自动引入对应片段"这类技巧。源码见 include.rb。

②{% include_relative %}—— 相对路径引入

与include不同，它从当前页面所在目录查找片段文件，写教程、文档站时特别好用。

③{% highlight %}—— 代码高亮

基于 Rouge 引擎，支持 100+ 语言语法高亮：

{% highlight ruby linenos %} def hello puts "Hello, Jekyll!" end {% endhighlight %}

linenos显示行号；Jekyll 4.4 起还支持mark_lines="1 2"高亮指定行。源码见 highlight.rb。

④{% post_url %}—— 根据文件名取文章链接

<a href="{% post_url 2008-11-21-complex %}">看这篇老文章</a>

只要文章还在_posts/里，链接就永远不会写错——文章改名、改日期都不用改链接。源码见 post_url.rb。

⑤{% link %}—— 通用静态文件链接

为_layouts之外的任意文件（含静态文件）生成相对 URL，行为与relative_url过滤器一致，适合引用 CSS、PDF 等资源。源码见 link.rb。

5️⃣ 自定义 Tag：十几行 Ruby 扩展你的模板

Liquid 的开放性在于：任何 Ruby 文件都能注册一个新 Tag。在_plugins/目录（本地开发时）新建文件，继承Liquid::Tag即可：

module Jekyll module Tags class Hello < Liquid::Tag def render(context) "Hello, " + context.registers[:site].config["author"] end end end end Liquid::Template.register_tag("hello", Jekyll::Tags::Hello)

之后在任何模板里就能直接写{% hello %}。内置的include、post_url等 Tag 正是用完全相同的方式注册的（例如 include.rb 结尾的register_tag调用），你可以照着它们学写法。

⚠️ 注意：出于安全考虑，生产托管环境（如 GitHub Pages）不允许加载_plugins/自定义代码，自定义 Tag 适合自托管站点。

6️⃣ 上手建议与常见坑

1. 先变量、后逻辑：能用{{ }}+ 过滤器解决的，别急着写{% if %}，模板更干净
2. 循环里注意性能：for循环内避免嵌套循环和重复过滤器调用，大列表建议先用limit截断
3. 变量不存在≠报错：Liquid 找不到变量时静默输出空，排查"为什么没显示"时先从这一点入手
4. 写文档展示代码：用{% raw %}包裹；Jekyll 4 起也可在 front matter 里设置render_with_liquid: false彻底关闭某页的 Liquid
5. 链接一律走过滤器：relative_url能帮你规避baseurl带来的路径问题

想深入细节，推荐按顺序阅读：liquid.md（总览）→ filters.md（过滤器全表）→ tags.md（标签详解），对照源码 lib/jekyll/filters.rb 与 lib/jekyll/tags/ 阅读，动手改改测试项目 test/source/ 里的页面跑一遍，Liquid 模板语言就真正属于你的了。

【免费下载链接】jekyll:globe_with_meridians: Jekyll is a blog-aware static site generator in Ruby项目地址: https://gitcode.com/gh_mirrors/je/jekyll