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/jekyllJekyll 是一款用 Ruby 编写的博客感知型静态站点生成器它的灵魂就是 Liquid 模板语言——你在 Jekyll 中写下的每一段页面逻辑几乎都靠 Liquid 的变量、过滤器和标签来完成。这篇指南带你一次吃透 Liquid 模板语法从最基础的双花括号变量到 Jekyll 独家扩展的内置 Filters再到 include、highlight 等 5 个实用内置 Tags最后还教你如何用十几行 Ruby 代码写出属于自己的自定义 Tag。1️⃣ Liquid 是什么三套符号撑起模板Jekyll 在处理 Markdown、HTML 文件时会先用 Liquid 解析一遍。你只需要记住三套符号就能读懂 90% 的模板符号名称作用例子{{ }}变量输出一段数据{{ page.title }}{% %}标签执行逻辑判断、循环{% if post %}|过滤器Filter修饰变量的输出{{ post.date \| date: %Y }}官方对 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、日期、分组等子模块。排版输出类过滤器作用示例markdownify把 Markdown 字符串转成 HTML{{ post.excerpt \| markdownify }}truncatewords按字数截断自动加省略号{{ content \| truncatewords: 30 }}strip_html去掉所有 HTML 标签{{ post.content \| strip_html }}number_of_words统计字数支持中文计数{{ content \| number_of_words }}smartify把直引号变成排版级弯引号{{ content \| smartify }}数据处理类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 与安全类过滤器作用示例relative_url根据baseurl生成相对链接换部署路径不踩坑href{{ /about/ \| relative_url }}slugify生成 URL 友好的短文本支持pretty、latin等模式{{ 你好 World \| slugify }}xml_escape/uri_escape转义 HTML 特殊字符 / URI 组件{{ user_input \| xml_escape }}日期格式化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 copyright2026 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_lines1 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️⃣ 上手建议与常见坑先变量、后逻辑能用{{ }} 过滤器解决的别急着写{% if %}模板更干净循环里注意性能for循环内避免嵌套循环和重复过滤器调用大列表建议先用limit截断变量不存在≠报错Liquid 找不到变量时静默输出空排查为什么没显示时先从这一点入手写文档展示代码用{% raw %}包裹Jekyll 4 起也可在 front matter 里设置render_with_liquid: false彻底关闭某页的 Liquid链接一律走过滤器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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考