hexo 学习►写作

hexo 学习 0019:hexo front matter

Front-matter 是你文章文件的“身份证”和“说明书”。它位于文件的最开头，是一段 YAML 或 JSON 格式的代码块，专门用来告诉 Hexo 如何处理这篇文章。如果没有它，Hexo 就不知道文章的标题是什么、该归到哪一类，甚至不知道何时发布。

语法格式：YAML 与 JSON

Front-matter 支持两种写法，就像你可以用中文或英文写说明书一样，但必须二选一，不能混用。

1. YAML 格式（推荐）
这是最常用的格式，以三个破折号 --- 开始，也以三个破折号 --- 结束。

1
2
3
4
5
6
7
---
title: Hello World
date: 2013/7/13 20:46:25
tags:
  - Hexo
  - Blog
---

2. JSON 格式
如果你更习惯 JSON 语法，可以使用三个分号 ;;; 作为结束标记（开始标记通常也是三个分号或直接以 JSON 对象开始，但在 Hexo 中通常指以 ;;; 结尾的块）。

1
2
3
"title": "Hello World",
"date": "2013/7/13 20:46:25"
;;;

核心配置项详解

在 Front-matter 中，你可以设置多种参数来控制文章的行为。以下是关键配置项及其作用：

设置项 描述 默认值
layout 指定文章使用的布局模板。如果设为 false，则不使用主题布局，但仍会被渲染引擎处理。 读取 _config.yml 中的 default_layout (通常为 post)
title 文章的标题。 默认为文件名
date 文章的创建日期。 文件建立日期
updated 文章的更新日期。 文件更新日期
comments 是否开启评论功能。设为 false 可关闭特定文章的评论。 true
tags 文章的标签列表。 无
categories 文章的分类列表。 无
permalink 自定义永久链接。必须以 / 或 .html 结尾。 null (自动生成)
excerpt 纯文本摘要。常用于首页显示，可使用插件格式化。 自动截取
disableNunjucks 设为 true 时，禁用 Nunjucks 标签 ({{ }}, {% %}) 的渲染，防止代码冲突。 false
lang 设置文章语言，覆盖全局自动检测。 继承自 _config.yml
published 标记文章是否发布。_posts 下默认为 true，_drafts 下默认为 false。 依目录而定

配置示例：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
---
title: 我的旅行日记
date: 2026-03-09 10:00:00
updated: 2026-03-09 12:30:00
tags:
  - 旅行
  - 摄影
categories:
  - 生活
  - 游记
permalink: travel/2026/my-trip.html
comments: true
disableNunjucks: false
---

概念辨析：分类 (Categories) 与 标签 (Tags)

这是新手最容易混淆的两个概念。我们可以用图书馆来打比方：

  • 分类 (Categories) 就像是图书馆的书架分区。它是层级化的、有秩序的。一本书（文章）通常放在一个主要的区域，比如“历史类”下的“中国史”。在 Hexo 中，分类可以形成父子层级结构，像目录一样严谨。
  • 标签 (Tags) 就像是书背上的便利贴。它是扁平的、无序的。一本书上可以贴很多便利贴，比如“唐朝”、“玄武门之变”、“人物传记”。标签用于捕捉不同分类文章之间的共同点，是跨维度的索引。

形象比喻：
如果把博客比作一个人，分类是骨骼，支撑起整体结构（如：技术、生活、随笔）；标签是肌肉和神经，连接各个部分，体现细节特征（如：Java、周末、心情）。分类和标签这两个维度配合，基本就能满足绝大多数博客的检索需求。

分类的高级用法：层级与并列

Hexo 的分类系统非常灵活，支持层级结构和并列结构。

1. 层级分类（父子关系）
当你按顺序列出分类时，Hexo 会将其视为层级关系。

1
2
3
categories:
  - Sports      # 父分类
  - Baseball    # 子分类

这表示文章属于 “Sports” 下的 “Baseball”。

2. 多层级复杂结构
你可以定义更深或更复杂的层级，使用列表的列表：

1
2
3
categories:
  - [MLB, American League, Boston Red Sox]
  - [MLB, American League, New York Yankees]

这里定义了两个独立的路径，文章同时属于这两个深层分类。

3. 并列分类（同级关系）
如果你想让文章同时属于几个互不从属的顶级分类（即“并列”），需要使用中括号将每个分类单独包裹，或者将多个单元素列表放在一起。

1
2
3
categories:
  - [Sports, Baseball]       # 路径 1: Sports -> Baseball
  - [Rivalries]              # 路径 2: Rivalries (顶级)

布局 (Layout) 的特殊行为

layout 参数控制文章使用哪个模板文件进行渲染。

  • 默认行为：遵循 _config.yml 中的 default_layout 设置（通常是 post）。
  • 禁用布局：如果你设置 layout: false，Hexo 将不会使用任何主题模板（即不会包裹 header、footer 等），文章内容将被直接渲染输出。
    • 注意：即使禁用了布局，渲染引擎（如 Markdown 转 HTML）依然会工作。只要安装了 hexo-renderer-marked，.md 文件依然会被转换成 HTML，只是没有主题的外壳。
  • 标签插件处理：除非你设置了 disableNunjucks: true 或者渲染引擎本身不支持，否则无论 layout 如何设置，Hexo 的标签插件（如 {% include %}）都会被正常处理。

总结与建议

  1. 必填项：虽然 Hexo 能自动推断标题和日期，但为了稳定，建议每篇文章都明确写上 title 和 date。
  2. 分类策略：保持分类的简洁和层级清晰，不要为了分类而分类。记住“主分类”的概念，避免结构过于混乱。
  3. 标签运用：标签可以自由发散，但不要过多，3-5 个精准的描述性标签最佳。
  4. 特殊场景：如果你需要生成一篇纯 HTML 片段用于嵌入其他页面，记得使用 layout: false。

通过熟练掌握 Front-matter，你就能完全掌控 Hexo 对每一篇文章的处理逻辑，让你的博客结构井井有条。