上文 《Vitepress搭建組件庫文檔（上）—— 基本配置》已經討論了 vitepress 搭建組件庫文檔的基本配置，包括站點 Logo、名稱、首頁 *home* 佈局、頂部導航、左側導航等。本文進入最重要的部分 —— 如何像 *Element Plus* 那樣一遍代碼就可以展示組件的效果和源代碼... ...
上文 《Vitepress搭建組件庫文檔（上）—— 基本配置》已經討論了 vitepress 搭建組件庫文檔的基本配置，包括站點 Logo、名稱、首頁 home 佈局、頂部導航、左側導航等。本文進入最重要的部分 —— 如何像 Element Plus 那樣一遍代碼就可以展示組件的效果和源代碼。
1 組件 Demo 的實現效果
vitepress 對 MarkDown 支持比較好，同時對 vue3 也支持較好。常見的在 MD 文檔中展示 Demo 有兩種方式：
- 在一個區塊內展示，添加插件用來解析 demo 區塊，如：
組件基本使用：
:::demo 描述信息
<template>
<el-button type="primary">測試按鈕</el-button>
</template>
:::
- 封裝一個組件，將 Demo 代碼的語言、路徑傳遞給該組件，然後在 MD 文檔中使用該組件，如：
組件基本使用：
<code-preview path="../demos/xx/xxx.vue"
language="vue">
如果某個組件文檔中 demo 較少，可以使用第一種方式，直接在 MD 文檔中編寫組件 demo；但如果 demo 較多或 demo 實現較複雜，可以使用第二種方式。所以最好兩種方式都支持。
在 vitepress 1.0 之前（如 0.22.0），vitepress-theme-demoblock 是個非常好的選擇，支持區塊內的方式展示 Demo 和示例代碼，但從 npmjs 上面可以看到該插件有一年多沒更新了，在 vitepress 1.0 中會報錯。不停搜索，總算找到一個可以很好支持 vitepress 1.0 的插件 —— vitepress-demo-preview，這裡非常感謝 vitepress-demo-preview 的作者 flingyp 大神！
2 集成 @vitepress-demo-preview
2.1 安裝依賴
pnpm add @vitepress-demo-preview/component @vitepress-demo-preview/plugin
2.2 config.ts
修改 docs/.vitepress/config.ts，添加 markdown 配置：
import { componentPreview, containerPreview } from '@vitepress-demo-preview/plugin'
...
export default defineConfig({
...
markdown: {
theme: {
light: 'vitesse-light',
dark: 'vitesse-dark'
},
lineNumbers: true,
config(md) {
md.use(componentPreview)
md.use(containerPreview)
}
}
})
2.3 組件引入
在 .vitepress 下新建目錄 theme，併在 theme 目錄中創建 index.ts
import theme from 'vitepress/dist/client/theme-default/index'
import { AntDesignContainer } from '@vitepress-demo-preview/component'
import '@vitepress-demo-preview/component/dist/style.css'
export default {
...theme,
enhanceApp({app}) {
app.component('demo-preview', AntDesignContainer)
}
}
這樣便完成了 @vitepress-demo-preview 的配置，接下來就可以在組件文檔中編寫demo了。
3 編寫組件 demo
這裡由於是演示，就不編寫測試組件了，簡單的使用 Element-Plus 來模擬組件庫，在文檔使用 Button 編寫 Demo。
3.1 引入組件庫
安裝組件庫依賴：
pnpm install element-plus
在 .vitepress/theme/index.ts 中安裝組件庫：
import ElementPlus from 'element-plus'
import 'element-plus/dist/index.css'
import theme from 'vitepress/dist/client/theme-default/index'
import { AntDesignContainer } from '@vitepress-demo-preview/component'
import '@vitepress-demo-preview/component/dist/style.css'
export default {
...theme,
enhanceApp({app}) {
app.use(ElementPlus)
app.component('demo-preview', AntDesignContainer)
}
}
3.2 編寫組件 Demo
在 docs 目錄下創建 demo 目錄，該目錄存放文檔中編寫的demo，如定義一個 button-demo-1.vue 文件：
<template>
<el-button type="primary">測試按鈕</el-button>
</template>
在 docs/compnents/basic-component1.md 中使用該 Demo：
# Basic Component 1
<preview path="../demos/button-demo-1.vue" title="基本使用" description="xxxxx"></preview>
預覽該頁面：
使用這個插件，只能在文檔外部定義組件 Demo，不支持在 MD 文檔中編寫 Demo。
4 打包組件庫
組件庫打包完成後，需要打包發佈。
打包：
pnpm run build
預覽組件庫：
pnpm run serve
vitepress 編寫組件庫文檔就先介紹到這裡。後面將分享 pnpm + monorepo + vite + vue3 + tsx + vitepress 搭建企業級組件庫，內容大綱如下：
- pnpm 搭建 monorepo 風格架構；
- 組件庫開發環境搭建和構建發佈；
- 組件庫演示 example 開發環境搭建和構建發佈；
- 組件庫文檔開發環境搭建和構建發佈；
- 命令行工具開發。
感謝你閱讀本文，如果本文給了你一點點幫助或者啟發，還請三連支持一下，點贊、關註、收藏，作者會持續與大家分享更多乾貨
