跳到主要内容
版本:Next

内容包替换清单

本站是一套模板,装什么内容由内容包决定。换主题时模板层一行都不用改,只需替换下面三类东西。这份清单是实测出来的:曾经用一套完全不同的内容包(中医经典)跑通过一次,模板层文件逐字节一致。

一、改配置层​

只改 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 / preferredPathsllms.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 的正文与附件)一律不能放进去,架构守卫会拦,但别等到被拦才发现。