本站 site.yml 全字段速查:每个键怎么配,什么时候可以删

这篇是给未来的自己(和任何一个要接手这份配置的人)写的:site.yml 有 23 个顶层分节、几十个键,注释虽密,但「哪些删了当场报错、哪些删了只是少一块 UI」光靠翻文件容易记混。本文按分节逐键过一遍,每个键给三样东西:怎么写 / 能不能省 / 省了会怎样。

配套那篇《本站 front-matter 全字段速查》管的是每一篇文章的头部;这篇管的是站点层。两篇合起来,本站零代码能碰的配置面就齐了。

一、先记住三条铁律

  1. 界面可见中文只住 site.yml。 scripts/gate-cn.ts 扫 src/components 与 src/pages,注释之外出现汉字即构建失败——导航名、按钮字、aria 文案全在这里,不在代码里。
  2. 缺省即隐藏。 可选键缺失 = 对应 UI 整块不渲染,不留空壳。这条现已覆盖 about 的全部文案键(除 hero_title)。
  3. strict 白名单:拼错键就等于构建失败。 每个对象都是 strict 的——多一个键、少一个必填键、类型不对,都会在 npm run content 阶段被拦下并给出中文解释。改键名要同步两处:scripts/content/schemas/site.ts 与 src/lib/types/site.ts;scripts/content/contract.ts 会拦住两者的漂移。

改完 site.yml 记得重跑 npm run content——.content/*.json 是构建期产物,页面读的是它,不是 yml 本身。

二、顶层总览:哪些节能省,哪些不能

顶层节 整节可省? 节内必填 管什么
site ❌ 不能 title author lang description url 站点元信息 / canonical / sitemap / rss
nav ❌ 不能 每条 6 个字段全给 双导航 / 路由白名单 / 预渲染页面清单
page_meta ✅ 可整节删 — 子页 <title> 专名(首页用 home 键给整条标题)
page_desc ✅ 可整节删 — 静态页 <meta description> 专写(键法同 page_meta;未写回落策略小表)
home ❌ 不能 sections ≥1 段;每段 id + (heading 或 heading_lines ≤2 行) 首页五段
portfolio ✅ 可整节删 — 观山轮播张数
blog ✅ 可整节删 — 归档列表 / 首页造境段 / 卡片标签
cover top_img post_meta toc post_copyright comments math aplayer code_blocks aside ✅ 十节都可整节删 — 文章详情的站点级默认值(Post Settings)
heatmap ✅ 可整节删 给了就要给全 9 键 首页造境段与 /blog 的热力图
about ❌ 不能 仅 hero_title /about 便当盒(话术 + 事实)
contact ❌ 不能 email 页脚联系方式栏
footer ❌ 不能 columns seal_text copyright(brand_bio 2026-09-23 起可省) 页脚 / 首页传音段 / favicon 印文
notfound ❌ 不能 line cta 404 页
a11y ✅ 可整节删 —(46 键全可选) 全站 aria 与可见小字

一句话记法:「骨架进必填,能力进可省」。 站点身份、页面清单、首页结构、关于页标题、联系方式与页脚、404,这些是骨架;轮播、归档开关、热力图、文章默认值、aria 文案,这些是能力,删了只退场不报错。

三、逐节逐键

3.1 site(必填节)

键 必填 说明
title ✅ 站点名;页面 meta 回落它,也作标题后缀
author ✅ 作者名;/about 深墨卡的名字、版权模块作者回落到它
lang ✅ 注入 <html lang>(如 zh-CN)
description ✅ 兜底摘要:未专写 page_desc 的静态页 + RSS 频道描述
url ✅ 站点绝对 URL:逐路由 canonical、sitemap、rss、robots 的域唯一来源;必须是合法 http(s)
tagline 可选 备用副题,当前无消费者(写了不报错,也不出现在任何地方)

3.2 nav(必填节,双导航共用)

每条六字段,全部必填:

字段 取值 约束
ink 显示名 全站唯一(React key 与「同 id 同词」律)
route / 或 /xxx,可 null 基础路由;/ = 首页;基路径全站唯一
isDetailPage true / false 该条目是否带动态详情页
detailPrefix 以 / 开头的路径,可含 #锚点 isDetailPage: true 时必填;false 时必须为 null
module 首页段 id,可 null 非 null 时必须命中 home.sections 的 id,且全站唯一
parent 父条目的基础路由,可 null 顶栏分组归属(口径同 route:去 #锚、空值回落 /)。null = 顶栏一级项;非 null 时必须命中另一条 nav 的 route 基础路径、不得自指、且父条目自身必须是 null(只允许一层)。写错的条目会从顶栏静默消失,故构建期硬拦
nav:
  - { ink: 山门, route: /,          isDetailPage: false, detailPrefix: null,       module: home,      parent: null }
  - { ink: 观山, route: /portfolio, isDetailPage: true,  detailPrefix: /portfolio, module: portfolio, parent: null }
  - { ink: 造境, route: /blog,      isDetailPage: true,  detailPrefix: /blog,      module: blog,      parent: null }
  - { ink: 归档, route: /archive,   isDetailPage: false, detailPrefix: null,       module: null,      parent: /blog }   # 收进「造境」的下拉面板

构建期还会逐条查:ink 重复、route 基路径撞车、detailPrefix 撞车、module 不在 home.sections 或重复、parent 悬空/自指/父条目自身带 parent。内链白名单也从这张表派生——加页面 = 加一行。

3.3 page_meta / page_desc(meta 两节,均可整节省)

自由 record,键 = 该页路由的 basename(/portfolio → portfolio)。缺键回落 site.title。它只喂预渲染的 <title>,不进页面可见层。

首页是唯一破例:它的 basename 是空串,没有段名可用,故键名取 home(与 nav 的 module: home 同词),值是首页整条 <title>——不套 <专名> · <站名> 后缀,想放什么就写什么(本站取「作者名 · 站名」=杜康 · 砚山,与子页后缀同构)。缺键时首页标题就只剩 site.title。

page_meta:
  home: 杜康 · 砚山   # 首页整条 title(本节唯一破例键)
  portfolio: 观山
  about: 观自

page_desc 是与它成对的姊妹节(只管静态页;文章详情页的摘要一直取该篇 front-matter 的 description):键法完全相同(键 = 路由 basename,首页用 home),值进 <meta name="description">。命中即用;未命中回落 page-meta.ts 的 STATIC_DESC 策略小表(''/portfolio/about → site.description,blog → 该段 intro(缺则回落 site.description);未列出的新页默认 site)——所以新页面零配置也有摘要,写这几条只为让 / 与三个列表页两两不同。本站一律只写一句短语(与页面专名同构):摘要是 title 的补充说明,不靠它堆词。

page_desc:
  home: 杜康 · MoyunLee
  portfolio: 观山 · 作品全览
  blog: 造境 · 笔墨札记
  about: 观自:关于杜康

3.4 home(必填节)

sections 是数组,顺序即渲染顺序,至少 1 段:

键 必填 说明
id ✅ 段 id = 锚点 id;必须在 src/site/sections.ts 有组件实现(否则「幽灵项」构建失败);全站唯一
heading 二选一 单行标题
heading_lines 二选一 横排断句标题,最多 2 行
en 可选 英文副题(可 null)
intro 可选 段引言(可 null);只对走段标题行的段有效(观山 / 造境 / 观自)
cta 可选 按钮数组 [{ label, to }]
cta_detail 可选 标题行「查看详细」开关,缺省 true;同 intro——山门与传音自带题头,写这两个键会被构建拦下(零消费者开关)

当前实现的段 id 一共 5 个:home portfolio blog about footer。heading 与 heading_lines 至少给一个;两个都不给 = 校验失败。

3.5 portfolio(可整节省)

键 必填 缺省行为
carousel.max_slides 可选 删键/整节删 = 不限张数;候选多于上限时只呈现前 N(构建期给提醒,不阻断)
carousel.interval_ms 可选 缺省/删 = 5000 毫秒

本节曾另有 toc.enable / toc.number / toc.style_simple 三键(作品目录默认值与博文分家)——2026-09-21 统一壳子后整组退役:两型同走 Post Settings 的 toc.*,作品仍可逐篇用 front-matter 的 toc / toc_number / toc_style_simple 覆盖。

注意:轮播成员不在这里点名——由各作品 front-matter 的 carousel: true 且有 cover 决定,这里只管「最多几张、多久换一张」。

3.6 blog(可整节省)

键 取值 缺省行为
order desc / asc 缺省 desc(新文章在前)
tags_max 正整数 删键 = 不限量
preview_max 正整数 缺省 6(首页造境段预览卡上限,超出的不渲染、不占 DOM)
work_tag 字符串 作品在归档卡与作品详情页(元信息行 / 侧栏标签胶囊)上的中文标签;删键 = 两处都不加这枚标签

注意:卡面那行日期不归本节管。卡片统一后日期是结构元素、恒出(值 = updated 优先,缺省回落 date)——原来的 show_date 开关已退役,本节没有它。

3.7 Post Settings 十节(每节都可整节删)

优先级:逐篇 front-matter > 本节 > 内置缺省。下表「内置缺省」列 = 整节删掉之后的行为:

键 内置缺省 说明
cover.enable 视为开 false = 全站强制色块,无视逐篇 cover
top_img.enable 视为开 false = 全站禁顶部大图
post_meta.post.date_type both created 只出发布 / updated 只出更新(缺则回落发布)/ both 都出
post_meta.post.categories true 侧栏是否出「分类」行(作品 / 博文同一套开关)
post_meta.post.tags true 侧栏那排标签胶囊是否出
post_meta.post.label true 是否出「发布 / 更新于 / 分类 / 周期」这类行首词
toc.post true 详情页出目录(有 h2/h3 才出;作品同这一套)
toc.number true 目录与正文标题同时编号
toc.style_simple false 简洁模式(扁平内联)
post_copyright.enable false 版权模块开关
post_copyright.author null null = 回落 site.author
post_copyright.author_href null null = 作者名不出链接
post_copyright.url null null = 回落本站该文绝对地址
post_copyright.info null 声明文字;开后不给 = 空串(开版权务必给 info)
comments.enable false 评论开关
comments.provider null null = 即便逐篇 comments: true 也不挂载(不留空壳)
math.per_page true true = 逐篇声明才加载
math.mathjax.enable / math.katex.enable false 引擎开关(per_page: false 时才全站生效)
aplayer.enable false 音乐播放器开关
aplayer.per_page true 同 math 的逐篇语义
code_blocks.shrink false 代码框默认折叠
aside.enable false ⚠ 整节删掉文章就没有右侧信息栏(只剩标题下的元信息行;提要只住侧栏,随之消失);本站现配 true

3.8 heatmap(可整节省;给了就要给全)

整节删 = 热力图整块不出。给了,则下面 9 个键一个都不能少(长度即刻度,写死防错位):

键 约束
title 支持 {year}(所选年)与 {n}(该年条数)
less / more 图例两端文字
tip 有更新悬浮提示,{date} {n}
tip_empty 空白格悬浮提示,{date}
region_label 区块 aria-label
years_label 年份页签组 aria-label
weekdays 恰好 7 项,周日起
months 恰好 12 项,索引 0 = 1 月

数据口径:热力图吃全部文章(含作品),每篇按「发布日 + 更新日」各记 1 条(updated 缺省、或与 date 同日时只记 1 条)——所以 {n} 是条数(发布 + 更新事件数),不是文章数。口径住在代码里(src/lib/data/content.ts 的 heatItems),本节只管文案与刻度。

3.9 about(必填节;话术 + 事实同家)

about 这一节本身不能删,但节内只有 hero_title 是必填:

键 必填 说明
hero_title ✅ /about 顶部书法大题,本页唯一 h1 的文本
anchors 可选 本页声明的锚点段;给了就必须含 about + footer,作内链 /about#碎片 校验的事实源(构建期硬校验:缺一端点即报错)。不写就不校验

以下 17 个文案键全部可省,删键即不渲染对应元素:

键 管哪一块 删了会怎样
tags_left / tags_right 顶部印章左右标签列 该列不出(另一列与印章照常)
label_intro 深墨卡左上小字 不出
intro_lead 深墨卡大字前缀(如「我叫」) 只出后面的名字
intro_sub 深墨卡第三行定位句 少这一行
label_pursuit 追求卡左上小字 不出
title_pursuit_a 追求卡大字前段 不出(若 title_pursuit_b 也缺则整行不出)
title_pursuit_b 追求卡朱砂高亮段 只出前段
label_skill 技能卡左上小字 不出
title_skill 技能卡大字题 不出
label_career 生涯卡左上小字 不出
title_career 生涯卡大字题 不出
label_place 坐标卡左上小字 不出
title_place 坐标卡大字题 不出
place_note 坐标卡配文,支持 {city} 该行不出;与 place_avail 同时缺则整块 meta 区不出
place_avail 可实习城市 / 合作方式 该行不出
place_coord 装饰坐标(纯装饰) 不出

技能卡有两张表,唯一事实源都在 about:

① skills——平铺技能表(2026-09-27 由四组 skill_groups 拍平;组名与组图标随之退役)。每行四键,整块可省:

skills:
  - { name: 3dsmax, level: 4, exp: 760, icon: 3dsmax.svg }        # name=技能名(写软件名;全表唯一)
  - { name: ZBrush, level: 3, exp: 570, icon: zbrush.svg }        # level=档位号 1-N(须与本行 exp 同档)
  - { name: Photoshop, level: 4, exp: 640, icon: photoshop.svg }  # exp=经验值 0-1000:决定条长,满分=末档 max

icon 是行首方章里的图标,两种写法:不带冒号的当文件名(住 source/site/skill/,见下节)、带 lucide: 的当兜底字形(拿不到官方标时的退路:当前 11 条全部用文件,这条通道空着备用)。

图标是文件,住 source/site/skill/(站点根静态件目录 source/site/ 下的一个子目录,发布后就是 /skill/<文件名>);解析在 src/components/about/skills/skillIcon.ts。不给 icon 才回落 circle(中性圆点),所以这里不设枚举硬校验。

怎么换图标:

  • 换:把新图丢进 source/site/skill/,site.yml 的 icon 写成那个文件名(如 icon: blender.svg)即可 —— 不改代码。
  • 两条硬要求(运行时用 CSS mask 只取形状、颜色由网站统一给):① 图片必须有透明底 —— 不透明底色(含 JPEG,没有 alpha 通道)会被染成整块实心方块;② 形状之间别互相遮盖,同色叠一起会并成一块(官方「彩色版」常是「底色方块 + 上面画字」:方块会被染成整块实心,得把方块丢掉、只留字 —— 生成器清单里的 drop 就是干这个的,Ae / Ps / Pr / Pt 四枚都这么来)。
  • 文件名写错会怎样:构建期直接报错并列出目录里现有的文件名(✗ site.yml › about.skills.4.icon:找不到图标文件 source/site/skill/photoshop.png(现有:3dsmax.svg、…)),不会带着一个空洞上线。
  • 想从 Iconify 抓官方标(可选):scripts/vendor-skill-marks.ts 的清单加一行(文件名 · Iconify id · 产品名 · 许可 · 可选的"要丢掉的 path 序号"与"取景 viewBox")→ 跑 node scripts/vendor-skill-marks.ts,文件就出现在同一个目录里。构建期不联网:抓取只发生在你手动跑脚本那一次;你手工丢进目录的图,这个脚本不碰。
  • 拿不到官方标时:icon 写 lucide:brush 这类兜底字形 id,字形表在 src/components/about/skills/skillIcon.ts(ZBrush 早先用过这条路,现已换成官方标)。

尺寸与配色都不用手管:方章恒 26px、图标恒 16px(CSS 统一,viewBox 是 24 还是 128 都一样);唯一要自己照看的是取景 —— 图形在画布里只占中间一小块时,页面上就比邻条小一圈(丢图前裁紧即可;官方标由清单里的 crop 收紧,量法见 .shots/probe-skill-ink.mjs);颜色一律是墨色、跟随方章,悬停时转本档色阶 —— 丢彩色 Logo 进去,页面上也是墨色(要保留图片原色就得改版式,那是另一件事)。

整块删 = 技能卡整张不渲染;给了就不能给空数组,技能名不能重复;level 与 exp 不同档当场报错(防「Lv.2 却跑 700 经验」)。

② skill_levels——等级体系(档位名的唯一来源;组件内零中文字面量,加档只在表尾追加):

skill_levels:
  - { name: 了解, max: 200 }    # max = 本档经验值上界(累计口径)
  - { name: 熟悉, max: 400 }    # 档位号 = 数组下标 + 1 → 卡面出 Lv.N
  - { name: 掌握, max: 600 }
  - { name: 熟练, max: 800 }
  - { name: 精通, max: 1000 }   # 经验满分 = 末档 max(1000)

事实层(2026-09-16 由 content/about/about.md 整份并入;site/content/ 已删)——三块都可整块省,缺省即隐藏:

键 说明 删了会怎样
timeline 生涯卡节点 { period, text } 数组;数组顺序即从上到下 生涯卡整张不出
location 现居城市;填 place_note 的 {city} {city} 填空,卡片照旧
about:
  timeline:
    - { period: "2024 - 2027", text: 动漫制作技术专业(在读) }
  location: 中国,长沙市
  anchors: [about, footer]

3.10 contact(必填节)

email 必填且必须通过邮箱正则。其余键是 catchall:平台名随意,值必须是这个形状(strict):

contact:
  email: someone@example.com
  wechat:   { platform: 微信, value: 你的微信号, url: null }        # 有值但无可用链接:url: null
  github:   { platform: GitHub, value: inkstone-peak, url: "https://github.com/MoyunLee/inkstone-peak" }
  bilibili: { platform: B 站, value: 雨夜鱼龙舞yo, url: "https://space.bilibili.com/1800744550" }

url: null 时渲染成灰字、不可点(不留死链):有 value 就显示 platform · value,只有 pending 才显示待建文案。本站现有三行社交(微信 / GitHub / B 站),其中 wechat 正是这一类——微信号没有可用的 http(s) 链接,只能 url: null(--ink-3 灰字 4.59:1 达标,但要复制得手抄);url 若给了就必须是合法 http(s)。

卡面文字 = platform · value(本站现有三行:微信 · MoyunLee / GitHub · inkstone-peak / B 站 · 雨夜鱼龙舞yo,数组顺序即渲染顺序)。url: null 的灰字行惯例排最后,唯一例外是 wechat——它是国内最主要渠道,故紧随 email。加一行 = 在 contact 下加一个键,页脚「联系」栏自动出现,组件零改动。

3.11 footer(必填节)

键 必填 说明
columns ✅ 栏目数组(见下)
email_label 可选 「联系」栏邮箱行的前缀标签(本站 邮箱,渲染成「邮箱 · 2106996916@qq.com」);删键=裸地址。界面中文的家仍是 site.yml,组件不写死
tab_label 可选 侧栏题签里那条「直达脚页」的题签名(本站 传音);落点由题签按 home.sections 的 footer 段推导,不写进 nav(nav 每行六个字段);删键=右侧题签不出现这一条
brand_bio 可选 栏1 印章下方的简介段;曾承载求职意向/地域口径的全站唯一落点。删键=整段不渲染、印章照常居中(本站 2026-09-23 已删,原句以注释留底在 site.yml)
seal_text ✅ 印文;页脚大印与构建期生成的 favicon / apple-touch-icon 都用它
copyright ✅ 版权行
demo_note 可选 演示站小字;发布前删,checklist 会提醒

columns 的三种写法:

columns:
  - { id: brand,     title: null }              # 特例:居中印章(brand_bio 可省),无栏题
  - { id: site,      title: 导航, from: nav }    # 从 nav 自动生成,加页面自动出现
  - { id: social,    title: 联系, from: contact }            # 从 contact 自动生成
  # 想再加一栏就照这样内联写(示例:作品 / 流程 / 关于我):
  # - { id: portfolio, title: 创作, links: [ { label: 作品, to: /portfolio }, { label: 流程, to: /blog }, { label: 关于我, to: /about } ] }

列数不用管 CSS:.foot-cols 的中间轨道数由组件按 columns.length − 2 现算,增删栏位只改这里。

规则:id === brand 是特殊栏;非 brand 栏必须给 from(nav / contact)或 links(内联 [{ label, to }])之一,两者都没有 = 构建失败。

to 允许四类:站内路由(须命中从 nav 派生的白名单)· http(s) 外链 · mailto: · source/site/ 下的静态件(任何带扩展名的文件,构建期查落盘)。没有专门的 cv 字段。(2026-10-03 用户令:本站不放简历 PDF,怕个人信息泄露;这条通用通道留着给别的文件。)

3.12 notfound(必填节)

line(提示语)+ cta({ label, to })。同一套文案生成 dist/404.html 并注入 noindex。

3.13 a11y(可整节省;46 键全可选)

缺键 = 不输出该属性;但键名仍走 strict 白名单,拼错照样报错。46 键按用途分七组:

  • 布局:nav_label nav_submenu_aria(顶栏分组 caret 按钮的可访问名模板,支持 {ink})tabs_label brand_label seal_top_hint(页脚大印:回到本页顶部)skip_link_label
  • 详情页与按钮:case_period(周期题词)case_embeds(嵌入分节标题)case_nav_label case_prev case_next(作品详情页「上一件 / 下一件」导航的可访问名与两枚链接题词)detail_cta detail_aria(支持 {ink})carousel_prev carousel_next carousel_pause carousel_play(轮播暂停/播放键,WCAG 2.2.2)
  • 关于:about_seal_label about_tags_label about_timeline_label
  • 详情页共用:post_date post_updated post_categories post_toc_label post_aside_label(两型同一枚侧栏可访问名)post_comments_label post_copyright_heading post_copyright_author post_copyright_link post_copyright_notice post_code_expand post_code_collapse related_title(详情页「相关阅读」区块标题,兼该块可访问名)
  • 内容层:lightbox_label(点图放大层)lightbox_close(关闭大图)embed_play embed_external embed_failed(嵌入海报三态)video_retry video_open_native(自托管视频失败态)
  • 外观:theme_label(三态切换组的 aria-label)theme_light theme_dark theme_system(三个选项文案,默认态=跟随系统)theme_switch_hint(窄屏收起按钮的 title/aria-label 兜底)
  • 列表页:archive_clear(/archive 筛选条上的撤销按钮:点了热力图某一天之后,把年表还原成全目)

四、删了会怎样(速查)

删掉 结果
site.tagline 无影响(当前无消费者)
page_meta.<某页> 该页 <title> 回落 site.title
page_meta.home 首页 <title> 回落 site.title(首页标题只剩站名:无作者、无职业词)
page_desc 整节 四页摘要回落策略小表(''/portfolio/about → site.description;blog → 该段 intro,现为 null 故仍回落 site.description)
portfolio 整节 轮播不限张数、间隔 5000ms
blog 整节 新在前 / 标签不限 / 首页预览 6 张 / 不出「作品」标签
heatmap 整节 首页造境段与 /blog 的热力图整块不出
about 任一文案键 对应那一行 / 那一块不出
about.skills 技能卡整张不出
about.timeline 生涯卡整张不出
about.location 坐标卡的 {city} 填空(卡片仍在)
about.anchors 不再校验 /about#碎片(页面无变化)
Post Settings 任一节 走第三节「内置缺省」列
aside 整节 文章不出右侧信息栏卡片;回落到标题下的只有元信息行(日期 / 分类 / 周期 / 标签),提要只住侧栏那一处,关掉即不出现
footer.demo_note 页脚右下小字消失
about.place_coord 坐标卡右下角坐标消失
a11y 任一键 该 aria / 可见小字不输出
非 brand 栏的 from / links ❌ 构建失败(不能省)

五、改配置会连锁影响什么

  • nav 加一行:预渲染页面清单、sitemap、rss、页面 meta、双导航、滚动高亮、内链白名单全部自动跟;如果是一个新页面,还要写页面组件并在 src/routes.tsx 注册。
  • home.sections 加一段:三件事一起做——yml 加段、src/site/sections.ts 注册组件、nav 挂 module。
  • footer.seal_text:页脚大印与构建期生成的 favicon / apple-touch-icon 都用它,改完重跑 npm run assets。
  • 类型标记:不在 site.yml 里配——「作品 / 博文」的判定住构建期(scripts/content/schemas/article.ts 的常量),运行层只看 kind;构建期还会把标记词从产物标签里剔除,所以卡片上不会露出 portfolio。
  • about.skills:技能卡的唯一事实源,改表即改卡(技能名唯一、level 与 exp 必须同档,构建期硬校验)。
  • site.yml about 的事实层:timeline / location / anchors 与话术同住 about(2026-09-16 由 content/about/about.md 整份并入,site/content/ 已删);place_note 的 {city} 由 about.location 填。

六、常见报错对照

报错 大概率原因
「xx」不在 home.sections 的 id 之列 nav[].module 拼错,或段还没加
「xx」在 src/site/sections.ts 无组件实现(幽灵项) home.sections 写了段 id,但没注册组件
「…」不是合法邮箱 contact.email 格式
「…」必须是合法的绝对 http(s) URL site.url(或某个社交 url)
「…」的 path 段未命中路由表(白名单:…) 内链指向了不存在的站内路由——加页面请先在 nav 加一行
非 brand 栏必须给 from 或 links footer.columns 某栏两样都没给
技能名「…」重复 about.skills[].name 撞车(2026-09-27 起唯一性从「组 id」改到「技能名」)
横排断句标题最多两行 heading_lines 超了 2 行
未知键 / 类型错误 / 必填缺失 strict 会直接点出键名,中文解释见 scripts/content/diagnostics.ts 的 FIELD_CN 表

七、最小可用 about 段(已实测)

about 是必填节,但除 hero_title 外整节删到只剩一行也能过:

about:
  hero_title: 观自

这份配置跑 npm run content、npx tsc --noEmit、中文闸与完整 npm run build 全部通过:页面只出顶部大题,标签列、深墨卡第三行、生涯卡、技能卡与坐标卡 meta 行全部安静退场。这就是「缺省即隐藏」的实际手感——删键 = 删除 UI,不是删除校验。

八、加东西的完整清单

想做的事 要动的文件
改文案 / 导航名 / 段序 / 社交链接 / a11y 只动 site.yml
加一个普通页面 nav 加一行 + 写页面组件 + src/routes.tsx 注册
加一个首页段 site.yml home.sections + src/site/sections.ts 注册 + nav 挂 module
新构建期校验 scripts/**

字段的中文解释住 scripts/content/diagnostics.ts 的 FIELD_CN 表,报错时会逐字段翻译。要理解每一篇文章头部怎么写,看配套的《本站 front-matter 全字段速查》——那份管文章,这份管站点。