文档站维护说明

website/ 下其实有两个独立站点：

「website/site/ 的产物目录也叫 docs/」有点绕，但这是刻意的： 官网构建时会把 VitePress 的产物收进自己的 docs/ 子目录， 于是 website/site/docs/ 就是一个自包含的发布目录 —— 官网在根，文档在 /docs/ 下。

官网（website/site/）复制标题链接

为什么是"生成式纯静态"复制标题链接

导航、页脚、应用卡片如果在 5 个 HTML 里各写一遍，改一处要改五处，必然漂移。 所以用 build.mjs 从模板 + 数据渲染出静态 HTML —— 产物仍然是可双击打开的纯静态文件，但维护面只有一份模板。

website/site/
├── build.mjs              构建入口（含本地预览服务器）
├── check-links.mjs        产物站内链接校验
├── src/
│   ├── layout.mjs         <head> + 顶部导航 + 页脚
│   ├── partials.mjs       应用卡片、能力卡、章节标题等复用片段
│   └── pages/             五个页面模板
└── assets/                样式、脚本、logo（构建时原样复制）

cd website/site
node build.mjs           # 构建（会顺带并入文档产物）
node build.mjs --serve   # 构建 + 本地预览（默认 5190）
node check-links.mjs     # 校验站内链接

数据来自哪里复制标题链接

应用名称、版本、菜单数、形态、分类，全部来自 website/docs/data/apps.json —— 由 website/scripts/gen-apps.mjs 扫描各应用 app.json 生成。

要改这些数字，改应用清单，不要改官网。 如果数据文件不存在，构建会直接报错并提示先跑数据生成脚本。

改品牌的地方复制标题链接

文档站（website/docs/）复制标题链接

目录结构复制标题链接

website/
├── package.json                 站点自己的依赖（与 plus-ui 相互独立）
├── scripts/
│   ├── gen-apps.mjs             扫描各应用 app.json → 生成首页/生态页用的数据
│   ├── gen-sidebar.mjs          扫描 docs/<章节>/**/*.md → 生成侧边栏数据
│   └── check-site.mjs           校验侧边栏指向、站内链接、首页数据
└── docs/                        ★ VitePress 的 srcDir
    ├── .vitepress/
    │   ├── config.mts           站点配置：导航 / 搜索 / 页脚（侧边栏是下面那份 import 进来的）
    │   ├── sidebar.mjs          构建期生成（scripts/gen-sidebar.mjs），不要手改
    │   └── theme/               ★ 可选：只做配色，删掉站点照常可用
    │       ├── index.ts         extends DefaultTheme，只 import 下面的 CSS
    │       └── custom.css       主题色 / hero / 卡片 / 表格 / 代码块
    ├── index.md                 首页（VitePress **原生** home 布局：hero + features + 正文）
    ├── public/                  静态资源（logo.svg、hero-wujies.svg 等）
    ├── data/apps.json           构建期生成（scripts/gen-apps.mjs），不要手改
    ├── guide/                   开始使用
    ├── architecture/            架构
    ├── plugin-dev/              插件开发
    │   ├── index.md             章节首页
    │   ├── demo.md              跟着 hello 读源码
    │   ├── basics/              基础：不变量、应用清单
    │   ├── backend/             后端工程 + 本地联调
    │   ├── frontend/            前端远程应用
    │   └── advanced/            进阶：菜单、迁移、种子数据、抽模块、贡献指南
    ├── api/                     API 手册（开放接口 / SDK 契约 / 定位器 / 前端运行时）
    ├── package/                 打包与上架
    ├── deploy/                  部署
    ├── ops/                     运维
    ├── ecosystem/               应用生态
    └── reference/               参考

本地开发复制标题链接

cd website
npm install
npm run dev          # 开发服务器，默认 5180 端口

其它脚本：

主题层是可选的（一条硬约定）复制标题链接

docs/.vitepress/theme/ 只提供配色：index.ts 除 import './custom.css' 外什么都不做， 不注册任何组件。原因是一次真实事故 —— 这个目录曾经整个丢失，而当时首页依赖它里面的 <HomePage />，结果是首页白屏（只剩空白，字都没有）。

所以约定是：

• 首页必须是 VitePress 原生 home 布局（frontmatter 的 hero / features + Markdown 正文）， 不依赖任何自定义组件；首页正文里的区块只用 Markdown + 原生结构写；
• 主题里不要加"首页必须依赖它才能渲染"的组件；
• 主题里不要引外部字体 / 图片 / CDN，视觉元素自绘在 docs/public/ 下。

自证方法（改完主题后应该跑一次）：把 docs/.vitepress/theme/ 整个移走再 npm run build， dist/index.html 里必须仍有 hero 文案、features 与正文 —— 只是回到默认紫色主题。 如果这时首页空了，就说明主题已经变成"渲染必需"，要立刻改回去。

配色分工：品牌色就是 custom.css 里的 --vp-c-brand-1/2/3（浅色与深色两套）， 色相方向与 docs/public/logo.svg 的「靛蓝 → 青」一致。改色值请顺手核对对比度 —— 品牌色上的白字要 ≥ 4.5:1（npm run check:contrast 就是那把量尺）。

写文档的约定复制标题链接

页面复制标题链接

• 每个 .md 只有一个 H1 标题；
• 不写 YAML frontmatter（首页 index.md 例外，它要 layout: home）；
• 中文、技术写作风格：精确、简洁。避免"强大的""完美的"这类营销词。

链接复制标题链接

• 站内链接用绝对路径（/guide/quickstart），不要用相对路径；
• VitePress 会把 .md 后缀去掉生成 URL（cleanUrls: true）；
• 链接到不存在的页面会被 check-site 报错。

⚠️ config.mts 曾经丢失过复制标题链接

docs/.vitepress/ 整个目录一度不存在（website/ 直到 2026-10 才纳入 git，纳入时 docs/ 里只有 md 与 public/）。后果：站点没有导航/侧边栏/搜索， 而且 check-site.mjs 直接报错退出 —— 那套守门等于没有。

现已按现有目录与各页 H1 生成（不是手写），侧边栏与目录结构因此天然一致。 两个由校验器逼出来的约定：

• 没有 index.md 的章节，导航指向它的第一个页面 —— 指向 /<sec>/ 会被判死链 （guide / architecture / reference 目前都没有 index.md）；
• index.md 的链接写 /<sec>/，不是 /<sec>/index —— 后者能打开， 但校验器会认为该章节首页"没有侧边栏入口"。

侧边栏是生成的，不是手写的复制标题链接

侧边栏不写在 config.mts 里：scripts/gen-sidebar.mjs 扫描 docs/<章节>/**/*.md 生成到 docs/.vitepress/sidebar.mjs，config.mts 只 import { sidebar } from './sidebar.mjs'。 规则都在脚本里（改规则改脚本）：

• 显示名取每页第一个 H1（跳过代码块），guide/quickstart 这类一句话式 H1 在 脚本的 TEXT_OVERRIDES 里换成短标签；
• 同一层里子目录与页面按名字字典序混排；
• 目录有 index.md 时成为可点击的分组（link 指向 /<dir>/），index.md 不再单独成条目；
• 没有 index.md 的目录靠脚本里的 GROUP_LABELS 起名（如 plugin-dev/basics → 基础）。

加页面、改目录之后必须重跑 npm run gen:sidebar，否则 check-site 会提醒该页 没有侧边栏入口（在站点里不可达）。

容器复制标题链接

允许 ::: tip / ::: warning / ::: danger / ::: details，标题跟中文。

敏感信息复制标题链接

校验复制标题链接

npm run gen:apps
npm run gen:sidebar
node scripts/check-site.mjs

check-site.mjs 会校验三件事：

1. 侧边栏与导航里列的链接是否都指向真实存在的页面；
2. 所有正文里的站内链接是否都能落到真实页面；
3. 首页用的 apps.json 是否存在、字段是否完整。

它同时会提醒"没有侧边栏入口"的页面。

部署复制标题链接

构建产物是纯静态文件，放在 docs/.vitepress/dist，扔到任意静态托管即可。

相关阅读复制标题链接

• 设计与决策存档
• 开发指南（贡献者）