@composy/docs-generator

@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，也会自动发现同名的 .ts、.mjs、.mts、.cjs 和 .cts 配置。CLI 仍兼容历史文件名 docs-generator.config.js 及其对应扩展名，便于旧项目平滑迁移。显式传入 -c 时也支持自定义 JavaScript/TypeScript 配置路径。

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/' },
    ],
  },
})

TypeScript 配置可以直接使用 ESM 导出，CLI 会通过 Vite 的配置加载器编译后读取：

import { defineConfig, markdownPlugin } from '@composy/docs-generator'

export default defineConfig({
  sourceDir: './src',
  outputDir: './docs',
  plugins: [markdownPlugin({ include: '**/*.md' })],
  site: { title: 'TypeScript Docs' },
})

解析插件的 include/exclude glob 可以写成相对于 sourceDir 的路径，也兼容以项目根目录为基准的写法；这样 src/components/**/*.vue 与 components/**/*.vue 都可以用于 sourceDir: './src'。

增量缓存与平台方式兼容

启用 parser.incremental 并设置 cacheDir 后，缓存复用不仅检查文件时间和内容，还会根据以下内容建立有效范围指纹：

• sourceDir 的绝对路径以及生效的 include/exclude glob 配置；
• 已注册插件的 name、version、dependencies 以及 config 的 SHA-256 指纹。

当插件、插件配置、文件扫描范围或源目录发生变化时，旧缓存会自动作废，避免错误复用旧的 DocNode。缓存格式升级到当前版本后，旧的 1.1.x 缓存也会先失效；新源文件仍会继续通过文件 hash 做细粒度变更检测。

TypeDoc 插件在 Windows 上会将 tsconfig、entryPoints 和 exclude 中的路径转换为 POSIX / 分隔符，并默认使用 expand entry-point strategy。因此传入源码目录时可以递归发现目录下的 TypeScript 文件，不会触发 TypeDoc 的反斜杠 glob 错误。测试和自定义插件产生的临时目录应放在系统临时目录或项目约定的 cache 目录中，不应提交到源码仓库。

CLI 命令

常用参数：

• -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。ESLint 与 TypeScript 主配置分别位于 .ldesign/eslint.config.js 和 .ldesign/tsconfig.json；根目录配置文件保留为兼容入口。

构建规则：

• 覆盖 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 打包配置
.ldesign/eslint.config.js ESLint 主配置
.ldesign/tsconfig.json   TypeScript 主配置
eslint.config.js         ESLint 兼容入口
tsconfig.json            TypeScript 兼容入口

常见场景

• 为组件库生成 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