跨端组件文档一键生成器（cross-docgen-cli）

跨端组件文档一键生成器 是一个面向前端组件库的 Node.js CLI 工具，专注解决“组件库文档维护累、易过期”的痛点。

它通过 扫描组件代码 → 解析 AST → 生成结构化 Markdown 文档 → 实时监听同步，让你在不写/少写文档的前提下，组件文档始终与代码保持同步。

适用于 React / Vue3 组件库，特别适合个人开发者和中小团队。

特性

• 一键生成：扫描组件目录，自动为每个组件生成 Markdown 文档
• 跨框架支持：支持 React（.tsx/.jsx）和 Vue3（.vue/.ts，MVP）
• 结构化输出：组件说明 / 元信息 / Props / 事件 / 插槽 / 示例
• 实时同步：监听组件文件变更，自动重新生成文档
• 零配置上手：默认参数即可跑通，支持命令行参数自定义
• 可定制模板：支持自定义 Markdown 模板（如加团队 Logo、规范说明）

安装

假设包名为 cross-docgen-cli，如采用作用域请替换为你自己的包名。

一次性使用（推荐体验）

无需安装，直接使用 npx：

npx cross-docgen-cli --dir src/components --out docs/components --framework auto

安装到项目中

npm install -D cross-docgen-cli
# 或 pnpm / yarn

安装后可以直接使用全局命令：

npx doc-gen --dir src/components --out docs/components --framework auto

也可以在 package.json 中配置脚本：

{
  "scripts": {
    "doc:gen": "doc-gen --dir src/components --out docs/components --framework auto",
    "doc:watch": "doc-gen --dir src/components --out docs/components --framework auto --watch"
  }
}

然后：

npm run doc:gen
npm run doc:watch

快速上手

假设你的组件库结构类似：

src/
  components/
    Button.tsx
    Modal.vue
docs/
  components/   # 想要把文档输出在这里

在项目根目录执行：

doc-gen --dir src/components --out docs/components --framework auto

执行完成后，将在 docs/components 下生成与 src/components 目录结构对应的 .md 文档，例如：

docs/
  components/
    Button.md
    Modal.md

如果希望文档随着组件改动实时更新：

doc-gen --dir src/components --out docs/components --framework auto --watch

命令行参数

doc-gen [options]

可用参数：

• -d, --dir <dir>
  组件源代码目录
  默认值：src/components

• -o, --out <outDir>
  文档输出目录
  默认值：docs/components

• -f, --framework <framework>
  组件框架类型
  可选值：react | vue | auto
  默认值：auto（按文件扩展名自动区分）

• -t, --template <path>
  自定义 Markdown 模板路径（可插入变量，见下文）

• -w, --watch
  监听组件目录文件变化，自动重新生成文档

示例：

# 只生成一次文档（React 项目）
doc-gen --dir src/components --out docs/components --framework react

# Vue 项目，并使用自定义模板
doc-gen --dir src/components --out docs/components --framework vue --template docs/template.md

# 实时监听组件变化
doc-gen --dir src/components --out docs/components --framework auto --watch

文档结构示例

生成的 Markdown 文档大致结构如下（示例）：

# Button

按钮组件，用于触发操作。

## 元信息

- **来源文件**: `src/components/Button.tsx`
- **框架**: `react`

## Props

| 名称 | 类型 | 必填 | 默认值 | 说明 |
| ---- | ---- | ---- | ------ | ---- |
| `type` | `primary \| default` | ✅ | `primary` | 按钮类型 |
| `disabled` | `boolean` |  | `false` | 是否禁用 |

## 事件

| 名称 | 参数类型 | 说明 |
| ---- | -------- | ---- |
| `onClick` | `(event: MouseEvent) => void` | 点击时触发 |

## 插槽

_暂无解析到插槽_

## 示例

```tsx
<Button type="primary" onClick={handleClick}>
  提交
</Button>

> 当前 MVP 中，Props / 事件 / 插槽的解析还是简化版本，后续会逐步增强 AST 解析逻辑。

---

## 自定义模板

你可以传入 `--template` 指定一个 Markdown 模板，用于统一文档外壳（如 Logo、规范、统一说明等）。

模板文件支持以下占位符：

- `{{CONTENT}}`：生成的默认文档内容（如上所示的整段内容）
- `{{NAME}}`：组件名称
- `{{DESCRIPTION}}`：组件描述（从注释或 SFC 顶部注释解析）
- `{{FRAMEWORK}}`：组件框架（`react` / `vue`）
- `{{FILE_PATH}}`：组件源文件路径

示例模板 `docs/template.md`：

```markdown
# 我们的组件库

> 本文档由 cross-docgen-cli 自动生成，请勿手动修改组件章节内容。

---

## 组件：{{NAME}}

{{CONTENT}}

---

_自动生成自 {{FILE_PATH}}_

使用方式：

doc-gen --dir src/components --out docs/components --framework auto --template docs/template.md

工作原理（简要）

1. 使用 glob 扫描指定目录中的组件文件：
   • React：**/*.{tsx,jsx}
   • Vue：**/*.{vue,ts}
2. 通过 AST 或简单规则提取：
   • 组件名称（优先导出名称，其次文件名）
   • 描述（文件顶部注释 / SFC 注释）
   • Props / 事件 / 插槽（MVP 阶段部分占位，后续迭代增强）
3. 将结构化数据渲染为 Markdown（默认模板或自定义模板）
4. 如果开启 --watch，使用 chokidar 监听组件目录变更，变更后自动重新生成整个文档目录。

路线图

• [ ] React：基于 TS 类型 / propTypes 深度解析 Props & 默认值
• [ ] Vue3：通过 defineProps / defineEmits / slots 精确解析
• [ ] 支持更多框架（Svelte / Solid 等）
• [ ] 支持 HTML 文档、站点导航与搜索
• [ ] 提供一键部署到 GitHub Pages / Vercel 的脚本
• [ ] 支持 .docgenrc / 插件机制，扩展解析与生成能力

许可证

MIT