Skill · Front-matter 字段速查
何时用：忘了某个字段叫啥、或者想知道某个开关有什么效果时翻一下。
解决什么：把 gobog 认识的 front-matter 字段按"必填 / 常用 / 高级"三档列全。
front-matter 用 YAML，写在 --- ... --- 之间。所有字段都可选——gobog 第一次扫到一篇没有 id / url / title / create_time 的文章时会自动补齐并写回原文件。
一份典型完整的 front-matter
---
title: 我的博客演进历程
author: sbraveyoung
create_time: 2026-05-09 12:00:00
updated_time: 2026-05-09 14:30:00
id: blog-evolve-2
url: /post/blog-evolve-2
description: 一段关于 markdown 博客发布链路的折腾笔记
tags: [博客, gobog, github-actions]
cover: hero.png
ai: true
order: 1
draft: false
hidden: false
private: false
pin: false
---
必填（gobog 没有也会自动填）
| 字段 | 类型 / 例子 | 说明 |
|---|---|---|
title |
我的博客演进历程 |
文章标题，渲染在 <h2> 和 <title> 里。 |
id |
blog-evolve-2 |
短稳定 id。无值时 = 文件 basename slug 化。 |
url |
/post/blog-evolve-2 |
永久 URL。一旦写过 gobog 不会改。post 用 /post/<id>，page 用 /<basename>。 |
create_time |
2026-05-09 12:00:00 |
首次创建时间。用作首页排序键。 |
常用
| 字段 | 默认 | 说明 |
|---|---|---|
author |
无 | 作者名，渲染在 atom feed 和元信息里。 |
updated_time |
无 | 最后更新时间。Obsidian 插件保存时不会自动改它，需要的话手动写。 |
description |
无 | 用于 <meta name="description"> 和列表页摘要。空 = 自动从正文摘 160 字。 |
tags |
无 | 数组（[a, b]）或逗号分隔（a, b）都接受。# 前缀会被自动去掉。 |
cover |
无 | 顶部头图 + og:image。裸文件名 → /image/<name>；URL 直通。 |
ai |
无 | AI 标识。详见 skill · ai-attribution。 |
排序 / 可见性开关
| 字段 | 默认 | 效果 |
|---|---|---|
pin |
false |
真值时置顶。同分组内 pinned 永远在 date 排序之上。 |
order |
无 | 整数。配合数字前缀文件名 / 共同决定该 group 是否启用 series 升序排序。 |
draft |
false |
真值时不进发布列表。除非 [blog].include_drafts = true。 |
hidden |
false |
跟 draft 一样，但语义是"暂时下线"。 |
private |
false |
列表里出现，正文要 HTTP Basic auth。静态导出直接跳过。 |
系列排序如何触发
满足以下条件，gobog 会把这个 group 当成"系列"（升序读）：
- group 的所有叶子
.md都满足：- front-matter 里有
order: <数字>，或者 - 文件名以数字开头（
00-foo.md、12_bar.md）
- front-matter 里有
只要有一个不满足，整个 group 退回 date-desc。这条规则的意图是"宁可保守，也别把混合 group 偷偷重排"。
例：
post/AI入门到精通系列/
00-导读与学习路线.md ← 数字前缀，触发
01-数学基础.md ← 数字前缀，触发
02-编程能力.md ← 数字前缀，触发
→ 整个 group 升序：00 → 01 → 02
post/数据结构系列/
Heap实现.md ← 没数字前缀
AVL树.md ← 没数字前缀
红黑树.md ← 没数字前缀
→ 退回 date-desc，最近写的在最上
兼容字段（保留但不要新写）
| 字段 | 说明 |
|---|---|
category |
早期分类字段。新文章用 tags 就够了。 |
typora-root-url |
Typora 编辑器自动写入。无害，gobog 解析后不展示。 |