企业官网建设流程全解析

Jekyll Front Matter详解：10个实用示例掌握YAML元数据控制文章与页面

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

Jekyll Front Matter（前置元数据）是 Jekyll 静态博客最核心的控制机制：只需在 Markdown 或 HTML 文件开头写一段 YAML 格式的元数据，就能控制文章的标题、日期、分类、标签、布局、URL 乃至是否发布。本文面向新手，通过 10 个实用示例带你快速掌握 Jekyll YAML 元数据的完整用法，让你对文章与页面的每一个细节尽在掌控。

什么是 Jekyll Front Matter？

任何文件，只要以三个破折号---开头并包裹一段合法的 YAML 文本，Jekyll 就会将它识别为 Front Matter，并对该文件进行特殊处理：

--- layout: post title: 我的第一篇文章 --- 正文内容从这里开始……

关键规则：

• 🔹 Front Matter必须位于文件最开头，且必须是---起始（Jekyll 源码中的 has_yaml_header? 方法 正是靠检查文件首行是否为---来判断）
• 🔹 两行---之间可以是预定义变量，也可以是你自创的自定义变量
• 🔹 即使中间留空，只要存在空白的---块，文件也会被 Jekyll 处理
• ⚠️ 使用 UTF-8 编码时，确保文件没有 BOM 头，否则会导致意外问题

官方说明可参考 Front Matter 文档。

10个实用示例：从入门到精通

示例1：用 layout 指定页面布局

layout指定该文件使用_layouts目录下的哪个模板文件（写文件名、不带扩展名）。这是使用频率最高的变量：

--- layout: default title: 关于我 ---

Jekyll 会将页面内容注入到布局的{{ content }}占位符中，多个布局还能层层嵌套，原理如下图所示（内容从 document 逐层注入到最外层布局）：

小技巧：写作layout: nil（或~）可让文章不使用任何布局，这在生成 RSS、JSON 等纯数据页面时非常有用。

示例2：用 permalink 自定义文章 URL

默认情况下文章地址为/年/月/日/标题.html。想改成固定路径？用permalink：

--- permalink: /my-first-post/ ---

设置后，这篇文章最终会被输出到你指定的 URL，适合做"置顶文章"或重要落地页。

示例3：用 published 控制文章是否发布

--- title: 草稿文章 published: false ---

设为false后，该文章不会出现在生成结果中，但本地执行jekyll build --unpublished时仍能看到它，非常适合"写完先藏着"的场景。

示例4：用 date 覆盖文章日期

文章的默认日期取自文件名（如2010-01-09-hello.markdown）。如果日期写错了，不用改文件名，直接在 Front Matter 里覆盖即可：

--- date: 2010-01-10 08:30:00 +0800 ---

日期格式为YYYY-MM-DD HH:MM:SS +/-TTTT，时、分、秒、时区偏移均可省略。测试仓库中就有一个真实例子：2010-01-09-date-override.markdown。

示例5：用 categories 指定文章分类

不依赖文件夹结构，直接声明分类：

--- categories: - 技术 - Ruby ---

支持 YAML 列表，也支持空格分隔的字符串写法。测试用例 2009-01-27-array-categories.markdown 展示了这种数组写法。

示例6：用 tags 为文章打标签

与分类类似，标签更轻量、更灵活，一篇文章可挂多个：

--- tags: - 前端 - Jekyll - 教程 ---

配合标签页、归档页可以做出非常丰富的博客导航。

示例7：用 excerpt 自定义摘要

列表页默认截取文章第一段作为摘要。想自定义？在 Front Matter 里直接写：

--- excerpt: '这里显示我亲手写好的摘要文字' ---

参考示例 2013-04-11-custom-excerpt.markdown。

示例8：创建自定义变量

除了预定义变量，Front Matter 里的一切内容都是合法 YAML——你可以自由发明变量：

--- author: 小杰 difficulty: 入门 food: Pizza ---

之后在页面、布局、includes 中都能用 Liquid 访问：{{ page.author }}、{{ page.food }}。这是实现"多作者博客""系列文章标记"等功能的基石。

示例9：用 Front Matter Defaults 批量设默认值

如果每篇文章都要写layout: post，太啰嗦了。Jekyll 允许在_config.yml中用defaults键按作用域批量设置默认元数据：

defaults: - scope: path: "" type: "posts" values: layout: "post" author: "小杰"

单篇文章仍可在自己的 Front Matter 中覆盖这些默认值。完整规则请见 Front Matter Defaults 文档。

示例10：空 Front Matter 也有用

有时候你只是想"激活" Liquid 语法，却不需要任何变量：

--- ---

这样 Jekyll 同样会处理该文件（常用于 CSS、RSS 等文件），相当于一个"开关"。

常见问题与避坑指南

💡一句话总结：预定义变量管全局（layout/permalink/published/date/categories/tags/excerpt），自定义变量管个性，defaults管效率——三者配合，Jekyll Front Matter 就能撑起整个站点的"元数据中枢"。

延伸阅读

• 📖 Front Matter 官方文档
• 📖 Front Matter Defaults 配置文档
• 🧪 测试用例：Front Matter 日期覆盖
• 🧪 测试用例：YAML 数组分类

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