文档维护

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

单组件页面模板

# 组件名

一句话说明组件做什么。

## 组件定位

## 适用场景

## 效果预览

## 结构预览

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

## 流程预览

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

## 使用示例

## Props / 入参

## 出参 / 回调

## 数据结构

## 事件协议

## 依赖与前置条件

## 注意事项

页面体验要求

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

示例和预览策略

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

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

构建与部署

本地开发：

pnpm docs:dev

构建：

pnpm docs:check
pnpm docs:build

构建产物：

docs/.vitepress/dist

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

版本同步建议

推荐在组件发版前检查：

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

pnpm docs:check
pnpm docs:build

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