@composy/docs-generator

@composy/docs-generator 是一个面向组件库、设计系统和业务项目的文档生成工具。它将 TypeScript API、Vue/React 组件、Markdown 文档统一解析为 DocNode[] 中间结构，再通过主题、模板和运行时能力生成可开发、可预览、可构建、可发布的文档站点。

English README

核心特性

• 统一数据模型：所有输入最终都会归一化为 DocNode[]，便于后续转换、导航构建和模板渲染。
• 多源文档解析：内置 TypeDoc、Vue 组件、React 组件、Markdown 等解析插件。
• 站点生成能力：同时支持 generate、dev、build、serve/preview 等完整工作流。
• 运行时支持：内置 Vue 3 + Vue Router + Vite 的 SPA 运行时与开发服务器。
• 模板与主题扩展：支持 EJS、Handlebars、Nunjucks 适配器以及自定义主题目录。
• Markdown 增强：支持锚点、外链、代码组、行高亮、行号、Shiki 高亮、Emoji、导入代码片段等。
• 可选功能模块：支持搜索、评论、PWA、i18n、分析统计、版本管理、图片优化等能力。
• 工程可验证：已接入 TypeScript、Vitest、@antfu/eslint-config 和 @composy/pack 多入口构建链路。

安装

pnpm add -D @composy/docs-generator

或：

npm i -D @composy/docs-generator

环境要求：

• Node.js >= 18
• 推荐使用 pnpm

快速开始

1. 初始化配置文件：

npx ldesign-docs init

2. 在项目中准备源码与 Markdown 文档目录，例如：

src/
  components/
  api/
  guide/

3. 启动开发服务器：

npx ldesign-docs dev

4. 生成文档输出：

npx ldesign-docs generate

5. 构建生产版本：

npx ldesign-docs build --mode hybrid

配置文件

默认配置文件名为 docsGenerator.config.js。CLI 仍兼容历史文件名 docs-generator.config.js，便于旧项目平滑迁移。

推荐使用 CommonJS 配置，兼容性最好：

const {
  defineConfig,
  markdownPlugin,
  typedocPlugin,
  vueComponentPlugin,
} = require('@composy/docs-generator')

module.exports = defineConfig({
  sourceDir: './src',
  outputDir: './docs',
  cacheDir: '.cache/docs-generator',
  logLevel: 'info',
  parser: {
    include: ['**/*.{ts,tsx,js,jsx,vue,md}'],
    exclude: ['**/node_modules/**', '**/dist/**', '**/build/**'],
    incremental: true,
    concurrency: 4,
  },
  plugins: [
    typedocPlugin({
      tsconfig: './tsconfig.json',
      entryPoints: ['./src/index.ts'],
    }),
    vueComponentPlugin({
      include: '**/*.vue',
      exclude: '**/node_modules/**',
    }),
    markdownPlugin({
      include: '**/*.md',
      exclude: '**/node_modules/**',
    }),
  ],
  site: {
    title: 'LDesign Docs',
    description: '自动生成的设计系统文档站点',
    lang: 'zh-CN',
    base: '/',
    darkMode: true,
  },
  theme: {
    name: 'default',
  },
  navigation: {
    sidebar: 'auto',
    topbar: [
      { text: '首页', link: '/' },
      { text: '指南', link: '/guide/' },
      { text: 'API', link: '/api/' },
      { text: '组件', link: '/components/' },
    ],
  },
})

CLI 命令

| 命令 | 说明 | | ---------------------------------------------- | -------------------------- | | ldesign-docs init | 初始化默认配置文件 | | ldesign-docs generate | 解析源码并输出文档站点 | | ldesign-docs build --mode <spa\|ssg\|hybrid> | 构建生产产物 | | ldesign-docs dev | 启动基于 Vite 的开发服务器 | | ldesign-docs serve --dir ./docs | 预览构建后的文档站点 | | ldesign-docs clean --output ./docs | 清空输出目录 |

常用参数：

• -c, --config <path>：指定配置文件路径
• -s, --source <dir>：覆盖 sourceDir
• -o, --output <dir>：覆盖 outputDir
• -w, --watch：开启监听模式
• --log-level <level>：设置日志级别

架构概览

当前源码按职责分为三层：

• src/engine/
  • 文档生成主流程、插件管理、解析系统、日志与错误处理
  • 典型模块：DocsGenerator、ParserSystem、PluginManager
• src/site/
  • 静态站点生成、模板引擎、主题系统、构建优化
  • 典型模块：StaticSiteEngine、TemplateEngine、ThemeManager
• src/runtime/
  • 开发时运行时、Vite 插件、前端应用、路由数据
  • 典型模块：routeData、devServer、app/router

其余能力层：

• src/config/：配置校验、Markdown 配置解析、Vite 配置扩展
• src/plugins/：解析器、增强、第三方集成、Playground 相关插件
• src/features/：搜索、PWA、评论、导航、版本、分析等附加能力
• src/markdown/：Markdown-it 插件与增强能力
• src/types/：公共类型与环境声明
• src/utils/：文件、模板、路径、并行执行等基础工具

工作流说明

1. 解析阶段

ParserSystem 会收集源文件，并将各类输入交给对应插件处理：

• typedocPlugin：提取 TypeScript API 信息
• vueComponentPlugin：解析 Vue SFC 组件
• reactComponentPlugin：解析 React 组件
• markdownPlugin：处理 Markdown 文档

最终统一产出 DocNode[]。

2. 转换与增强阶段

插件钩子可在 beforeParse / parse / afterParse / beforeTransform / transform / afterTransform 等节点介入，对文档元数据、导航、搜索索引或扩展内容进行加工。

3. 站点生成阶段

StaticSiteEngine 与 TemplateEngine 根据站点配置、主题与导航数据生成 HTML、资源文件和运行时注入数据。

4. 开发运行时阶段

runtime/ 下的 Vite 插件会把路由数据、文档数据和配置注入到前端 Vue 应用中，支持本地预览与 HMR。

5. 构建优化阶段

site/optimization/ 中的模块可执行资源压缩、关键 CSS 提取、代码切分、图片优化、预取资源生成等操作。

插件与扩展

内置插件主要分为四类：

• src/plugins/parsers/
  • typedocPlugin
  • vueComponentPlugin
  • reactComponentPlugin
  • markdownPlugin
• src/plugins/enhancements/
  • Mermaid、KaTeX、媒体、代码差异对比等增强插件
• src/plugins/integrations/
  • Algolia、CodePen、CodeSandbox、StackBlitz 等外部平台集成
• src/plugins/playground/
  • 示例控件生成与 Playground 支持

如果需要自定义扩展，优先沿用 DocsPlugin 接口和现有钩子生命周期，而不是在 DocsGenerator 主流程里硬编码业务逻辑。

构建与发布

本包当前使用 @composy/pack（来自 tools/tsup-config）进行统一打包，构建配置位于 .ldesign/pack.config.ts。

构建规则：

• 覆盖 src/**/*.ts
• 排除 .d.ts、测试文件和 src/bin/cli.ts 的普通库构建
• 同时输出 ESM、CJS 和 d.ts
• CLI 入口单独构建并保留 shebang
• 复制运行时页面与模板资源到 dist/

产物结构示例：

dist/
  index.js
  index.cjs
  index.d.ts
  engine/
  runtime/
  site/
  templates/

这意味着：

• 可以直接从包根导入
• 也可以按子路径导入，例如 @composy/docs-generator/runtime
• 所有主要 TS 入口都会生成对应的声明文件

开发与验证

常用命令：

pnpm lint:check
pnpm typecheck
pnpm test:run
pnpm build

辅助命令：

pnpm format
pnpm build:inspect
pnpm test:coverage

当前仓库已验证：

• pnpm lint:check
• pnpm typecheck
• pnpm test:run
• pnpm build

目录结构

bin/                    CLI 启动入口
docs/                   项目文档
src/
  cli/                  CLI 命令实现
  config/               配置解析与校验
  engine/               解析与生成主引擎
  features/             搜索、PWA、评论等增强能力
  markdown/             Markdown 增强插件
  plugins/              插件实现
  runtime/              开发运行时与 Vite 集成
  site/                 静态站点生成与主题系统
  templates/            运行时模板组件
  types/                类型与环境声明
  utils/                通用工具函数
templates/              默认主题与静态模板资源
.ldesign/pack.config.ts 打包配置
eslint.config.js        ESLint 配置

常见场景

• 为组件库生成 API 文档与组件说明页
• 为设计系统生成可交互的文档站点
• 为业务项目搭建统一的 Markdown + API 混合文档门户
• 在 monorepo 中复用统一主题、统一导航和统一构建验证链路

相关文档

• 快速开始
• 配置参考
• API 参考
• 插件开发
• 主题开发
• 迁移指南
• 性能优化
• 最佳实践
• 架构说明
• 贡献指南

CLI 诊断与性能参数

新增的诊断命令和解析参数适合接入 CI、脚本和本地排障：

ldesign-docs doctor
ldesign-docs inspect
ldesign-docs generate --dry-run --log-level warn

• doctor：检查配置文件、目录、插件、解析结果和警告；配合 --json 可输出结构化结果。
• inspect：输出最终配置、插件顺序、主题、缓存目录和解析器参数。
• --dry-run：仅执行解析和转换，不写入输出目录，适合提交前快速验证。
• --concurrency <number>：覆盖解析并发数。
• --no-incremental：临时禁用增量解析缓存，便于排查缓存命中问题。

clean 默认拒绝清理当前工作目录或当前目录之外的路径；确实需要清理外部输出目录时必须显式传入 --force。

通过 @composy/cli 统一接入

接入类型：bin 统一命令：ldesign docs 命令别名：docs-generator 包内原生 bin：ldesign-docs 当前包通过独立 bin 接入，统一命令会转发到包自身 CLI。

pnpm add -D @composy/cli
ldesign docs --help
ldesign tools run docs-generator --help