文档维护

Maintain

文档维护

这里记录文档站的维护规则、页面模板、质量检查清单和部署建议。

本文档站暂时和组件库源码放在同一个仓库中维护。

为什么不独立成项目

当前不建议把文档源码拆到同级独立项目，原因是：

原因	说明
强依赖源码	文档需要同步组件 Props、Hooks 返回值、services 入参出参、manager 数据结构
版本同步	组件改动和文档改动放在同一个 PR 中，最不容易漂移
维护成本低	不需要通过 npm 包、submodule 或复制源码来拿类型
内部文档定位	当前主要是内部使用说明和 API 文档，不是独立营销官网

部署产物可以独立上线，但文档源码建议保留在当前仓库。

什么时候考虑拆出独立项目

满足以下条件时再考虑拆分：

• 文档服务多个仓库，不只 mbjia-tools。
• 非研发同学需要长期维护文案，需要独立权限。
• 公司统一文档门户要聚合多个组件库/SDK。
• 文档发布节奏完全独立于组件库。
• 需要接入复杂 Demo 平台，比如 Storybook、Ladle、截图服务、mock 后端。

目录约定

docs/
  index.md
  guide/          # 新手接入、安装、工程要求
  packages/       # 包级说明
  components/     # 组件使用说明
  hooks/          # Hooks API
  api/            # 数据结构、服务接口、事件协议
  maintain/       # 开发、发布、维护

页面维护规则

新增或修改组件时，按以下规则更新文档：

改动类型	必须更新
新增基础组件	components/basic/、packages/ui.md
新增业务组件	components/business/、packages/components.md
新增 Hook	hooks/、packages/hooks.md
新增服务接口	api/services.md
新增公共数据类型	api/data-structures.md
新增事件	api/events.md
上传流程变化	api/upload.md、components/business/every-where-upload.md

文档质量检查清单

每次新增或修改文档时，至少检查以下项目：

检查项	要求
源码依据	Props、回调、事件、数据结构必须来自当前仓库源码或现有业务文档，不确定就标注边界。
适用场景	说明什么时候使用，什么时候不建议使用。
使用示例	至少提供一个最小可复制示例。
发布摘要	有业务可感知变化时，更新 docs/data/release-notes.json。
效果/结构预览	基础 UI 给效果预览；复杂业务组件给结构预览和流程预览。
入参	Props、函数参数、接口参数要有字段表。
出参	回调、ref、接口返回值要有出参说明。
数据结构	公共模型要链接到 api/data-structures。
事件协议	涉及 eventBus 的组件必须列事件名、方向、说明。
前置条件	业务组件要说明登录态、接口权限、worker、环境配置等依赖。
自动校验	修改后执行 pnpm docs:check，检查导出覆盖和站内链接。
构建验证	修改后执行 pnpm docs:ci，同步版本、检查链接并构建。

单组件页面模板

# 组件名

一句话说明组件做什么。

## 组件定位

## 适用场景

## 效果预览

## 结构预览

复杂业务组件使用；基础 UI 可省略。

## 流程预览

涉及跨组件、接口、事件流时使用。

## 使用示例

## Props / 入参

## 出参 / 回调

## 数据结构

## 事件协议

## 依赖与前置条件

## 注意事项

页面体验要求

模块	要求
首屏	先让用户知道这个页面能解决什么问题。
预览	不使用粗糙 inline demo；优先使用 demo-card、structure-preview、flow-preview。
表格	字段表必须包含字段、类型、必填/默认值、说明；没有默认值时写 -。
跳转	常用前置条件、类型、事件尽量在本页给摘要；完整内容再链接到详情页。
文案	面向使用者，不写内部分析过程。

示例和预览策略

类型	策略
基础 UI	给静态效果预览、代码示例、Props 表
业务组件	给结构预览、流程图、最小代码示例、事件协议
Hooks	给函数签名、返回值、最小示例
services	给请求参数、返回数据、调用示例

业务组件不要强行做真实在线 Demo，除非已经准备好 mock 数据、登录态和接口环境。

构建与部署

本地开发：

pnpm docs:dev

构建：

pnpm docs:ci

构建产物：

docs/.vitepress/dist

部署时只需要把 dist 目录交给 Nginx、对象存储或公司静态服务。

pnpm docs:ci 会先从内部 Verdaccio 同步正式包和 alpha 包版本，再执行文档检查和 VitePress 构建。Cloudflare Pages 当前也应使用这条命令作为构建入口。

文档自动更新策略

当前推荐以下几种方式实现文档自动更新。

需要注意：当前文档站是静态站点，不能在 npm 包发布后自己修改线上 HTML。现在已经做到“构建时自动同步最新正式包和 alpha 包版本”；如果要做到发包后线上文档即时更新，必须由正式包和 alpha 包的发布流水线在发包成功后触发一次文档站构建和部署。

方式一：Gitee CI（推荐）

在仓库根目录创建 .gitee-ci.yml，在 push 到 main 分支时自动构建：

# .gitee-ci.yml
name: docs-build
on:
  push:
    branches: [main]
jobs:
  build-docs:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - uses: pnpm/action-setup@v2
        with:
          version: 8
      - run: pnpm install
      - run: pnpm docs:ci
      - run: |
          # 将 docs/.vitepress/dist 部署到静态服务
          # 具体命令取决于部署目标（Nginx、OSS 等）

方式二：Git Hook（轻量）

在 package.json 添加脚本，利用 Git Hook 在 push 前检查文档：

{
  "scripts": {
    "prepush": "pnpm docs:ci"
  }
}

配合 husky 或 simple-git-hooks 使用。

方式三：定时任务

在 CI 中配置定时触发（如每 5 分钟或每小时），自动拉取私库版本并构建新文档。这个方式不依赖发版流水线改造，但不是严格即时。

方式四：发版后触发文档部署（即时同步）

在正式包和 alpha 包的发布流水线最后增加一步：发包成功后调用文档站的部署 webhook 或平台 API，触发文档站重新构建。

DOCS_DEPLOY_HOOK_URL="https://..." pnpm docs:deploy-hook

发布链路建议如下：

发布正式包或 alpha 包 -> Verdaccio 出现新版本 -> 触发文档站部署 -> pnpm docs:ci -> 线上文档更新

这个方式才能保证仓库发布新版本后，线上文档尽快同步到最新版本。CI 里要把 DOCS_DEPLOY_HOOK_URL 配成密钥，并且只在 lerna publish 成功后执行；如果 hook 失败，包可能已经发布成功，可以单独重跑 pnpm docs:deploy-hook。

当前建议

由于文档目前和组件库源码在同一仓库，推荐使用方式一（CI 自动构建）加方式四（发版后触发文档部署）。main 分支推送负责同步源码文档，发版后部署负责同步 Verdaccio 上的正式包和 alpha 包版本。

构建环境要求：

• Node.js v22+
• pnpm v8+
• 能访问 http://verdaccio.atvideo.cc（同步正式包和 alpha 包版本时必须）

版本同步建议

推荐在组件发版前检查：

1. 包版本是否更新。
2. 新增导出是否已写入文档。
3. Props 或返回值是否变化。
4. 事件名是否变化。
5. 导出覆盖和站内链接是否通过。
6. 构建是否通过。

pnpm docs:ci

如果组件变化较大，建议在发版说明里附上对应文档链接。

多版本文档建议

当前文档站默认展示当前分支对应的最新文档。如果后续需要支持每个发布版本，可以在发版流程中增加一步：按 tag 构建文档，并把产物部署到固定版本目录。

建议约定：

项目	建议
版本路径	/versions/<package-version>/，例如 /versions/3.0.132/。
默认入口	/ 永远指向最新稳定版本。
历史版本	只修严重错误，不随最新源码回填行为说明。
发版检查	发包、打 tag、构建文档、部署版本目录应在同一条发布流程里完成。

如果暂时不做多版本部署，至少要保留 Git tag，让使用旧包版本的业务项目能回到对应源码和 docs/ 目录核对。