本站 site.yml 全字段速查:每个键怎么配,什么时候可以删
这篇是给未来的自己(和任何一个要接手这份配置的人)写的:site.yml 有 23 个顶层分节、几十个键,注释虽密,但「哪些删了当场报错、哪些删了只是少一块 UI」光靠翻文件容易记混。本文按分节逐键过一遍,每个键给三样东西:怎么写 / 能不能省 / 省了会怎样。
配套那篇《本站 front-matter 全字段速查》管的是每一篇文章的头部;这篇管的是站点层。两篇合起来,本站零代码能碰的配置面就齐了。
一、先记住三条铁律
- 界面可见中文只住
site.yml。scripts/gate-cn.ts扫src/components与src/pages,注释之外出现汉字即构建失败——导航名、按钮字、aria 文案全在这里,不在代码里。 - 缺省即隐藏。 可选键缺失 = 对应 UI 整块不渲染,不留空壳。这条现已覆盖
about的全部文案键(除hero_title)。 - 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_labelnav_submenu_aria(顶栏分组 caret 按钮的可访问名模板,支持{ink})tabs_labelbrand_labelseal_top_hint(页脚大印:回到本页顶部)skip_link_label - 详情页与按钮:
case_period(周期题词)case_embeds(嵌入分节标题)case_nav_labelcase_prevcase_next(作品详情页「上一件 / 下一件」导航的可访问名与两枚链接题词)detail_ctadetail_aria(支持{ink})carousel_prevcarousel_nextcarousel_pausecarousel_play(轮播暂停/播放键,WCAG 2.2.2) - 关于:
about_seal_labelabout_tags_labelabout_timeline_label - 详情页共用:
post_datepost_updatedpost_categoriespost_toc_labelpost_aside_label(两型同一枚侧栏可访问名)post_comments_labelpost_copyright_headingpost_copyright_authorpost_copyright_linkpost_copyright_noticepost_code_expandpost_code_collapserelated_title(详情页「相关阅读」区块标题,兼该块可访问名) - 内容层:
lightbox_label(点图放大层)lightbox_close(关闭大图)embed_playembed_externalembed_failed(嵌入海报三态)video_retryvideo_open_native(自托管视频失败态) - 外观:
theme_label(三态切换组的 aria-label)theme_lighttheme_darktheme_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 全字段速查》——那份管文章,这份管站点。