企业官网建设流程全解析

开源项目文档工具链：从 Markdown 到交互式 Playground 的自动化生成

一、文档的第一性原理：为什么 README 写得好但没人用你的 API

开源项目有一个残酷的定律：API 使用率 = 文档质量 × 上手速度。用户带着问题来到你的仓库，他会：先看 README 找到快速开始的命令；然后打开文档站找具体的 API 用法；最后在 Playground 中测试调用。

如果这三个环节的任意一个卡住了——README 没有安装命令、文档站没有搜索、Playground 打不开——用户就走了。文档不是附加品，是产品的一部分。

但维护文档非常耗时。API 改了要同步更新文档、示例代码过期了要修复、Playground 需要单独开发。这就是为什么文档需要自动化工具链——让文档跟随代码自动生成，让示例代码自动验证。

graph LR A[源代码 + JSDoc] --> B[TypeDoc 生成 API 文档] B --> C[VitePress 文档站] D[Markdown 文件] --> C C --> E[自动部署到 GitHub Pages] F[代码示例] --> G[Playground 组件] G --> C H[CI 检查] --> I{代码示例<br/>可运行?} I -->|是| J[通过] I -->|否| K[CI 失败] style K fill:#ff6b6b,color:#fff style J fill:#51cf66,color:#fff

二、文档工具链的三层架构：生成 → 展示 → 交互

Layer 1 — 自动生成 API 参考：TypeDoc（TypeScript）或 JSDoc 工具扫描代码中的类型定义和注释，自动生成 API 参考文档。这样当函数签名变化时，文档会自动更新。

Layer 2 — 文档站：VitePress 是 Vue 生态下的文档站框架，支持 Markdown + Vue 组件混写。它的热更新让写文档像写代码一样快。

Layer 3 — 交互式 Playground：用户在文档站中可以直接运行代码，立即看到效果。这比"复制示例代码 → 新建文件 → npm install → 运行"快 10 倍。

三、文档工具链的工程化配置

VitePress 配置（docs/.vitepress/config.ts）：

import { defineConfig } from 'vitepress'; export default defineConfig({ title: 'MyLib', description: '一个轻量级 AI 工具库', base: '/mylib/', themeConfig: { nav: [ { text: '指南', link: '/guide/' }, { text: 'API 参考', link: '/api/' }, { text: 'Playground', link: '/playground' }, ], sidebar: { '/guide/': [ { text: '快速开始', link: '/guide/getting-started' }, { text: '安装', link: '/guide/installation' }, { text: '基本用法', link: '/guide/basic-usage' }, { text: '高级配置', link: '/guide/advanced' }, ], '/api/': [ { text: '总览', link: '/api/' }, { text: 'Agent', link: '/api/agent' }, { text: 'Tool', link: '/api/tool' }, { text: 'Memory', link: '/api/memory' }, ], }, socialLinks: [ { icon: 'github', link: 'https://github.com/user/mylib' }, ], search: { provider: 'local', // 本地搜索，无需外部服务 }, }, });

API 文档自动生成（从 TypeScript 源码生成 API 参考）：

// package.json { "scripts": { "docs:api": "typedoc --out docs/api src/index.ts --plugin typedoc-plugin-markdown", "docs:dev": "vitepress dev docs", "docs:build": "vitepress build docs", "docs:preview": "vitepress preview docs" } }

TypeDoc 配置（typedoc.json）：

{ "entryPoints": ["src/index.ts"], "out": "docs/api", "plugin": ["typedoc-plugin-markdown"], "excludePrivate": true, "excludeProtected": true, "readme": "none" }

交互式 Playground（Vue3 组件）：

<!-- docs/.vitepress/theme/components/Playground.vue --> <script setup> import { ref, computed } from 'vue'; import { useData } from 'vitepress'; const code = ref(`// 试试修改这段代码 const agent = new Agent({ model: 'gpt-4o-mini', temperature: 0.3, }); const result = await agent.ask('Hello, world!'); console.log(result); `); const output = ref(''); const isRunning = ref(false); async function runCode() { isRunning.value = true; output.value = ''; try { // 使用 JavaScript sandbox 安全执行代码 const result = await evaluateInSandbox(code.value); output.value = JSON.stringify(result, null, 2); } catch (err) { output.value = `Error: ${err.message}`; } finally { isRunning.value = false; } } async function evaluateInSandbox(code) { // 实际实现使用 iframe 沙箱或 Web Worker // 这里简化为模拟 return new Promise(resolve => { setTimeout(() => resolve({ message: 'Hello from Agent!' }), 500); }); } </script> <template> <div class="playground"> <div class="editor"> <textarea v-model="code" rows="10" spellcheck="false" /> </div> <div class="controls"> <button @click="runCode" :disabled="isRunning"> {{ isRunning ? '运行中...' : '▶ 运行' }} </button> </div> <div class="output" v-if="output"> <pre>{{ output }}</pre> </div> </div> </template>

CI 中验证代码示例：

name: Check Examples on: pull_request: paths: - 'docs/**' - 'examples/**' jobs: check-examples: runs-on: ubuntu-latest steps: - uses: actions/checkout@v4 - uses: pnpm/action-setup@v2 - run: pnpm install # 提取文档中的所有代码块，检查是否可以编译 - name: Extract and typecheck examples run: | node scripts/check-docs-examples.js

文档示例检查脚本（scripts/check-docs-examples.js）：

const fs = require('fs'); const path = require('path'); const { execSync } = require('child_process'); function extractCodeBlocks(markdown) { const blocks = []; const regex = /```(?:typescript|ts|javascript|js)?\n([\s\S]*?)```/g; let match; while ((match = regex.exec(markdown)) !== null) { blocks.push(match[1]); } return blocks; } function checkExamples(docsDir) { const errors = []; function walk(dir) { for (const file of fs.readdirSync(dir)) { const fullPath = path.join(dir, file); if (fs.statSync(fullPath).isDirectory()) { walk(fullPath); } else if (file.endsWith('.md')) { const content = fs.readFileSync(fullPath, 'utf-8'); const blocks = extractCodeBlocks(content); for (let i = 0; i < blocks.length; i++) { try { // 写入临时文件并尝试编译 const tmpFile = `/tmp/example-${Date.now()}.ts`; fs.writeFileSync(tmpFile, blocks[i]); execSync(`npx tsc --noEmit ${tmpFile}`, { timeout: 10000 }); fs.unlinkSync(tmpFile); } catch (err) { errors.push(`${fullPath}: 代码块 ${i + 1} 编译失败 - ${err.message}`); } } } } } walk(docsDir); if (errors.length > 0) { console.error('以下文档示例代码无法编译：'); errors.forEach(e => console.error(` ❌ ${e}`)); process.exit(1); } console.log('✅ 所有文档示例代码编译通过'); } checkExamples('docs');

四、文档工程的投入产出

时间投入：VitePress 的初始配置约 1-2 小时。TypeDoc 的配置约 30 分钟。Playground 组件的开发约 4-8 小时（取决于交互复杂度）。总计约为 0.5-1.5 天。

持续维护：文档站本身几乎不需要维护。TypeDoc 自动生成的部分随代码自动更新。主要维护负担是指南类文档的手动更新。

不适用场景：

• 内部工具（只有 2-3 个同事使用）
• 原型阶段的实验性项目（API 频繁变更）
• CLI 工具（更适合用--help和 man page）

五、总结

开源项目文档工具链的核心是：TypeDoc 自动生成 API 参考 + VitePress 构建文档站 + Playground 降低上手门槛。CI 中自动验证代码示例确保文档和代码保持同步。

落地路径：先用 VitePress 搭一个简单的文档站（README + 安装指南）；然后接入 TypeDoc 自动生成 API 文档；最后加一个最小化的 Playground 让用户即时体验。

少即是多。文档不需要花哨的设计——清晰的导航、可搜索的 API 参考、能跑的代码示例，这三点做好了，你的文档质量已经超越了 90% 的开源项目。