Jekyll 内置 Liquid 标签完全指南include、highlight 语法高亮与 link/post_url 链接标签【免费下载链接】jekyll:globe_with_meridians: Jekyll is a blog-aware static site generator in Ruby项目地址: https://gitcode.com/gh_mirrors/je/jekyll本篇技术指南围绕 Jekyll 的 Liquid 标签文档 展开系统讲解 Jekyll 在标准 Liquid 之上提供的全部内置标签用于代码片段高亮的highlight、用于生成正确永久链接permalink的link与post_url以及页面片段复用工具include。读完本文你将掌握每个标签的完整语法、可选参数、版本要求与底层实现原理并能直接在真实站点中写出可复制、可运行的模板代码。概览Jekyll 支持的标签体系Jekyll 基于 Ruby 实现完整支持标准 Liquid 模板引擎的全部控制流与标签语法 目录可以看到这些标签的源码实现标签说明源码文件include/include_relative嵌入_includes目录或其他相对位置的片段文件include.rbhighlight使用 Rouge 对代码块进行语法高亮highlight.rblink根据文件路径生成正确的永久链接并做链接校验link.rbpost_url根据文章名生成文章永久链接post_url.rb除此之外你还可以通过编写插件注册自定义标签扩展 Jekyll 的模板能力。Includes复用页面片段如果某个页面片段页脚、导航、分享按钮等在站点中反复出现include 文档 推荐使用include标签将其抽取到_includes目录中统一维护{% include footer.html %}Jekyll 会在源码根目录的_includes目录中查找该文件并插入其渲染结果。include还支持以变量方式指定文件名、向片段传递参数以及通过include_relative标签引入相对当前文件位置的片段。从 include.rb 的render实现可以看到include 的完整渲染流程是先解析文件路径支持{{ variable }}变量语法→ 校验文件名合法性 → 在includes_load_paths中定位文件 → 将解析后的参数写入context[include]→ 渲染片段并返回。值得注意的是OptimizedIncludeTag 对 include 做了性能优化每个文件只解析一次并缓存在site.inclusions中后续重复引用直接复用解析结果这在循环中反复 include 同一文件时能显著减少解析开销。代码片段语法高亮基于 Rouge 的内置高亮Jekyll 内置了超过 100 种语言的语法高亮支持这得益于 Rouge——一个用 Ruby 编写的语法高亮引擎也是 Jekyll 3 及以后版本的默认高亮器。在 configuration.rb 中highlighter配置项的默认值即为rouge。注意Pygments 已废弃Pygments 在 Jekyll 4 中已不再支持。即使配置highlighter: pygments也会自动回退使用 Rouge。Rouge 由 Ruby 编写且与 Pygments 的样式表 100% 兼容因此你可以直接沿用现有的 Pygments CSS 主题。要渲染一个带语法高亮的代码块只需用highlight标签包裹代码{% highlight ruby %} def foo puts foo end {% endhighlight %}highlight后面的第一个参数是语言标识符上例中的ruby。要确定所用语言的标识符可查阅 Rouge 支持的语言与 lexer 列表中的 “short name”。语言名不区分大小写测试 test_tag_highlight.rb 验证了Ruby与ruby等价并支持c#、xmlcheetah、x.y、coffee-script等特殊字符组合其合法性由 highlight.rb 中的SYNTAX正则约束。从源码实现看render_rouge 的执行链路是根据语言名通过Rouge::Lexer.find_fancy查找 lexer若找不到则回退为Rouge::Lexers::PlainText纯文本随后用Rouge::Formatters::HTML格式化输出最终代码块被包裹为figure classhighlightprecode ...结构见 add_code_tag。代码块内的 Liquid 处理与 raw/endrawJekyll 会处理代码块中的所有 Liquid 语法。如果你要展示的语言本身包含花括号如 Go、Rust 等模板类语言或要展示 Liquid 代码本身通常需要用raw和endraw标签将代码包围阻止 Liquid 引擎解析其中的{{ }}与{% %}{% raw %} {% highlight liquid %} {{ page.title }} {% endhighlight %} {% endraw %}自 Jekyll 4.0 起还有一个更彻底的办法在文档的 front matter 中设置render_with_liquid: false即可完全关闭该文档的 Liquid 渲染。该逻辑在 convertible.rb 的render_with_liquid?方法中实现renderer.rb 会据此决定是否执行 Liquid 渲染流程同样document.rb、excerpt.rb 等模块也都实现了该方法因此该开关对页面、文档、摘录均生效。显示行号linenos 参数highlight标签的第二个可选参数是linenos加入后会在代码块每行前渲染行号{% highlight ruby linenos %} def foo puts foo end {% endhighlight %}从 highlight.rb 的parse_options实现可见linenos裸写时会被规范化为inline值此时使用 Rouge 的HTMLTable格式化器table_formatter生成带有gutter与code两列的行号表格测试 test_tag_highlight.rb 验证了其输出包含table classrouge-table与td classgutter gl结构。此外linenos也支持显式赋值如linenostable。标记特定行mark_lines 参数自 Jekyll 4.4.0 起highlight标签支持mark_lines参数用于标记代码片段中的特定行。该参数接受一个必须用双引号包裹、以空格分隔的行号列表{% highlight ruby mark_lines1 2 %} def foo puts foo end {% endhighlight %}上例将标记第 1 行和第 2 行而第 3 行不会被标记。被标记的行默认应用 CSS 类名hll。源码层面line_highlighter_formatter 会为格式化器包一层Rouge::Formatters::HTMLLineHighlighter并将mark_lines解析为整数数组传给:highlight_lines如果mark_lines不是双引号包裹的整数列表mark_lines 会直接抛出SyntaxError提示正确的书写格式。高亮样式表要让高亮真正显示出来你需要引入一份语法高亮样式表。由于 Rouge 与 Pygments 样式兼容可以直接使用 Pygments 主题 CSS例如native.css。将 CSS 文件复制到你的 css 目录后在main.css中导入即可import native.css;主题样式负责渲染各语言的 token 颜色以及hll类所对应的标记行背景色。链接标签link 与 post_url自 Jekyll 4.0 起link和post_url标签都不再需要手动前置site.baseurl。这一行为在 url_filters.rb 的relative_url实现中得到印证它会在渲染时自动读取site.baseurlsanitized_baseurl见 url_filters.rb并拼接到输出 URL 前。使用 link 标签链接到页面、文章、集合项或文件link标签会为指定路径生成正确的永久链接 URL。例如链接到mypage.html时即使你之后修改了 permalink 样式带扩展名或不带扩展名link标签生成的 URL 始终有效。使用link标签时必须包含文件原始扩展名。以下是一些示例{% link _collection/name-of-document.md %} {% link _posts/2016-07-26-name-of-post.md %} {% link news/index.html %} {% link /assets/files/doc.pdf %}也可以在 Markdown 链接中使用Link to a document Link to a post Link to a page Link to a file路径规则link标签中的路径定义为相对于站点根目录即配置文件所在目录的路径而不是从当前页面到目标页面的相对路径。例如page_a.md存放在pages/folder1/folder2中要链接到存放在pages/folder1中的page_b.md路径应写为/pages/folder1/page_b.md而不是../page_b.html。如果你不确定文件的相对路径可以在页面中临时输出{{ page.path }}来查看当前页面的路径。从 link.rb 的render实现可以看到底层逻辑标签会先对路径执行 Liquid 渲染因此支持变量路径随后遍历site.each_site_file中的全部文件将传入路径与每个item.relative_path比对同时兼容带与不带前导/的写法命中后返回relative_url(item)若找不到匹配文件则抛出ArgumentError并终止构建。这正是link标签做链接验证的方式——详见下文。链接验证让坏链接在构建期暴露link与post_url标签的一个核心价值是链接校验如果目标链接不存在Jekyll 将直接构建失败而不是生成一个无效链接后让你带着坏链接上线。测试 test_tag_link.rb 明确验证了当link指向不存在的集合项时会抛出ArgumentErrortest_tag_post_url.rb 也验证了无效文章名会抛出Jekyll::Errors::PostURLError非法日期则抛出InvalidDateError。link 标签的注意事项不能对link标签追加过滤器。例如{% link mypage.html | append: #section1 %}是无效的因为过滤器会被误认为路径的一部分。要链接到页面内的锚点section请改用普通的 HTML 或 Markdown 链接方式。文件名可以是变量。在 front matter 中定义变量后即可引用--- title: My page my_variable: footer_company_a.html ---{% link {{ page.my_variable }} %}此例中link标签会渲染为指向footer_company_a.html的链接。测试 test_tag_link.rb 验证了动态路径{% link {{ contacts_filename }}.{{ contacts_ext }} %}与静态路径均能正确解析。使用 post_url 标签链接到文章post_url标签会为指定文章生成正确的永久链接 URL{% post_url 2010-07-21-name-of-post %}如果你的文章组织在子目录中需要包含子目录路径{% post_url /subdir/2010-07-21-name-of-post %}使用post_url时无需包含文件扩展名只需文章名日期 slug。同样可以嵌入 Markdown 链接Name of Link从 post_url.rb 的实现看post_url的匹配逻辑经历了两次遍历首先用PostComparer的POST_PATH_MATCHER正则post_url.rb解析出路径、日期、slug并与site.posts.docs中的每篇文章按名称path-date-slug精确比对若第一次未命中则回退到旧的按日期slug 匹配方法命中时会打印弃用警告提示开发者改用精确名称测试 test_tag_post_url.rb 专门覆盖了这一弃用路径。同时PostComparer 会校验日期合法性非法日期如月份 42会抛出InvalidDateError。结合数据文件批量生成文章链接假设你用数据文件_data/cool_posts.yaml维护一组“精选文章”详见 datafiles 文档- title: An Awesome Post slug: 2010-07-21-name-of-post - title: Another Awesome Post slug: 2016-07-26-name-of-post自 Jekyll 4.5.0 起你可以在循环中把数据文件的字段直接传给post_url标签批量生成文章链接列表Cool posts: {%- for cool_post in site.data.cool_posts %} - {{ cool_post.title }} {%- endfor %}这一用法在 post_url.rb 中由template Liquid::Template.parse(markup)支撑当标签参数中包含{{时标签会先把参数当作 Liquid 模板渲染再对解析后的文章名执行匹配从而让数据文件驱动的动态文章名成为可能。小结Jekyll 的内置标签在标准 Liquid 之上补齐了静态站点生成最关键的三个场景include解决片段复用与性能缓存highlight提供基于 Rouge 的 100 语言高亮含linenos行号与mark_lines行标记link/post_url则提供与 permalink 样式解耦、且自带构建期链接校验的安全链接方案。它们的完整语法、可选参数与错误信息分别定义在 lib/jekyll/tags 目录的四个源码文件中并有 test_tag_highlight.rb、test_tag_link.rb、test_tag_post_url.rb 三份测试用例逐一验证可作为你排查模板问题与理解底层行为的第一手参考资料。【免费下载链接】jekyll:globe_with_meridians: Jekyll is a blog-aware static site generator in Ruby项目地址: https://gitcode.com/gh_mirrors/je/jekyll创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考