The above article "Vitepress Building Component Library Document (Part 1) - Basic Configuration" has discussed the basic configuration of Vitepress building component library document, including site logo, name, home page layout , top navigation, left navigation, etc. This article enters the most important part - how to display the effects and source code of components in one pass of code like Element Plus .
1 Implementation effect of component Demo
vitepress has better support for MarkDown and also better support for vue3. There are two common ways to display Demo in MD documents:
- Displayed in a block, add a plug-in to parse the demo block, such as:
组件基本使用：
:::demo 描述信息
<template>
<el-button type="primary">测试按钮</el-button>
</template>
:::
- Encapsulate a component, pass the language and path of the Demo code to the component, and then use the component in the MD document, such as:
组件基本使用：
<code-preview path="../demos/xx/xxx.vue"
language="vue">
If there are few demos in a component document, you can use the first method and write the component demo directly in the MD document; but if there are many demos or the demo implementation is complex, you can use the second method. So it's best to support both methods.
Before vitepress 1.0 (such as 0.22.0), vitepress-theme-demoblock was a very good choice, supporting the display of Demo and sample code in a block. However, you can see from npmjs that the plug-in has not been updated for more than a year. An error will be reported in vitepress 1.0 . After constant searching, I finally found a plug-in that can support vitepress 1.0 very well - vitepress-demo-preview . I am very grateful to the author of vitepress-demo-preview, flingyp !
2 Integrate @vitepress-demo-preview
2.1 Install dependencies
pnpm add @vitepress-demo-preview/component @vitepress-demo-preview/plugin
2.2 config.ts
Modify docs/.vitepress/config.ts and add markdown configuration:
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 Component introduction
Create a new directory theme under .vitepress and create index.ts in the theme directory
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)
}
}
This completes the configuration of @vitepress-demo-preview , and then you can write the demo in the component document.
3. Write component demo
Since this is a demonstration, we will not write test components. We simply use Element-Plus to simulate the component library and use Button in the document to write the Demo.
3.1 Introduction of component library
Install component library dependencies:
pnpm install element-plus
Install the component library in .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 Write component demo
Create a demo directory in the docs directory , which stores the demos written in the document. For example, define a button-demo-1.vue file:
<template>
<el-button type="primary">测试按钮</el-button>
</template>
Use this Demo in docs /compnents/basic-component1.md :
# Basic Component 1
<preview path="../demos/button-demo-1.vue" title="基本使用" description="xxxxx"></preview>
Preview this page:
Using this plug-in, component Demo can only be defined outside the document, and writing Demo in the MD document is not supported.
4 Packaging component library
After the component library is packaged, it needs to be packaged and released.
Pack:
pnpm run build
Preview component library:
pnpm run serve
This is the first introduction to writing component library documents in vitepress . Later I will share pnpm + monorepo + vite + vue3 + tsx + vitepress to build an enterprise-level component library. The content outline is as follows:
- pnpm builds monorepo style architecture;
- Component library development environment construction and build release;
- Component library demonstration example development environment construction and build release;
- Component library document development environment construction and build release;
- Command line tool development.
Thank you for reading this article. If this article has given you a little help or inspiration, please support it three times, like, follow, and collect. The author will continue to share more useful information with you.