## 前言上一篇给组件库结合 [Iconify](https://link.juejin.cn/?target=https%3A%2F%2Ficonify.design%2F "https://iconify.design/") 实现了纯 CSS 图标，本篇使用 `VitePress` 搭建组件库文档。
代码仓：[gitee](https://link.juejin.cn/?target=https%3A%2F%2Fgitee.com%2Fhit-point%2Fhp-ui%2Ftree%2Ffeature_five "https://gitee.com/hit-point/hp-ui/tree/feature_seven") ## 初始化文档工程安装 `VitePress`。 ```bash pnpm --filter @hpui/docs i -D vitepress ``` 将 `docs/` 作为根目录 `Project Root`(参考：[VitePress - 根目录](https://link.juejin.cn?target=https%3A%2F%2Fvitepress.dev%2Fguide%2Frouting%23root-and-source-directory "https://vitepress.dev/guide/routing#root-and-source-directory"))，则 `VitePress` 会固定读取 `docs/.vitepress/config.mts`(`/.vitepress/config.mts`) 作为配置文件。 ```ts // docs/.vitepress/config.mts import { defineConfig } from 'vitepress' // 配置参考：https://vitepress.dev/reference/site-config export default defineConfig({ title: "HpUI", description: "Vue3 组件库", themeConfig: {} }) ``` 在 `package.json` 中配置启动脚本时(参考：[VitePress CLI](https://link.juejin.cn/?target=https%3A%2F%2Fvitepress.dev%2Freference%2Fcli "https://vitepress.dev/reference/cli"))，要注意将 `Project Root` (`docs/`，相对路径为 `.`)指定为 `VitePress` 工作目录： ```json { "name": "@hpui/docs", "private": true, "scripts": { "dev": "vitepress dev . --host", "build": "vitepress build .", "preview": "vitepress preview . --host" }, "devDependencies": { "vitepress": "^1.3.4" } } ``` `docs/index.md`(`/index.md`) 将作为首页 markdown 文件。 ```md --- # VitePress 支持在 markdown 中通过 Frontmatter 写 yaml 配置，设置页面的主题样式 # https://vitepress.dev/reference/frontmatter-config#frontmatter-config # VitePress 默认主题的首页模板：https://vitepress.dev/reference/default-theme-layout#home-layout layout: home title: HpUI hero: name: HpUI text: Vue3 组件库 tagline: 从 0 到 1 搭建 Vue 组件库 image: src: /logo.svg alt: Hp actions: - theme: brand text: 指南 - theme: brand text: 组件 - theme: brand text: API 文档 - theme: brand text: 演练场 - theme: alt text: Gitee --- ``` `public` 静态文件里的 `logo` 用 `vue` 的即可。运行一下组件库文档。 ```bash pnpm --filter @hpui/docs run dev ``` ![image.png](https://p9-xtjj-sign.byteimg.com/tos-cn-i-73owjymdk6/9be14334aa004c5c86726794842a795b~tplv-73owjymdk6-jj-mark-v1:0:0:0:0:5o6Y6YeR5oqA5pyv56S-5Yy6IEAg5oiR6KGA5p2h5ZGiODEw:q75.awebp?rk3s=f64ab15b&x-expires=1760658325&x-signature=ci30tp215OUtO52cLrZR5Fg7BZQ%3D) 在 `docs` 目录下建立 `.gitignore` 文件忽略缓存目录。 ```diff # docs/.gitignore /.vitepress/cache ``` ## 文档路由接下来，我们给首页配置跳转路由。 ```diff --- # VitePress 支持在 markdown 中通过 Frontmatter 写 yaml 配置，设置页面的主题样式 # https://vitepress.dev/reference/frontmatter-config#frontmatter-config # VitePress 默认主题的首页模板：https://vitepress.dev/reference/default-theme-layout#home-layout layout: home title: HpUI hero: name: HpUI text: Vue3 组件库 tagline: 从 0 到 1 搭建 Vue 组件库 image: src: /logo.svg alt: Hp actions: - theme: brand text: 指南 link: /guide/ - theme: brand text: 组件 link: /components/ - theme: brand text: API 文档 link: /api/ - theme: brand text: 演练场 link: /playground - theme: alt text: Gitee link: https://gitee.com/hit-point/hp-ui --- ``` 我们根据首页里的 `link` 来建立路由文件夹，里面先存放 `index.md` 。同时在 `docs/.vitepress/config.mts` 中配置标题。 ```ts // docs/.vitepress/config.mts import { defineConfig } from 'vitepress' // 配置参考：https://vitepress.dev/reference/site-config export default defineConfig({ title: "HpUI", description: "Vue3 组件库", themeConfig: { // 参考：https://vitepress.dev/reference/default-theme-nav#navigation-links nav: [ { text: '指南', link: '/guide/' }, { text: '组件', link: '/components/' }, { text: 'API', link: '/api/' }, { text: '演练场', link: '/playground' }, ], } }) ``` 在本地环境里测试一下。 ![动画.gif](https://p9-xtjj-sign.byteimg.com/tos-cn-i-73owjymdk6/b49ab5df8a44432098423026cdc8111b~tplv-73owjymdk6-jj-mark-v1:0:0:0:0:5o6Y6YeR5oqA5pyv56S-5Yy6IEAg5oiR6KGA5p2h5ZGiODEw:q75.awebp?rk3s=f64ab15b&x-expires=1760658325&x-signature=15AES%2FgRxhiqiCFDvxYVqdvsv3I%3D) 接下来我们根据 `VitePress` 官网，配置默认主题的[Sidebar](https://link.juejin.cn/?target=https%3A%2F%2Fvitepress.dev%2Freference%2Fdefault-theme-sidebar%23multiple-sidebars "https://vitepress.dev/reference/default-theme-sidebar#multiple-sidebars")。 ```ts // docs/.vitepress/config.mts import { defineConfig } from 'vitepress' // 配置参考：https://vitepress.dev/reference/site-config export default defineConfig({ title: "HpUI", description: "Vue3 组件库", themeConfig: { // 参考：https://vitepress.dev/reference/default-theme-nav#navigation-links nav: [ { text: '指南', link: '/guide/' }, { text: '组件', link: '/components/' }, { text: 'API', link: '/api/' }, { text: '演练场', link: '/playground' }, ], // 参考：https://vitepress.dev/reference/default-theme-sidebar#multiple-sidebars sidebar: { // 指南部分的章节导航 '/guide/': [ { text: '指引', items: [ { text: '组件库介绍', link: '/guide/' }, { text: '快速开始', link: '/guide/quick-start' }, ], }, ], // 组件部分的章节导航 '/components/': [ { text: '组件', items: [ { text: 'Button 按钮', link: '/components/button' }, ], }, ] } }, }) ``` ![动画.gif](https://p9-xtjj-sign.byteimg.com/tos-cn-i-73owjymdk6/828eb40e8cea42ada0d84a5c2421baa4~tplv-73owjymdk6-jj-mark-v1:0:0:0:0:5o6Y6YeR5oqA5pyv56S-5Yy6IEAg5oiR6KGA5p2h5ZGiODEw:q75.awebp?rk3s=f64ab15b&x-expires=1760658325&x-signature=VJAjTe3Ia9UJXr%2FxF3tCzV7V1bo%3D) ## 组件用例展示建立 `docs/example` 目录来存放我们的组件用例。先引入组件库主包的依赖。 ```bash pnpm --filter @hpui/docs i -S --workspace @hpui/ui ``` 将之前编写的 `button` 示例放进 `docs/example/button/index.vue` 里面。 ```vue // docs/example/button/index.vue ``` 接下来设置好 `tsconfig.json` 确保类型不报错。 ```json // docs/tsconfig.json { // 集成基础配置 "extends": "../tsconfig.base.json", "compilerOptions": { "baseUrl": ".", "lib": ["ESNext", "DOM", "DOM.Iterable"], "types": [], // 因为 baseUrl 改变了，基础配置中的 paths 也需要一并重写 "paths": { // 将 @hpui/xxx 内部依赖定位到源码路径 "@hpui/*": ["../packages/*/src"] } }, "include": [ // 文档应用会引用其他子模块的源码，因此都要包含到 include 中 "../packages/*/src", ".vitepress/**/*", ".vitepress/**/*.md", // example 目录存放用例代码 "example/**/*", // 脚本目录，之后会涉及 "scripts/**/*" ], "exclude": ["**/dist", "**/cache"] } ``` 按照之前 `example` 里面的配置建立 `vite.config.mts` 文件。 ```ts // docs/vite.config.mts import { defineConfig } from 'vite'; import { join } from 'node:path'; import unocss from 'unocss/vite'; export default defineConfig({ plugins: [ // 应用组件库的 unocss 预设，配置文件在根目录的 uno.config.ts // 集成 UnoCss 方便我们编写组件用例，或者实现 VitePress 专用组件 unocss(), ], resolve: { alias: [ { // 将 @hpui/xxx 内部依赖定位到源码路径 find: /^@hpui\/(.+)$/, replacement: join(__dirname, '..', 'packages', '$1', 'src'), }, ], }, }); ``` 按照文档 [VitePress - 拓展默认主题](https://link.juejin.cn/?target=https%3A%2F%2Fvitepress.dev%2Fguide%2Fextending-default-theme "https://vitepress.dev/guide/extending-default-theme") 中的说明，建立 `docs/.vitepress/theme/index.ts` 文件。关于这个文件，我的理解是类似项目里的 `main.ts` 文件。 ```ts // docs/.vitepress/theme/index.ts import DefaultTheme from 'vitepress/theme'; import { EnhanceAppContext } from 'vitepress'; import { Theme } from '@hpui/ui'; // 应用组件库的 unocss 预设，配置文件在根目录的 uno.config.ts import 'virtual:uno.css'; export default { ...DefaultTheme, enhanceApp(ctx: EnhanceAppContext) { DefaultTheme.enhanceApp(ctx); const { app } = ctx; // 应用组件库提供的主题插件 app.use(Theme); // 注册其他插件、全局组件、provide... }, }; ``` 在用例展示文档 `docs/components/button.md` 中引入我们之前编写的 `button` 用例。 ```md # Button 按钮常用的操作按钮。 ## 基础用法基础的按钮用法。 <<< ../example/button/index.vue ## Button API ``` 到文档里看看效果。 ![动画.gif](https://p9-xtjj-sign.byteimg.com/tos-cn-i-73owjymdk6/9d6e642fec354781b72c9079019dd838~tplv-73owjymdk6-jj-mark-v1:0:0:0:0:5o6Y6YeR5oqA5pyv56S-5Yy6IEAg5oiR6KGA5p2h5ZGiODEw:q75.awebp?rk3s=f64ab15b&x-expires=1760658325&x-signature=C97P5y1Af0GsdJaHeAjutnIHLJA%3D) 到这里不管是修改用例还是源码，都可以做到实时热更新。接下来我们要对这个页面做一个优化，让它更符合我们平时看到的组件库风格。 * 给整个展示区域添加边框； * 源码展示部分支持显示和隐藏； * 为用例相关的更多操作提供拓展空间。建立 `docs/.vitepress/components` 目录来存放 `VitePress` 文档功能相关的组件： ``` 📦.vitepress ┣ 📂components ┃ ┣ 📜ShowArea.vue ┃ ┗ 📜index.ts ┣ 📂theme ┃ ┗ 📜index.ts ┗ 📜config.mts ``` 建立 `docs/.eslintignore` 文件。 ``` # docs/.eslintignore # eslint 会自动忽略 . 开头的路径或文件，必须强行指定放开 !.vitepress # 产物和缓存依然要忽略 .vitepress/dist .vitepress/cache ``` 编写 `ShowArea.vue` 代码。 ``` ``` ``` // docs/.vitepress/components/index.ts import ShowArea from './ShowArea.vue'; export { ShowArea, }; ``` 到这一步，我们的代码会有两个规范报错： ![image.png](https://p9-xtjj-sign.byteimg.com/tos-cn-i-73owjymdk6/b37c87dc6fcc4107b5e3a490cb5a34f1~tplv-73owjymdk6-jj-mark-v1:0:0:0:0:5o6Y6YeR5oqA5pyv56S-5Yy6IEAg5oiR6KGA5p2h5ZGiODEw:q75.awebp?rk3s=f64ab15b&x-expires=1760658325&x-signature=4VVx%2BuE0rDog2r0297adwF%2Bf6fU%3D) ![image.png](https://p9-xtjj-sign.byteimg.com/tos-cn-i-73owjymdk6/6430f487e85748e4a52fc14554092bd7~tplv-73owjymdk6-jj-mark-v1:0:0:0:0:5o6Y6YeR5oqA5pyv56S-5Yy6IEAg5oiR6KGA5p2h5ZGiODEw:q75.awebp?rk3s=f64ab15b&x-expires=1760658325&x-signature=5Y3hvC6wiJMGGbOdWT1PTUo953k%3D) 解决办法： ``` // .stylelintrc.js module.exports = { // 继承的预设，这些预设包含了规则集插件 extends: [ // 代码风格规则 'stylelint-stylistic/config', // 基本 scss 规则 'stylelint-config-standard-scss', // scss vue 规则 'stylelint-config-recommended-vue/scss', // 样式属性顺序规则 'stylelint-config-recess-order', ], rules: { // 自定义规则集的启用 / 禁用 // 'stylistic/max-line-length': null, 'stylistic/max-line-length': 100, 'selector-class-pattern': null, /** * Expected custom property name "--hp-color-bd_light" * to be kebab-caseStylelintcustom-property-pattern */ 'custom-property-pattern': null, }, }; ``` ``` // tsconfig.eslint.json { // eslint 检查专用，不要包含到 tsconfig.json 中 "extends": "./tsconfig.base.json", "compilerOptions": { // 参考 https://typescript-eslint.io/linting/typed-linting/monorepos "noEmit": true }, // 只检查，不构建，因此要包含所有需要检查的文件 "include": [ "**/*", // .xxx.js 文件需要单独声明，例如 .eslintrc.js "**/.*.*", "**/.vitepress/**/*" ], "exclude": [ // 排除产物目录 "**/dist", "**/node_modules" ] } ``` 解决完规范问题，我们将 `` 注册为全局组件，方便后续使用。 ``` // docs/.vitepress/theme/index.ts import DefaultTheme from 'vitepress/theme'; import { EnhanceAppContext } from 'vitepress'; import { Theme } from '@hpui/ui'; import { ShowArea } from '../components'; // 应用组件库的 unocss 预设，配置文件在根目录的 uno.config.ts import 'virtual:uno.css'; export default { ...DefaultTheme, enhanceApp(ctx: EnhanceAppContext) { DefaultTheme.enhanceApp(ctx); const { app } = ctx; // 应用组件库提供的主题插件 app.use(Theme); // 注册其他插件、全局组件、provide... app.component('ShowArea', ShowArea); }, }; ``` 修改 `docs/components/button.md` 中的用例，用刚才封装的 `ShowArea` 组件优化。 ``` # Button 按钮常用的操作按钮。 ## 基础用法基础的按钮用法。 ## Button API ``` 优化后的效果如下：里面用到了两个新的图标，仿照 [从 0 到 1 搭建 Vue 组件库框架 | 矢量图标方案](https://juejin.cn/post/7415656960341393471) 引入即可。 ![动画.gif](https://p9-xtjj-sign.byteimg.com/tos-cn-i-73owjymdk6/231d9a42bc72447290040b6a02d78cc9~tplv-73owjymdk6-jj-mark-v1:0:0:0:0:5o6Y6YeR5oqA5pyv56S-5Yy6IEAg5oiR6KGA5p2h5ZGiODEw:q75.awebp?rk3s=f64ab15b&x-expires=1760658325&x-signature=HcF5t8X4v%2FHbQVgL%2FKdvt7yrDP0%3D) 到现在这一步已经可以满足大部分需求了。 ## 根据用例文件路径渲染出对应的内容参考[element-plus](https://link.juejin.cn/?target=https%3A%2F%2Fgithub.com%2Felement-plus%2Felement-plus%2Fblob%2Fdev%2Fdocs%2Fen-US%2Fcomponent%2Fbutton.md "https://github.com/element-plus/element-plus/blob/dev/docs/en-US/component/button.md") 实现的用例展示功能，我们可以发现：`element-ui` 组件库在成对的 `:::example` & `:::` 中间写入用例的文件路径，就可以渲染出完整的用例展示效果。那么我们是否也可以做到这种效果？ * [element-plus 的实现参考](https://link.juejin.cn/?target=https%3A%2F%2Fgithub1s.com%2Felement-plus%2Felement-plus%2Fblob%2FHEAD%2Fdocs%2F.vitepress%2Fconfig%2Fplugins.ts "https://github1s.com/element-plus/element-plus/blob/HEAD/docs/.vitepress/config/plugins.ts") * [vitepress-theme-demoblock 的实现参考](https://link.juejin.cn/?target=https%3A%2F%2Fgithub1s.com%2Fxinlei3166%2Fvitepress-theme-demoblock%2Fblob%2FHEAD%2Fsrc%2Fnode%2Fdemoblock.ts "https://github1s.com/xinlei3166/vitepress-theme-demoblock/blob/HEAD/src/node/demoblock.ts") 通过参考他人的做法后，通过 [markdown-it-container](https://link.juejin.cn/?target=https%3A%2F%2Fgithub.com%2Fmarkdown-it%2Fmarkdown-it-container "https://github.com/markdown-it/markdown-it-container") 可以便捷地实现这一需求。安装我们所需要的工具。 ```bash pnpm --filter @hpui/docs i -S markdown-it markdown-it-container pnpm --filter @hpui/docs i -D @types/markdown-it ``` 建立 `docs/.vitepress/plugins` 目录，存放我们的 `markdown-it` 拓展插件。 ``` 📦docs ┣ 📂.vitepress ┃ ┣ 📂plugins ┃ ┃ ┣ 📜index.ts ┃ ┃ ┣ 📜mdExamplePlugin.ts # 处理将新语法转换为组件 ┃ ┃ ┣ 📜mdPlugin.ts # markdown-it 插件，集合了 mdExamplePlugin 和 mdScriptSetupPlugin ┃ ┃ ┗ 📜mdScriptSetupPlugin.ts # 处理用例组件通过 `; return defaultRender( // 将 ``` ``` // packages/button/src/index.ts import Button from './button.vue'; import './button.scss'; import 'virtual:uno.css'; export { Button }; export type ButtonInstance = InstanceType; export * from './props'; ``` ### input组件安装 `button` 依赖。 pnpm --filter @hpui/input i -S --workspace @hpui/button 建立 `input` 组件的 `props.ts` 文件。 ``` // packages/input/src/props.ts /** @module Input */ import { Ref } from 'vue'; import { InferVueDefaults } from '@hpui/shared'; import { ButtonProps, defaultButtonProps } from '@hpui/button'; import type Input from './input.vue'; /** 输入框组件的属性 */ export interface InputProps extends ButtonProps { /** * 输入值，支持 v-model 双向绑定 * @default '' */ modelValue?: string; } /** @hidden */ export function defaultInputProps(): Required> { return { ...defaultButtonProps(), modelValue: '', }; } /** 输入框组件的事件 */ export interface InputEmits { /** * 11111 * @param val 输入框的值 */ (event: 'update:modelValue', val: string): void; /** 22222 */ (event: 'input', val: string): void; } /** 输入框组件对外暴露的方法 */ export interface InputExpose { /** 清空输入框 */ clear: () => void; /** 响应式变量 */ a: Ref; } export type InputInstance = InstanceType; ``` ``` ``` ``` // packages/input/src/index.ts import Input from './input.vue'; export { Input }; export type InputInstance = InstanceType; export * from './props'; ``` ### 安装TypeDoc pnpm --filter @hpui/docs i -D typedoc typedoc-plugin-markdown 创建 `docs/scripts/typedoc.ts` 脚本。 ``` // docs/scripts/typedoc.ts import { Application, TSConfigReader, } from 'typedoc'; import { join } from 'node:path'; /** 从整个工程的根目录计算路径 */ const fromRoot = (...paths: string[]) => join( __dirname, '..', '..', ...paths, ); const tsConfigPath = fromRoot('tsconfig.src.json'); /** 文档输出目录 */ const OUT_DIR = join(__dirname, '..', 'api'); async function main() { const app = await Application.bootstrapWithPlugins({ // 指定文件入口，支持 globs 匹配多文件。规定为所有组件包内的 src/props.ts 文件。 entryPoints: [fromRoot('packages', '**', 'props.ts')], // tsconfig 配置 tsconfig: tsConfigPath, // 启用 markdown 转化插件 plugin: ['typedoc-plugin-markdown'], // 更多配置项参考：https://typedoc.org/options/ disableSources: true, readme: 'none', skipErrorChecking: true, }, [ new TSConfigReader(), ]); const project = await app.convert(); if (project) { // 生成并输出产物 await app.generateDocs(project, OUT_DIR); } } main().catch(console.error); ``` 在 `docs/.gitignore` 中补充产物目录。 ``` # docs/.gitignore /.vitepress/cache /api ``` 之前在根目录安装过 [tsx](https://link.juejin.cn/?target=https%3A%2F%2Fgithub.com%2Fesbuild-kit%2Ftsx "https://github.com/esbuild-kit/tsx")，直接运行脚本。 ```bash pnpm --filter @hpui/docs exec tsx scripts/typedoc.ts ``` 观察一下生成产物。 ![image.png](https://p9-xtjj-sign.byteimg.com/tos-cn-i-73owjymdk6/2f063156bf024d8abac5f6c3019a0751~tplv-73owjymdk6-jj-mark-v1:0:0:0:0:5o6Y6YeR5oqA5pyv56S-5Yy6IEAg5oiR6KGA5p2h5ZGiODEw:q75.awebp?rk3s=f64ab15b&x-expires=1760658325&x-signature=BteBS0xydzRcQdTK1M%2F%2BQT%2F8DVs%3D) 注意：如果你的生成产物和这个不一样，确保你的 `typedoc` 和 `typedoc-plugin-markdown` 版本是： "typedoc": "^0.25.4", "typedoc-plugin-markdown": "^3.17.1", 建立 `configs` 文件夹，用来存放导航配置对象的 `json` 文件，再将 `docs/.vitepress/config.mts` 中的导航配置部分由直接声明对象改为文件引入。 ``` // docs/configs/components.json [ { "text": "基础组件", "items": [{ "text": "Button 按钮", "link": "/components/button" }] }, { "text": "配置组件", "items": [{ "text": "ConfigProvider 配置", "link": "/components/config-provider" }] }, { "text": "表单组件", "items": [{ "text": "Input 输入", "link": "/components/input" }] } ] ``` ``` // docs/configs/api.json // 先初始化为空数组，等待后续动态生成 [] ``` ``` // docs/.vitepress/config.mts import { defineConfig } from 'vitepress'; import { mdPlugin } from './plugins'; import apiConfig from '../configs/api.json'; import componentsConfig from '../configs/components.json'; // 配置参考：https://vitepress.dev/reference/site-config export default defineConfig({ title: 'HpUI', description: 'Vue3 组件库', markdown: { config: (md) => { md.use(mdPlugin); }, }, themeConfig: { // 参考：https://vitepress.dev/reference/default-theme-nav#navigation-links nav: [ { text: '指南', link: '/guide/' }, { text: '组件', link: '/components/' }, { text: 'API', link: '/api/' }, { text: '演练场', link: '/playground' }, ], // 参考：https://vitepress.dev/reference/default-theme-sidebar#multiple-sidebars sidebar: { // 指南部分的章节导航 '/guide/': [ { text: '指引', items: [ { text: '组件库介绍', link: '/guide/' }, { text: '快速开始', link: '/guide/quick-start' }, ], }, ], // 组件部分的章节导航 '/components/': componentsConfig, // API 文档部分的章节导航 '/api/': apiConfig, }, }, }); ``` 完善一下 `docs/scripts/typedoc.ts` 中的代码，补充动态生成章节导航部分的逻辑： ``` // docs/scripts/typedoc.ts import { Application, TSConfigReader, ReflectionKind, ProjectReflection, } from 'typedoc'; import { join } from 'node:path'; import { readFile, writeFile } from 'node:fs/promises'; import { DefaultTheme } from 'vitepress'; /** 从整个工程的根目录计算路径 */ const fromRoot = (...paths: string[]) => join( __dirname, '..', '..', ...paths, ); const tsConfigPath = fromRoot('tsconfig.src.json'); /** 文档输出目录 */ const OUT_DIR = join(__dirname, '..', 'api'); /** 章节导航配置所在目录 */ const CONFIGS_DIR = join(__dirname, '..', 'configs'); async function main() { const app = await Application.bootstrapWithPlugins({ // 指定文件入口，支持 globs 匹配多文件。规定为所有组件包内的 src/props.ts 文件。 entryPoints: [fromRoot('packages', '**', 'props.ts')], // tsconfig 配置 tsconfig: tsConfigPath, // 启用 markdown 转化插件 plugin: ['typedoc-plugin-markdown'], // 更多配置项参考：https://typedoc.org/options/ disableSources: true, readme: 'none', skipErrorChecking: true, }, [ new TSConfigReader(), ]); const project = await app.convert(); if (project) { // 生成并输出产物 await app.generateDocs(project, OUT_DIR); // 生成产物 json 文件 const jsonDir = join(OUT_DIR, 'documentation.json'); await app.generateJson(project, jsonDir); // 根据产物信息，动态生成 API 文档部分的章节导航 await resolveConfig(jsonDir, join(CONFIGS_DIR, 'components.json')); } } main().catch(console.error); /** 生成 sidebar 目录 config */ async function resolveConfig( documentJsonDir: string, componentsConfigJsonDir: string, ) { // 读取 TypeDoc 产物 const buffer = await readFile(documentJsonDir, 'utf8'); const data = JSON.parse(buffer.toString()) as ProjectReflection; if (!data.children || data.children.length <= 0) { return; } // 读取 components.json，使 API 文档的一、二级导航与组件说明文档保持一致 const componentsConfig = await readComponentsConfig(componentsConfigJsonDir); data.children.forEach((module) => { if (module.kind !== ReflectionKind.Module) return; const moduleConfig = findComponentFromConfig(componentsConfig, module.name); if (!moduleConfig) return; moduleConfig.collapsed = true; moduleConfig.link = `/api/modules/${module.name}`; // 每个模块下的 interface、class 继续细分为三级导航 moduleConfig.items = []; module.children?.forEach((sub) => { // 将三级导航的跳转路径与产物文件路径对应起来 if (sub.kind === ReflectionKind.Class) { moduleConfig.items?.push({ text: sub.name, link: `/api/classes/${module.name}.${sub.name}` }); } else if (sub.kind === ReflectionKind.Interface) { moduleConfig.items?.push({ text: sub.name, link: `/api/interfaces/${module.name}.${sub.name}` }); } }); }); // 输出最终的导航对象 await writeFile(join(CONFIGS_DIR, 'api.json'), JSON.stringify(componentsConfig, null, 2), 'utf8'); } async function readComponentsConfig(jsonDir: string) { const buffer = await readFile(jsonDir, 'utf8'); return JSON.parse(buffer.toString()) as DefaultTheme.SidebarItem[]; } function findComponentFromConfig(config: DefaultTheme.SidebarItem[], name: string) { let itemIndex = -1; const targetCategory = config.find((category) => { if (!category.items || category.items.length <= 0) return false; itemIndex = category.items.findIndex((comp) => comp.text?.startsWith(name)); return itemIndex >= 0; }); return itemIndex >= 0 ? targetCategory?.items?.[itemIndex] || null : null; } ``` 修改 `package.json` 中 `scripts` 字段，加入 `TypeDoc` 自动生成 API 文档的脚本。 ``` // docs/package.json { "name": "@hpui/docs", "private": true, "scripts": { "api": "tsx scripts/typedoc.ts", "dev": "vitepress dev . --host", "build": "pnpm run api && vitepress build .", "preview": "vitepress preview . --host" }, "devDependencies": { "@types/markdown-it": "^14.1.2", "typedoc": "^0.26.7", "typedoc-plugin-markdown": "^4.2.7", "vitepress": "^1.3.4" }, "dependencies": { "@hpui/ui": "workspace:^", "markdown-it": "^14.0.0", "markdown-it-container": "^4.0.0" } } ``` 修改对应的标题栏导航。 ``` // docs/.vitepress/config.mts import { defineConfig } from 'vitepress'; import { mdPlugin } from './plugins'; import apiConfig from '../configs/api.json'; import componentsConfig from '../configs/components.json'; // 配置参考：https://vitepress.dev/reference/site-config export default defineConfig({ title: 'HpUI', description: 'Vue3 组件库', ignoreDeadLinks: true, markdown: { config: (md) => { md.use(mdPlugin); }, }, themeConfig: { // 参考：https://vitepress.dev/reference/default-theme-nav#navigation-links nav: [ { text: '指南', link: '/guide/' }, { text: '组件', link: '/components/' }, { text: 'API', link: '/api/README' }, { text: '演练场', link: '/playground' }, ], // 每篇文档右侧的大纲开启支持三级的深度 outline: { level: [2, 3], }, // 参考：https://vitepress.dev/reference/default-theme-sidebar#multiple-sidebars sidebar: { // 指南部分的章节导航 '/guide/': [ { text: '指引', items: [ { text: '组件库介绍', link: '/guide/' }, { text: '快速开始', link: '/guide/quick-start' }, ], }, ], // 组件部分的章节导航 '/components/': componentsConfig, // API 文档部分的章节导航 '/api/': apiConfig, }, }, }); ``` 修改对应的首页导航。 ``` --- # VitePress 支持在 markdown 中通过 Frontmatter 写 yaml 配置，设置页面的主题样式 # https://vitepress.dev/reference/frontmatter-config#frontmatter-config # VitePress 默认主题的首页模板：https://vitepress.dev/reference/default-theme-layout#home-layout layout: home title: HpUI hero: name: HpUI text: Vue3 组件库 tagline: 从 0 到 1 搭建 Vue 组件库 image: src: /logo.svg alt: Hp actions: - theme: brand text: 指南 link: /guide/ - theme: brand text: 组件 link: /components/ - theme: brand text: API 文档 link: /api/README - theme: brand text: 演练场 link: /playground - theme: alt text: Gitee link: https://gitee.com/hit-point/hp-ui --- ``` 接下来以 `button` 组件为例，引入 `TypeDoc` 生成的文档。修改 `button` 组件对应的文档。 ``` # Button 按钮常用的操作按钮。 ## 基础用法基础的按钮用法。 :::example ../example/button/index.vue ::: ## Button API ## [Button Props](../api/interfaces/Button.ButtonProps.md) ## [Button Slots](../api/interfaces/Button.ButtonSlots.md) ``` 运行脚本。 pnpm --filter @hpui/docs run api 脚本自动生成的文档如下。 [ { "text": "基础组件", "items": [ { "text": "Button 按钮", "link": "/api/modules/Button", "collapsed": true, "items": [ { "text": "ButtonProps", "link": "/api/interfaces/Button.ButtonProps" }, { "text": "ButtonSlots", "link": "/api/interfaces/Button.ButtonSlots" } ] } ] }, { "text": "配置组件", "items": [ { "text": "ConfigProvider 配置", "link": "/components/config-provider" } ] }, { "text": "表单组件", "items": [ { "text": "Input 输入", "link": "/api/modules/Input", "collapsed": true, "items": [ { "text": "InputEmits", "link": "/api/interfaces/Input.InputEmits" }, { "text": "InputExpose", "link": "/api/interfaces/Input.InputExpose" }, { "text": "InputProps", "link": "/api/interfaces/Input.InputProps" } ] } ] } ] 来看下生成文档效果。 ![动画.gif](https://p9-xtjj-sign.byteimg.com/tos-cn-i-73owjymdk6/17da44dae798403d9e3a04633c5c270c~tplv-73owjymdk6-jj-mark-v1:0:0:0:0:5o6Y6YeR5oqA5pyv56S-5Yy6IEAg5oiR6KGA5p2h5ZGiODEw:q75.awebp?rk3s=f64ab15b&x-expires=1760658325&x-signature=PuX6ejRZcR12f6tpKfpeSi6%2FZMw%3D) ![动画.gif](https://p9-xtjj-sign.byteimg.com/tos-cn-i-73owjymdk6/fca883cb1a274f6e991159e15e7c01c2~tplv-73owjymdk6-jj-mark-v1:0:0:0:0:5o6Y6YeR5oqA5pyv56S-5Yy6IEAg5oiR6KGA5p2h5ZGiODEw:q75.awebp?rk3s=f64ab15b&x-expires=1760658325&x-signature=dk5gPQN8yD%2BybBwYn68LwnAFci0%3D)