文档生成与同步

概述

当 Registry 能力开发完成后，需要生成站点文档并同步注册表，以便内部与外部项目都能获取最新内容。本指南介绍如何使用 Bun 脚本完成文档生成、注册表同步以及常见问题排查。

文档生成

1. 运行生成脚本

bun run registry:gen-doc <name> --type <ui|block|hook|item>

--type 默认为 ui，可选值包括 ui、block、hook、item。
建议始终显式声明类型，避免目录命名差异导致的生成错误。

常用示例：

bun run registry:gen-doc button --type ui
bun run registry:gen-doc gh-stargazers-button --type block
bun run registry:gen-doc use-cancelable-swr --type hook
bun run registry:gen-doc make-api-request --type item

2. 生成逻辑

脚本会根据类型执行对应的生成策略：

类型	源文件	注入内容	输出位置
`ui` / `block`	`registry/ssp/<type>/<name>/README.mdx` `registry/ssp/<type>/<name>/example.tsx`	将 `example.tsx` 代码注入 `_code_autogenerated_` 占位符	`content/docs/ssp/(<type>)/<name>.mdx`
`hook`	`registry/ssp/hook/<name>/README.mdx` `registry/ssp/hook/<name>/index.ts`	将 `index.ts` 代码注入 `_code_autogenerated_`	`content/docs/ssp/(hook)/<name>.mdx`
`item`	`registry/ssp/item/<name>/README.mdx`	README 原样复制（无代码注入）	`content/docs/ssp/(item)/<name>.mdx`

3. 文档目录结构

生成的文档会落在 content/docs/ssp 目录下，按能力类型分组：

content/docs/ssp/
├── (ui)/                # UI 组件文档
├── (block)/             # Block 组件文档
├── (hook)/              # Hook 文档
└── (item)/              # 工程能力文档

4. 示例代码注入

对需要注入示例代码的类型（UI、Block、Hook），请在 README 中保留占位符：

<ExampleCode content={`_code_autogenerated_`}>
  <Example />
</ExampleCode>

脚本会将示例源文件内容写入 content 属性，生成后的文档将直接展示真实代码。对于 Item 类型，README 会直接复制，不会执行代码注入。

注册表同步

1. 执行同步

bun run registry:sync

2. 同步内容

同步脚本会：

遍历 registry/ssp/ 目录，读取各模块的 index.json。
校验配置是否符合 registry-item schema。
更新仓库根目录的 registry.json。
在 public/r/ 下生成对应的公开 JSON 文件。

3. 输出文件结构

registry.json              # 主注册表文件
public/r/
├── button.json            # UI 组件条目
├── gh-stargazers-button.json
├── use-cancelable-swr.json
├── make-api-request.json
└── ...                    # 其它能力输出

4. 可选：构建验证

同步完成后，可执行构建脚本确认所有条目能被正确打包：

bun run registry:build

完整工作流程

开发阶段

# 1. 初始化能力目录
bun run registry:create <name> --type <ui|block|hook|item>

# 2. 补充源码 / 模板文件
# 编辑 registry/ssp/<type>/<name>/ 下的 index.ts(x)、example.tsx、README.mdx 等

发布阶段

# 1. 生成站点文档
bun run registry:gen-doc <name> --type <ui|block|hook|item>

# 2. 同步注册表索引
bun run registry:sync

# 3. 可选：构建与校验
bun run registry:build

# 4. 运行 Biome 确保格式一致
bun run lint

验证结果

# 检查生成的文档（示例：UI 组件）
cat content/docs/ssp/(ui)/<name>.mdx

# 检查公开注册表文件
cat public/r/<name>.json

# 检查主注册表是否包含条目
grep "<name>" registry.json

常见问题

文档生成失败

常见原因：

目标目录或 README 文件缺失。
示例文件缺失（UI/Block 需要 example.tsx，Hook 需要 index.ts）。
名称与目录结构不匹配（kebab-case、hook 前缀）。

排查建议：

ls registry/ssp/<type>/<name>/
# 确保包含 README、示例/源码文件

# 检查 README 中是否包含占位符
grep "_code_autogenerated_" registry/ssp/<type>/<name>/README.mdx

注册表同步失败

常见原因：

index.json 字段缺失或路径配置错误。
dependencies 中的包尚未安装。
JSON 格式不合法。

排查建议：

# 使用 Biome 检查 JSON 结构
bunx biome check registry/ssp/<type>/<name>/index.json

# 安装缺失依赖
bun add <package-name>

示例代码未注入

常见原因：

_code_autogenerated_ 被误删或命名不正确。
示例文件无法读取（语法错误或路径不匹配）。

排查建议：

grep "_code_autogenerated_" registry/ssp/<type>/<name>/README.mdx
bunx biome check registry/ssp/<type>/<name>/example.tsx

脚本参数

registry:gen-doc

bun run registry:gen-doc <name> --type <ui|block|hook|item>

未显式传入 --type 时默认处理为 UI 组件。
Hook 名称会自动校验 use- 前缀；Item 会直接复制 README。

registry:sync

bun run registry:sync

无需参数，会自动扫描 registry/ssp/ 下的所有能力模块。

下一步

完成文档生成与注册表同步后：

本地验证：在站点中预览新增文档、确认示例渲染正确。
提交变更：确认 registry.json、public/r/、content/docs/ssp/ 等文件已经更新并提交到 Git。
创建 PR：在描述中附带能力名称、脚本执行结果与测试方式。
等待 Review：根据反馈补充文档或示例。
合并发布：合并后将自动构建并发布最新的 Registry。