如何在本博客写文章 —— Frontmatter 字段与内容规范完全指南

1. title —— 文章标题（必填）#

类型：字符串。显示在浏览器标签页、文章顶部、列表页、RSS 等所有涉及标题的位置。

1
title: 如何在本博客写文章

含冒号或特殊字符时请用引号包起来：title: "3 分钟读完：Astro 是什么"

2. published —— 发布时间（必填）#

类型：日期时间（ISO 8601 格式）。用于排序、归档和显示。

1
published: 2026-04-17T10:00:00+08:00

推荐带上 +08:00 时区以避免服务器时区差异。如果只写日期也可以：published: 2026-04-17。

3. updated —— 更新时间（可选）#

类型：日期时间。当你修订一篇旧文章并希望标记”最后更新于”时填写。不填则不显示。

1
updated: 2026-04-18T12:00:00+08:00

4. description —— 文章摘要（推荐）#

类型：字符串。会出现在文章列表卡片、SEO 的 <meta description>、RSS 摘要中。留空时会自动截取正文开头。

1
description: 手把手讲解每篇 Markdown 要写的 Frontmatter 字段。

5. tags —— 标签（推荐）#

类型：字符串数组。一篇文章可以有多个标签，同一个标签可跨分类使用。

1
tags: [博客, 使用指南, Markdown]

• 标签会出现在文章卡片、详情页顶部、标签页
• 归档页会根据标签进行二级过滤
• 建议保持 3-6 个标签，过多反而影响信息密度

6. category —— 分类（推荐）#

类型：字符串。一篇文章只能属于一个分类。

1
category: 博客指南

• 不填或留空时会归入”未分类”
• 分类用于粗粒度划分，标签用于细粒度描述
• 本站当前的常用分类：博客指南 / 文章示例 / 杂谈 / 项目 等，可以自由扩展

7. pinned —— 置顶（可选）#

类型：布尔值。true 时文章会被置顶到主页列表最上方，并显示”置顶”徽章。

1
pinned: true

默认 false。

8. draft —— 草稿（可选）#

类型：布尔值。true 时文章不会出现在生产构建中（本地开发时可见），用于未完成的文稿。

1
draft: true

默认 false。

9. visible —— 可见性（可选）#

类型：布尔值。false 时文章不会出现在列表、分类、标签或搜索中，也不会生成文章详情页；本地开发模式同样隐藏。这不是登录权限控制，不要用它保存私密信息。

1
visible: false

默认 true。

draft 与 visible 的区别：

• draft: true = 本地看得到，线上完全不构建
• visible: false = 本地与线上都隐藏，不生成文章详情页

10. image —— 封面图（可选）#

类型：字符串路径。支持：

• 相对路径（推荐）：./images/cover.webp，与文章同目录
• 绝对路径：/assets/images/cover.webp，放在 public/assets/images/
• 远程 URL：https://...

1
image: ./images/cover.webp

留空则列表卡片不显示封面。

11. author —— 作者（可选）#

类型：字符串。当转载、引用他人作品时填写原作者。留空则使用站点默认作者。

1
author: 张三

12. sourceLink —— 原文链接（可选）#

类型：字符串 URL。转载文章时填写原文地址，会显示在文章底部”来源”处。

1
sourceLink: "https://example.com/original-post"

13. licenseName —— 授权协议名称（可选）#

类型：字符串。例如 CC BY-NC-SA 4.0、MIT、未授权 等。

1
licenseName: "CC BY-NC-SA 4.0"

14. licenseUrl —— 授权协议链接（可选）#

类型：字符串 URL。点击协议名称会跳转到这个链接。

1
licenseUrl: "https://creativecommons.org/licenses/by-nc-sa/4.0/"

15. lang —— 语言（可选）#

类型：字符串。覆盖文章的语言标记，比如写了一篇英文文章想让搜索引擎正确识别：

1
lang: en

留空时使用站点默认语言（zh_CN）。

标题#

1
# H1（文章只用一个，通常不需要写——因为 title 已经是 H1）
2
## H2
3
### H3
4
#### H4

段落与强调#

1
这是一个普通段落。
2

3
**加粗**、*斜体*、~~删除线~~、`行内代码`

列表#

1
- 无序项 A
2
- 无序项 B
3
  - 嵌套 B.1
4
  - 嵌套 B.2
5

6
1. 有序项 1
7
2. 有序项 2

引用#

1
> 这是一段引用。
2
> 可以换行，可以 **嵌套加粗**。
3
>
4
> > 二级引用

链接与图片#

1
[显示文字](https://example.com)
2

3
![替代文本](./images/xxx.webp)
4
![替代文本](/assets/images/xxx.webp)

代码块（含语法高亮）#

1
```ts
2
const a: number = 1;
3
console.log(a);
4
```
5

6
```bash
7
npm run dev
8
```

表格#

1
| 列A  | 列B  | 列C  |
2
| :--- | :--: | ---: |
3
| 左   | 中   |   右 |
4
| aaa  | bbb  |  ccc |

分割线#

1
---

任务列表（GFM）#

1
- [x] 已完成
2
- [ ] 未完成

数学公式（KaTeX）#

行内：$E = mc^2$

块级：

1
$$
2
\int_0^1 x^2\,\mathrm{d}x = \frac{1}{3}
3
$$

Mermaid 流程图#

1
```mermaid
2
graph LR
3
  A[开始] --> B{判断}
4
  B -->|是| C[执行]
5
  B -->|否| D[跳过]
6
```