上线与更新手册
这份文档只回答两个问题:内容怎么更新、站点怎么上线。每一步都给出可以直接执行的命令,以及执行完应该看到什么结果。
前置条件:Node.js 20 以上(
node -v确认),项目根目录已经npm install过一次。
0. 两条链路速查
| 我要做什么 | 命令 | 耗时 |
|---|---|---|
| 本地预览(改什么看什么) | npm start | 首次约 20 秒 |
| 新增一篇文档 | npm run new -- docs/<栏目>/<文件>.md | 秒级 |
| 提交前自检 | npm run check | 秒级 |
| 打包(含全部守门) | npm run verify | 3–5 分钟 |
| 只打包不守门 | npm run build | 2–3 分钟 |
| 本地看打包结果 | npm run serve | 秒级 |
记住一个原则:npm run verify 通过 = 可以上线;没通过就不要打包上线。
1. 更新内容
1.1 新增一篇文档
npm run new -- docs/ue/networking/my-topic.md
脚本会生成带完整 frontmatter 的骨架,不修改任何配置文件。侧栏、导航、搜索索引、sitemap 全部自动更新——这是本模板的核心约定,新增内容永远不需要碰代码。
1.2 frontmatter 每个字段都要填
---
title: 属性复制与 RPC:带宽预算下的取舍 # 页面标题,也会进搜索索引
description: 从每个 Actor 每帧产生的字节数出发…… # 摘要,列表页与 SEO 用它
sidebar_position: 1 # 同级排序,数字小的在上面
tags: [网络, 复制, 带宽] # 标签,会出现在详情页与变更日志
subject_version: "5.8" # 领域维度,取值必须在配置的版本列表里
updated: 2026-11-13 # 最后更新日期,必须是 YYYY-MM-DD
access: free # free / member / pro,付费项构建期直接拒绝
---
字段缺失或格式不对时,npm run check 会逐条告诉你缺哪个、错在哪:
校验文档 9 篇(领域维度字段:subject_version)
frontmatter 校验通过:字段完整,access 全为 free
1.3 加一个新栏目(分类)
栏目 = 文件夹,顺序与显示名写在文件夹里的 _category_.json:
{
"label": "网络同步",
"position": 3,
"link": {"type": "generated-index"},
"collapsible": true,
"collapsed": true
}
collapsed: true 表示默认收起,读者点标题才展开;当前页所在的分类会自动展开,不用读者再点。collapsible: true 表示允许手动收起。新栏目照抄这一份即可,别写成 false,否则侧栏一进站就是长长一列全展开。
同时要在英文目录放一份孪生声明,否则顶栏的英文名会缺失、npm run check:i18n 会报错:
i18n/en/docusaurus-plugin-content-docs/current/ue/networking/_category_.json
1.4 双语:写中文就必须配英文
这是本模板唯一有硬性负担的地方。每篇 docs/ 下的文档,都必须在同路径下有一份英文译文:
docs/ue/networking/my-topic.md
i18n/en/docusaurus-plugin-content-docs/current/ue/networking/my-topic.md
译文的要求只有三条,全部由脚本自动检查:
| 检查项 | 规则 |
|---|---|
| 文件名 | 与原文完全同名同路径 |
| 正文 | 不允许有成段中文(代码块、行内代码里的中文豁免) |
| 路由字段 | slug 与 sidebar_position 必须与原文一致 |
跑一次就知道缺哪篇:
npm run check:i18n
翻译覆盖:9/9 篇(100%)| i18n/en JSON 文案 111 条
翻译检查通过:文档、分类声明与界面文案均有对应译文,且无残留中文