本站 front-matter 全字段速查:一篇配置一篇
这篇既是说明,也是模板:它的头部把这套系统支持的字段全写了一遍,新建文章时照抄、删掉不要的行即可。
一、五秒上手
全部内容都在一个目录 source/posts/ 下,按类型分两个子目录归档:
source/posts/
├─ portfolio/ 作品(tags 含 portfolio 标记)
└─ blog/ 博文
子目录只是归档习惯,可以继续往下嵌套任意层(如 source/posts/portfolio/practice/2026/x.md):构建期递归读取,slug 仍取文件名、类型仍看 tags、URL 与目录无关;文件名(slug)全站唯一(跨子目录同名会被构建拦下并指出两处路径)。最短的一篇只要三行:
---
title: 文章标题
date: "2026-09-16"
tags: [标签一]
---
正文写在第二个 --- 之后。就这三行也能发布,其余字段缺省即隐藏。
二、两个家:站点默认值与逐篇覆盖
配置分两层住,职责不重叠:
- 站点级默认值住
site.yml顶层的 Post Settings 各节(cover/top_img/post_meta/toc/post_copyright/comments/math/aplayer/code_blocks/aside)——仿 Butterfly_config.yml的精神,大多数行为改配置不改代码。 - 逐篇差异住文章自己的 front-matter——只写你要改的那几行,其余自动继承默认值。
构建期把两者合并成「有效值」钉进 .content/posts.json,页面层只读成品、不做默认值推理。所以改 site.yml 后要重跑 npm run content。
三、必需字段
只有三个,作品与博文同一条底线:
title:文章标题。date:创建日期,必须加引号(date: "2026-09-16")——裸 ISO 会被 YAML 读成日期对象,当场校验失败。它同时是全站统一排序键(作品也按date倒序;period只是页面上的展示口径,可写可不写)。tags:标签,至少一个;tags: [写作, 配置]与tags: 写作两种写法都认。它同时承载类型标记(见第五节)。
四、全字段速查表
「本站默认」列 = 你不写它时会发生什么。
| 写法 | 解释 | 本站默认 |
|---|---|---|
title |
【必需】文章标题 | — |
date |
【必需】文章创建日期("YYYY-MM-DD",必须加引号);进热力图的「发布格」 |
— |
updated |
【可选】文章更新日期(ISO,加了才显示);与发布日各占热力图一格 | 不显示 |
tags |
【必需】标签 ≥1;也是类型标记的载体 | — |
draft |
【可选】true = 草稿:不进 .content/posts.json,不出页面 / sitemap / rss,只在构建日志里报数 |
false |
categories |
【可选】文章分类 | 空 |
keywords |
【可选】文章关键字(喂预渲染 <meta keywords>);仅博文——作品不出这枚 meta,博文不写则用 tags 兜底 |
空 |
description |
【可选】文章描述(喂预渲染 <meta description>;也是卡片提要行与详情页侧栏的提要段——署名之下、两型同源) |
回落站点描述 |
top_img |
【可选】详情页顶部大图 | 回落 cover;站点 top_img.enable 一票否决 |
cover |
【可选】归档卡缩略图(false 关 / 图片地址 / 留空回落) |
无图出五档色块 |
comments |
【可选】显示评论模块 | false;且站点 comments.provider: null 时,写 true 也不挂载(不留空壳) |
toc |
【可选】显示目录(有 h2/h3 才出) | toc.post: true |
toc_number |
【可选】目录与正文标题同时编号 | toc.number: true |
toc_style_simple |
【可选】目录简洁模式(扁平内联) | toc.style_simple: false |
copyright |
【可选】显示版权模块 | post_copyright.enable: false |
copyright_author |
【可选】版权模块的文章作者 | 回落 site.author |
copyright_author_href |
【可选】作者名链接 | 不出链接 |
copyright_url |
【可选】版权模块的文章链接 | 回落本站该文绝对地址 |
copyright_info |
【可选】版权声明文字(Butterfly 的 license / license_url 折进这一句) |
回落 post_copyright.info |
mathjax |
【可选】公式引擎开关 | false;math.per_page: true = 逐篇声明才生效 |
katex |
【可选】公式引擎开关(与 mathjax 二选一生效) | false |
aplayer |
【可选】音乐播放器开关 | false;aplayer.per_page: true |
highlight_shrink |
【可选】代码框默认折叠(true/false) | code_blocks.shrink: false |
aside |
【可选】显示右侧信息栏 | aside.enable: true |
background |
【可选】文章背景色 | 不设 |
main_color |
【可选】文章主色,必须 6 位十六进制不可缩写(#ffffff 不能写 #fff) |
不设 |
swiper_index |
【可选】一级置顶序号,数字越小越靠前(全站唯一排序契约,见第七节) | 不设 |
top_group_index |
【可选】次级置顶序号(同上) | 不设 |
relatedWork |
【可选】关联案例(作品)的 slug | 不设;详情页「相关阅读」把它置顶(悬空只在构建期提醒,不出错) |
内容槽与作品字段(
links/video/embeds/embed_hero/period/carousel)列在第五节;本表 + 第五节 =scripts/content/schemas/article.ts的全部字段。
五、类型:加一个标记就变作品
一篇是作品还是博文,只看 tags:
tags里含portfolio→ 作品,走/portfolio/<slug>,可选用下列作品专属字段;tags里不含该标记 → 博文,走/blog/<slug>。
标记词是构建期的分流指令:判定只做一处(
scripts/content/schemas/article.ts的常量),随后构建期会把它从产物的标签里剔掉——所以卡片上不会出现portfolio这枚标签,运行层也不认识这个词。它不可在site.yml里配置(历史上有过blog.portfolio_tag键,会与常量分叉、改了就静默出错,已删)。
所以下面这段就是一篇作品,多写一行可选的 description 提要即可(period 同样可选):
---
title: 作品名
date: "2026-09-16"
tags: [portfolio, 特效]
description: 一句话提要(卡片与详情页侧栏都用它)
period: 2026.09 – 至今
---
详情页只有一套壳子:案例页与文章页共用同一个外壳——顶图槽(有自托管视频出视频 → 声明 embed_hero: true 时出第一条嵌入 → 有图出图 → 都没有不出)· 题头(标题 → 发丝线)· 正文 · 嵌入槽 · 版权槽 · 侧栏(一张信息卡:作者 / 提要 / 发布 · 更新于 · 分类 · 标签;目录在卡外自成一块)全是同一份实现;提要与元信息只住侧栏这一处(关掉侧栏的篇目,只有元信息行回落到标题下;提要不再出现);作品只多一项「周期」,并把类型标签显示为 site.yml 里 blog.work_tag 的「作品」——两型的差别在页面上只剩标签与作品自带的数据。
两个视图、一份数据:/blog 是中心库,展示全部文章(含作品);/portfolio 只是同一份数据里带标记的那个子集。两者由同一次构建产出,不存在两份事实。
内容槽与作品字段(都可缺省,缺省即不渲染那一块);其中 links / video / embeds 两型通用——博文同样能挂播放器,period / carousel 只对作品有意义:
| 字段 | 必填 | 说明 |
|---|---|---|
description |
可选 | 一句话提要:卡片与详情页侧栏(署名之下)都用它(就是「全字段速查」里的那个 description,作品不另起字段) |
period |
可选 | 项目周期,出现于案例页元信息行与侧栏行(2026.09 – 2026.12);作品专属 |
links |
可选 | 外链 [{ label, url }](必须合法 http(s));两型通用 |
video |
可选 | 站内自托管视频 { src, poster, controls, caption };两型通用,占顶部槽位 |
embeds |
可选 | 第三方播放器嵌入(仅白名单平台,必须 https);两型通用,缺省全部留在正文前的「视频」分节(要占顶见下一行) |
embed_hero |
可选 | true = 第一条嵌入占顶部槽(16/9 定比、独占版心);缺省 false = 嵌入只走正文前的「视频」分节 |
carousel |
可选 | true = 上观山顶部纯图轮播;必须同时有 cover 才进得去;作品专属 |
正文中间插视频
正文里独立成行写这一行就行(html: false 的安全不变量不动——这是自定义语法,不是放行原始 HTML):
@[B 站 · 《重回1985》12 集全集连播](https://player.bilibili.com/player.html?bvid=BV1mfK767EqC&autoplay=0&high_quality=1)
- 方括号里是标签(作 iframe 的可访问名,必填);圆括号里必须是播放器地址。三道闸与 front-matter 的
embeds完全同口径(https / B 站页面地址当场教换 / host 白名单),构建期报错并指出文件,坏块不会交付。 - 独立成行才生效(块级规则);写在句子中间不识别,会原样留在段落里。
- 渲染成与「视频」分节同一套 markup(宽度同
--prose-max,与正文阅读宽同档),零新增 CSS、零前端 JS,预渲染照旧带播放器。 - 想让它占顶部槽(16/9 独占版心)用 front-matter 的
embed_hero: true;想让整篇只有一个视频位就只写一处。
六、图片槽三态与回落链
cover 与 top_img 支持三态:图片地址=用这张、false=显式关闭、留空/不写=回落。
回落链:top_img 缺省回落 cover;站点 cover.enable / top_img.enable 设为 false 是全站一票否决。
素材母版一律放 source/images/<slug>/(构建期由 vite 插件直接搬进 dist/images/;站点根静态件住 source/site/,别把图放那儿)。
写路径时就近写母版位置即可:cover: source/images/<slug>/cover.webp 与 cover: /images/<slug>/cover.webp 等价,Windows 绝对路径(如 D:\my-site\source\...)与反斜杠也认——构建期一律归一成交付地址。视频同理:source/video/x.mp4 ↔ /media/video/x.mp4。top_img 与 video.poster 同规。
七、置顶序:swiper_index 与 top_group_index
设了 swiper_index 的排在最前,其次是设了 top_group_index 的,数字越小越靠前;两个都没设就按 date 倒序。本文设了 swiper_index: 1,所以它排在归档最前面。
这一份置顶序是全站唯一的排序契约(实现只有一处:src/lib/data/content.ts 的 compareArticles()),四处列表吃同一份:
| 列表 | 顺序 | 谁能置顶 |
|---|---|---|
/blog 归档网格 + 首页造境段 |
同一契约(日期方向由 site.yml blog.order 给) |
全部文章(含作品) |
| 观山列表 + 观山顶部轮播 + 首页观山段 | 同一契约 + date 倒序 |
作品 |
⚠ 与 Butterfly 的关系:这两个字段不是一套独立的「轮播图列表」,但确实管观山顶部轮播的顺序——轮播成员=作品里声明
carousel: true且有cover的前max_slides张,顺序就是这个置顶序(例:给某件作品写swiper_index: 1,它立刻排到轮播第一张)。轮播的张数上限与切换间隔才在site.yml的portfolio.carousel(max_slides/interval_ms)。
八、代码框与第三方能力
highlight_shrink: true:每个代码块默认收成一段,右下角出按钮展开——下面就是被折叠的样子。comments/mathjax/katex/aplayer是四个受控开关:comments只有在site.yml配好评论服务提供方后才会真正挂载评论区;mathjax/katex/aplayer按 Butterfly 的per_page语义走(per_page: true缺省时只有逐篇声明才加载)。
// 展开按钮的文字住 site.yml a11y(post_code_expand / post_code_collapse),组件零中文字面量
export function resolvePost(fm: FrontMatter, cfg: PostDefaults) {
return {
toc: fm.toc ?? cfg.toc.enable,
copyright: fm.copyright ?? cfg.copyright.enable,
}
}
九、本站 ≠ Butterfly:照抄原文档会踩的坑
| Butterfly 的写法 | 在本站 |
|---|---|
comments 默认 true |
本站默认 false,且 provider: null 时写了也不挂载 |
page 的 top_single_background |
不支持 |
license / license_url |
折进 copyright_info 一句(文案只有一个家) |
post_meta 逐篇覆盖 |
只在 site.yml 的 post_meta 配,无逐篇开关 |
swiper_index = 首页轮播图 |
本站 = 全站置顶序号:归档网格 + 观山列表 + 观山顶部轮播(见第七节) |
mathjax / katex / aplayer 会加载对应 js/css |
本站只落成容器上的 data-* 钩子,第三方脚本尚未接入——写了不报错,但也不会真的渲染公式或播放器(如实标注) |
date / tags 必填 |
一致;本站另把 date 当作全站统一排序键 |
本站额外提供的字段:relatedWork main_color(6 位十六进制且不可缩写)background,以及作品专属一整套(见第五节)。
想看每一篇的真实头部,直接读 site/source/posts/ 里任意一篇;字段的中文解释住 scripts/content/diagnostics.ts 的 FIELD_CN 表,报错时逐字段给你翻译。站点侧每个键怎么配,看配套的《本站 site.yml 全字段速查》——那份管站点,这份管文章。
版权声明
版权声明本文采用「署名-非商业性使用-相同方式共享 4.0 国际 (CC BY-NC-SA 4.0)」许可协议,转载请注明出处。