内容包替换清单
本站是一套模板,装什么内容由内容包决定。换主题时模板层一行都不用改,只需替换下面三类东西。这份清单是实测出来的:曾经用一套完全不同的内容包(中医经典)跑通过一次,模板层文件逐字节一致。
一、改配置层
只改 site.config.js 一个文件。
| 字段 | 改成什么 |
|---|---|
siteId | 新站点的命名空间(订阅标签前缀、搜索索引、权益表都按它隔离) |
title / tagline / navbarTitle / footerText | 站点身份 |
content.root / content.topicSlug | 内容目录名与栏目 slug |
subject.field / labelZh / labelEn / versions / publishedVersions / defaultVersion | 那个「会随版本变」的维度:引擎版本、典籍版本、流派、朝代都行 |
tagGroups | 订阅与筛选用的标签分组 |
changelog.kinds / labels | 变更日志的分类词与字段名 |
llms.title / description / notes / preferredPaths | llms.txt 的站点摘要与推荐起点 |
search.indexPrefix | 搜索索引归属 |
ui.* | 界面文案,全部是 {zh, en} 两套 |
二、内容包必须有的东西
| 必须 | 为什么 |
|---|---|
docs/ 根下一篇文章带 slug: / | 顶栏「首页」指向 /。缺了它构建直接报 Broken link -> /,不是样式问题而是断链 |
每个顶层目录一个 _category_.json | 顶栏第二行的大项就是从这些文件推导的:label 当标题、position 当顺序。collapsed 一律写 true(默认收起),否则侧栏进站就是全展开的一长列 |
辅助栏目写进 ui.navCategories.exclude | 更新日志 / 写作规范 / 上线手册这类栏目留在侧栏即可,占着顶栏会把内容大项挤到后面。填的是目录名,不是 label |
| 每篇 frontmatter 七个必填字段 | title / description / sidebar_position / tags / subject_version / updated / access,缺一个校验就退出 |
i18n/<locale>/ 与 docs/ 一一对应 | 多语言站每篇都要有译文,缺一篇覆盖率检查就报错 |
| 变更日志交给脚本生成 | docs/changelog/ 下的年度文件由 npm run changelog 整篇重写,手写会在下次生成时消失 |
三、换完按顺序验收
npm run check # frontmatter + 架构守卫
npm run check:i18n # 译文覆盖率与中文残留
npm run changelog # 按新内容重建年度文件
npm run build # 真正构建
前四条串起来就是 npm run verify,CI 用的也是它。想连搜索一起验,把 gen:index 也跑一遍——npm run build 已经包含。
四、四个最容易踩的坑
大项放错层级
顶栏第二行只认 docs/ 的顶层目录。把子分类(如 docs/引擎/内存/)当成大项写进配置,顶栏就会出现一个点了 404 的项。新建大项 = 新建顶层目录。
反过来,不想上顶栏的顶层目录要显式排除:ui.navCategories.exclude: ['changelog']。不写就会自动出现——这是「新建目录零配置」的代价,也是它的便利。
档位字段对不上
subject.versions 是白名单,文档里的 subject_version 只要不在里面,校验就报错。换主题时这两处必须一起改,否则第一篇文章就会被拦下。
标签没进 tagGroups
标签不在 tagGroups 里不会报错,但订阅分组、侧栏筛选都会漏掉它。这类问题不会在构建期暴露,只会在读者那里表现为「收不到更新」。
把受控内容放进 static/
static/ 会被原样复制成公开静态文件。受控资产(access 非 free 的正文与附件)一律不能放进去,架构守卫会拦,但别等到被拦才发现。