1018 字
5 分钟
Frontmatter 元数据字段说明

每篇文章开头用三条横线 --- 包裹一段 YAML,称为 Frontmatter,用来声明文章的标题、日期、分类、行为等元数据。

完整字段模板#

---
# ── 必填 ──────────────────────────────
title: "文章标题" # 文章主标题
published: 2026-08-27 # 发布日期(YYYY-MM-DD)
# ── 时间与更新 ─────────────────────────
publishedAt: 2026-08-27T10:30:00+08:00 # 精确发布时间戳(同日多篇排序用)
updated: 2026-11-06 # 最后更新日期
updatedAt: 2026-11-06T15:45:00+08:00 # 精确更新时间戳
# ── 摘要与封面 ─────────────────────────
description: "文章摘要,用于卡片和 SEO" # 留空自动截取正文前段
image: "./image.png" # 封面图(相对路径或外链)
# ── 分类与标签 ─────────────────────────
category: "使用指南" # 单分类
tags: # 多标签
- "Shirone"
- "Markdown"
# ── 行为控制 ─────────────────────────
pinned: true # 置顶到列表最前(默认 false)
draft: false # 草稿,true 时不进生产构建(默认 false)
comment: true # 开启评论区(默认 true)
# ── 系列关联 ─────────────────────────
series: "starter-guide" # 所属系列 slug,对应 content/series/<slug>.md
seriesOrder: 1 # 系列内排序序号(缺省按发布日期排)
# ── 加密 ────────────────────────────
encrypted: true # 标记文章加密
password: "shirone-secret" # 解锁密码(设置后 encrypted 隐式为 true)
passwordHint: "提示语" # 密码输入框下方提示
hideHomeContent: true # 首页/归档/RSS 隐藏摘要与字数
# ── 其他 ────────────────────────────
lang: "zh_CN" # 文章语言(默认取站点语言)
---

字段逐项说明#

必填字段#

title必填string

文章主标题,显示在文章页顶部、列表卡片与浏览器标签页。

published必填YYYY-MM-DD

发布日期。文章按此日期倒序排列,也用于归档页分组。

时间与更新#

publishedAt可选ISO 8601 时间戳

精确发布时间(含时区)。同一天发布多篇时用于精准排序;填写后其日历日期必须与 published 一致,否则构建报错。

updated可选YYYY-MM-DD

最后更新日期。设置后文章页会显示”最后更新”信息。

updatedAt可选ISO 8601 时间戳

精确更新时间戳,配合 updated 使用。

摘要与封面#

description可选string

文章摘要,用于列表卡片简介与搜索引擎摘要。留空时自动截取正文前段。

image可选string

文章封面图。支持相对路径(如 ./image.png,与文章同目录,构建期自动优化)或网络外链。

分类与标签#

category可选string

文章所属分类,只能填一个。归档与分类页按它分组。

tags可选string[]

标签列表,可填多个。用于标签页聚合与相关文章推荐。

行为控制#

pinned可选boolean
false

设为 true 时文章置顶到列表最前,不受发布日期排序影响。

draft可选boolean
false

设为 true 时文章为草稿,不进入生产构建,仅本地开发可见。

comment可选boolean
true

是否开启本篇文章的评论区。

系列关联#

series可选string

所属系列的 slug,对应 content/series/<slug>.md。声明后文章页出现系列导航(“第 X/共 N 篇”、上/下一篇)。

seriesOrder可选number

系列内排序序号。缺省时按发布日期排序。

加密#

encrypted可选boolean
false

显式标记文章为加密。设置了 password 时隐式为 true。

passwordstring

@type string @required(加密时)

前端加密的解锁密码。构建期加密、运行期解密,访客输入正确密码才能阅读。

passwordHint可选string

显示在密码输入框下方的提示语。

hideHomeContent可选boolean
true

加密时在首页卡片、归档与 RSS 中隐藏文章摘要与字数,防止泄漏。

其他#

lang可选string

文章语言代码(如 zh_CN、en、ja)。缺省取站点语言。

最小可用示例#

只填必填项也能正常发布:

---
title: "我的第一篇文章"
published: 2026-08-27
---

注意事项#

  1. pinned 置顶:多篇置顶时,置顶文章之间仍按发布日期排序。
  2. draft 草稿:适合未完成的随笔,推送后不会出现在线上。
  3. 加密安全:password 是前端加密,防浏览不防破解;敏感内容勿依赖它。
  4. image 路径:优先用相对路径与文章同目录存放,可享受构建期图片优化。

第 1 篇,共 20 篇本文属于系列

分享文章

生成精美分享图或复制链接,与更多人分享本文。

继续阅读

沿着主题读

基于共同的标签与分类

换条路线

从其他文章中稳定抽取