🎉 Introduce

We can see their component display and code example display from some excellent UI component libraries such as element-plus and Ant Design Vue

This project is based on vitepress and markdown-it implementation to display components and code examples in documents. Using this plug-in, Vue SFC components can be displayed in static documents

🏄‍♂️ Packages

Package	Version (click for changelogs)
@vitepress-demo-preview/component
@vitepress-demo-preview/plugin

⚙️ Installation

1pnpm add @vitepress-demo-preview/component @vitepress-demo-preview/plugin

⚡ Usage

configure in your vitepress/theme entry file

1import DefaultTheme from 'vitepress/theme'
2import { AntDesignContainer, ElementPlusContainer, NaiveUIContainer } from '@vitepress-demo-preview/component'
3import '@vitepress-demo-preview/component/dist/style.css'
4
5export default {
6  ...DefaultTheme,
7  enhanceApp({ app }: { app: App }) {
8    app.component('demo-preview', AntDesignContainer)
9  }
10}

configure markdown to add plugin

1import { defineConfig } from 'vitepress'
2import { containerPreview, componentPreview } from '@vitepress-demo-preview/plugin'
3
4export default defineConfig({
5  markdown: {
6    config(md) {
7      md.use(containerPreview)
8      md.use(componentPreview)
9    }
10  }
11})

SSR Compatibility

If the components are not SSR-friendly, you can specify the clientOnly to disable SSR.

1import { defineConfig } from 'vitepress'
2import { containerPreview, componentPreview } from '@vitepress-demo-preview/plugin'
3
4export default defineConfig({
5  markdown: {
6    config(md) {
7      /**
8       * SSR Compatibility
9       * @link https://vitepress.dev/guide/ssr-compat
10       * If the components are not SSR-friendly, you can specify the clientOnly to disable SSR.
11       */
12      md.use(containerPreview, { clientOnly: true })
13      md.use(componentPreview, { clientOnly: true })
14    }
15  }
16})

Alias Configuration

If you need to use alias paths, you can configure the alias in the vitepress configuration file.

1import { defineConfig } from 'vitepress'
2import { resolve } from 'path'
3
4const alias = {
5  '@': resolve(__dirname, '../../example')
6}
7
8export default defineConfig({
9  // ...
10  markdown: {
11    config(md) {
12      md.use(componentPreview, { alias })
13      md.use(containerPreview, { alias })
14    }
15  },
16  vite: {
17    resolve: {
18      alias
19    }
20  }
21})

Preview of Component Form

1<!-- Tip: Support for closed tags -->
2
3<preview path="./xxx/xx.vue"></preview>
4
5<preview path="./xxx/xx.vue" title="title"></preview>
6
7<preview path="./xxx/xx.vue" title="title" description="component description content"></preview>

Preview by Container Form

1:::preview
2
3demo-preview=./xxx/xx.vue
4
5:::
6
7:::preview title
8
9demo-preview=./xxx/xx.vue
10
11:::
12
13:::preview title || component description content
14
15demo-preview=./xxx/xx.vue
16
17:::

📦 Packages

@vitepress-demo-preview/plugin

@vitepress-demo-preview/plugin is a markdown-it plugin, which mainly provides two kinds of Component preview methods, namely Component Form and Container Form.

@vitepress-demo-preview/component

@vitepress-demo-preview/component is a component library that provides presentation components. It mainly provides three containers. These are Ant Design Container, ElementPlus Container, and Naive UI Container, which mimic the styles associated with the preview of each UI framework component.

Of course, we will also consider providing similar component containers for other component libraries.

Tip: @vitepress-demo-preview/component is not necessary. You can also consider just using the @vitepress-demo-preview/plugin, which is not bound to each other. You can implement your own component container according to your own preferences and needs. For details, refer to the source code of the above three containers.

📑 License

MIT

Copyright (c) 2023 flingyp