什么是Front-matter

前言

此处所说到的Front-matter其实是指Markdown中的Front matter，它是一种通过三个横杠（—）包围的标签组，会出现在文章在最开头，里面可以记录文章相关的一些信息，例如标题、创建时间、更新时间、作者、标签、分类、封面等等等等。本文主要是记录我个人常用的一些标签，以及对应的格式

它到底是个什么东西

简单说：Front-matter 是写在 Markdown 文件最顶部的一小段 YAML 配置，用 --- 包起来，用来告诉渲染器”这篇文章叫什么、什么时候写的、归到哪一类”。

它不会影响正文内容，渲染的时候会被单独解析掉。你现在看到的这篇文章，开头就是这么一段：

1
2
3
4
5
6
7
8
---
title: 什么是Front-matter
date: 2024-10-06 22:20:00
categories:
  - Hexo教程
tags: [Front-matter, Markdown, Hexo, YAML]
permalink: /what-is-front-matter/
---

有几个硬性规则：

  1. 必须放在文件第一行，前面连空行都不能有，否则会被当成正文渲染出来
  2. 开头和结尾各一行 ---，不能多也不能少
  3. 语法是 YAML，不是 JSON，也不是随便写

YAML 基本写法

最常用的就三种结构，够用了：

键值——注意冒号后面必须有一个空格：

1
title: 我的文章标题

列表——两种写法等价，都行：

1
2
3
4
5
6
7
# 写法一：换行 + 短横线
tags:
  - Hexo
  - Markdown

# 写法二：行内数组
tags: [Hexo, Markdown]

嵌套——用缩进表示层级，只能用空格，不能用 Tab：

1
2
3
author:
  name: Harrison
  email: xxx@example.com

几个容易翻车的点：

  • 中文冒号不行。title：xxx 这种全角冒号 YAML 不认，必须半角 :
  • 值里有冒号要加引号。title: "6:00 起床" 不加引号会解析失败
  • 值里有特殊字符也建议加引号，比如 [、{、#、*、&
  • true / false / 数字会被识别成布尔和整数，想当字符串用就得加引号

通用常用字段

这些不挑平台，Typora、Obsidian、Hugo、Jekyll 都认：

字段 作用 示例
title 文章标题 title: 什么是Front-matter
date 创建时间 date: 2024-10-06 22:20:00
updated 最后更新时间 updated: 2026-09-23 14:50:00
tags 标签，一篇文章可以多个 tags: [Hexo, YAML]
categories 分类 categories:\n - Hexo教程
description 摘要，给搜索引擎看 description: 一句话说清这篇讲啥
keywords 关键词 keywords: [Front-matter, Markdown]
author 作者 author: Harrison
cover / index_img 封面图 cover: /img/default.png
draft 草稿，true 则不发布 draft: false
comments 这篇文章要不要开评论 comments: false
toc 要不要显示目录 toc: true

Hexo 里要注意的地方

这些是 Hexo 特有的，别的平台不一定通用：

1. date 基本等于必填

没有 date 的话，Hexo 会拿文件的创建时间来兜底，但换台机器、重新 clone 一次，排序就全乱了。老老实实写上。

2. 平铺的 categories 是层级关系，不是并列

这点我踩过。这样写两个分类：

1
2
3
categories:
  - 技术教程
  - Node.js

Hexo 会理解成**「技术教程」下的「Node.js」子分类**，生成的路径只有 /categories/技术教程/Node.js/，而不存在独立的 /categories/Node.js/。也就是说 Node.js 这个分类本身是点不进去的。

想要并列的多个分类，得写成嵌套数组——每个分类单独用一个方括号包起来：

1
2
3
categories:
  - [技术教程]
  - [Node.js]

这样两个都是顶层分类，各自生成 /categories/技术教程/ 和 /categories/Node.js/，文章同时挂在两边。（这个写法我实测过，确认有效。）

想表达真正的父子层级时，反过来把两级写进同一个方括号即可：

1
2
categories:
  - [技术教程, Node.js]

3. permalink 结尾带不带 / 都行，但要统一

我早期的文章是 permalink: wallhaven-web-crawler-guide（不带斜杠），后来统一成了 /wallhaven-web-crawler-guide/（带斜杠）。两种都能用，但别混着来，改来改去会让已发布的链接失效，SEO 也跟着掉。

4. layout 决定用哪个模板

默认是 post。写独立页面（比如「关于」）的时候要写 layout: page。

5. 加密文章用 password

装了 hexo-encrypt 之后，加一行就能给文章上锁：

1
password: private-2025

fluid 主题额外支持的字段

本站用的是 fluid 主题，它在标准字段之外还认这些，写在 Front-matter 里能单独控制某一篇：

字段 作用
index_img 文章列表页显示的缩略图
banner_img 文章顶部的头图，不写就用主题默认那张
subtitle 副标题，显示在标题下面
excerpt 手动指定摘要，不写就自动截取正文开头
keywords 单独给这篇文章设 keywords，覆盖站点默认值
sticky 数值越大越靠前，用来置顶
math 这篇文章要不要开数学公式渲染
toc 单独关掉这篇的目录
author 覆盖全局作者名

举个例子，想让一篇文章置顶并配个头图：

1
2
3
4
5
6
7
8
9
10
---
title: 一篇很重要的文章
date: 2026-09-23 10:00:00
categories:
  - 随笔
tags: [置顶]
sticky: 100
banner_img: /img/default.png
index_img: /img/default.png
---

我在用的模板

最后贴一份我自己的惯用模板，新文章直接复制改改就行：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
---
title: 文章标题
date: yyyy-mm-dd HH:MM:SS
categories:
  - 分类
tags: [标签1, 标签2, 标签3]
permalink: /english-slug/
description: 一句话摘要，会显示在列表页和搜索结果里
---

引言，一到两句话说清楚这篇要讲啥

<!--more-->

正文从这里开始

<!--more--> 是 Hexo 的截断标记，放在引言后面，列表页就只会显示它之前的内容，不会把整篇都铺出来。

顺带一提：Obsidian 用户

如果你是拿 Obsidian 写博客的，Obsidian 的「属性」功能本质上就是同一套 YAML，两者完全兼容。在 Obsidian 里点「添加属性」填的字段，Hexo 照样认。反过来，Front-matter 里写的字段在 Obsidian 里也会显示成属性卡片。

唯一要注意的是 Obsidian 喜欢把日期写成 2024-10-06 不带时间，而 Hexo 排序需要精确到秒，手动补一下 22:20:00 就好。

参考

Hexo教程
#Front-matter #Markdown #Hexo #YAML
什么是Front-matter
https://blog.qfmy.vip/what-is-front-matter/
作者
Harrison
发布于
2024年10月6日
许可协议