vitepress-plugin-demo

Features

• ✨ Use the <demo> or container in Markdown to reference a demo container.
• ♾️ Automatically convert TS code and provide JS demo code.
• 👽️ Support Vue, React, JS, TS and HTML demo block.
• 📝 Use Markdown syntax by you demo block description.
• 💡 Support twoslash syntax highlighting.
• 📦️ Supports multiple presets, ready to use out of the box.
• 🎨 Customize the demo container to suit your needs.

vitepress-plugin-demo is a markdown-it plugin specifically designed for Vitepress demos. It converts code blocks in Markdown into references to the <demo-container> component. It does not generate UI itself but serves as a plugin for creating demo containers.

With this plugin, you can use the <demo> tag in Markdown to reference a demo container. For example:

1<demo src="../demo.vue" title="Demo block" description="use demo" />

You can use Markdown syntax in the desc field. For example:

1<demo src="../demo.vue" title="Demo block" description="use `demo` ..." />

However, we recommend using the container mode to write the desc content with Markdown:

1::: demo src="../demo.vue" title="Demo block"
2
3This is a `description` that can be written using Markdown.
4
5:::

This looks more aesthetically pleasing and adheres better to Markdown syntax.

In addition, you can pass the attrs parameter to props, so you can utilize the Line Highlighting in Code Blocks feature of VitePress:

1<demo src="../demo.vue" attributes="{1,4,6-8}" />
2<demo src="../demo.vue" attributes="{4}" />

Twoslash

vitepress-plugin-demo also supports vitepress/twoslash syntax highlighting. You can use the twoslash tag in Markdown to reference a demo container. For example:

1<demo src="../demo.vue" title="Demo block" description="use demo" twoslash />

React

vitepress-plugin-demo also supports React demo blocks. You can use the react tag in Markdown to reference a demo container.

1npm install react react-dom --save-dev

import your React component:

1<demo type="react" src="../demo.tsx" title="Demo block" description="use demo" />

Install

1npm install vitepress-plugin-demo --save-dev

Usage

1import { demoMdPlugin } from 'vitepress-plugin-demo'
2// .vitepress/config.js
3export default defineConfig({
4  markdown: {
5    config(md) {
6      md.use(demoMdPlugin)
7    },
8  },
9})

Register your <demo-container> component in theme/index.ts|js:

1// https://vitepress.dev/guide/custom-theme
2import Theme from 'vitepress/theme'
3
4// your demo component
5import CustomDemoContainer from './components/CustomDemoContainer.vue'
6
7export default {
8  ...Theme,
9  enhanceApp({ app, router, siteData }) {
10    app.component('demo-container', CustomDemoContainer)
11  },
12}

Presets

vitepress-plugin-demo pre-set common component library themes, which you can directly use:

1npm install vitepress-plugin-demo naive-ui --save-dev

1import TwoslashFloating from '@shikijs/vitepress-twoslash/client'
2import NaiveUIContainer from 'vitepress-plugin-demo/client/naive-ui'
3import '@shikijs/vitepress-twoslash/style.css'
4
5export default {
6  ...Theme,
7  async enhanceApp({ app, router, siteData }) {
8    if (!import.meta.env.SSR) {
9      const { default: NaiveUI } = await import('naive-ui')
10      app.use(NaiveUI)
11    }
12    app.use(TwoslashFloating)
13    app.use(NaiveUIContainer, {
14      github: 'you github blob url',
15      codeeditor: {
16        editor: ['stackblitz', 'codesandbox'],
17        globals: {
18          package: {/* ... */},
19          files: {/* ... */},
20          opens: ['App.vue']
21        },
22        resolve(props) {
23          const code = props.typescript || props.javascript
24          return { /* cover global config */ }
25        }
26      },
27    })
28  },
29}

Customs

The demo-container component will receive relevant information about the demo, and you need to implement the rendering of the demo:

1<script lang="ts" setup>
2import { computed } from 'vue'
3
4const props = defineProps<{
5  typescript: string
6  // if using ts, javascript will transform the to js
7  javascript: string
8  title: string
9  metadata: object
10}>()
11
12const code = computed(() => decodeURIComponent(props.typescript || props.javascript))
13</script>
14
15<template>
16  <div>
17    <div>{{ title }}</div>
18    <!-- copy your demo source code -->
19    <div @click="navigator.clipboard.writeText(code)"> Copy Code </div>
20    <!-- The description is rendered in the desc slot -->
21    <slot name="md:description" />
22    <!-- The demo is rendered in the default slot -->
23    <slot />
24    <!-- highlighted code for the demo -->
25    <slot name="md:typescript" />
26    <!-- or -->
27    <slot name="md:javascript" />
28  </div>
29</template>

Other props will not be processed and will be directly passed to the <demo-container> component. For example, you can customize whether the code is expanded using the prop:

1<demo src="../demo.vue" expand />

however, it is important to note that <demo> is not strictly a component and cannot handle excessively complex custom props, such as v-bind.

1const props = defineProps<{
2  // ...
3  expand: boolean
4}>()

Metadata

The demo-container component will receive relevant information about the demo. You can use the metadata to access and use this information within the demo:

1<script lang="ts" setup>
2const props = defineProps<{
3  typescript: string
4  javascript: string
5  title: string
6  // metadata returns information about the demo during build (absolutePath, relativePath, fileName)
7  metadata: object
8}>()
9const githubBlobUrl = 'https://www.github.com/.../tree/main/'
10const githubPath = githubBlobUrl + props.metadata.relativePath
11
12function toEditGithubDemoFile() {
13  window.open(githubPath)
14}
15</script>

CodeSandbox

You can define the parameters for CodeSandbox by using codesandbox/lib/api/define and create a sandbox environment by submitting them to the CodeSandbox API through a <form>:

1<script lang="ts" setup>
2import { getParameters } from 'codesandbox/lib/api/define'
3
4const props = defineProps<{
5  typescript: string
6  javascript: string
7  // ...
8}>()
9
10// Compute the parameters for CodeSandbox
11const parameters = computed(() => {
12  return getParameters({
13    files: {
14      'package.json': {
15        // specify your dependencies
16        content: { dependencies: { vue: 'latest' } },
17      },
18      'index.html': { content: `<div id="app"></div>` },
19      'App.vue': { content: decodeURIComponent(props.javascript) },
20      'src/main.js': { content: '...' },
21    },
22  })
23})
24</script>
25<template>
26  <!-- Form to submit the parameters to CodeSandbox -->
27  <form action="https://codesandbox.io/api/v1/sandboxes/define" method="POST" target="_blank">
28    <input type="hidden" name="parameters" :value="parameters">
29    <button>Edit in CodeSandbox</button>
30  </form>
31</template>

Development

1pnpm install
2
3# Run development server
4pnpm dev
5
6# Have fun!
7pnpm play

Unit tests are in progress, PRs welcome!

Acknowledgements

This project draws inspiration from the following projects:

• ruabick
• vitepress-demo-preview
• create-vitepress-demo
• naive-ui
• element-plus

License

MIT License © Hairyf