markdown plugin for building demos in vitepress.
npm install vitepress-plugin-demo or container in Markdown to reference a demo container.
vitepress-plugin-demo is a markdown-it plugin specifically designed for Vitepress demos. It converts code blocks in Markdown into references to the component. It does not generate UI itself but serves as a plugin for creating demo containers.
tag in Markdown to reference a demo container. For example:
vue
`
You can use Markdown syntax in the desc field. For example:
`vue
..." />
`
However, we recommend using the container mode to write the desc content with Markdown:
`markdown
::: demo src="../demo.vue" title="Demo block"
This is a description that can be written using Markdown.
:::
`
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:
`markdown
`
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:
`markdown
`
React
vitepress-plugin-demo also supports React demo blocks. You can use the react tag in Markdown to reference a demo container.
`sh
npm install react react-dom --save-dev
`
import your React component:
`markdown
`
Install
`bash
npm install vitepress-plugin-demo --save-dev
`
Usage
`js
import { demoMdPlugin } from 'vitepress-plugin-demo'
// .vitepress/config.js
export default defineConfig({
markdown: {
config(md) {
md.use(demoMdPlugin)
},
},
})
`
Register your component in theme/index.ts|js:
`js
// https://vitepress.dev/guide/custom-theme
import Theme from 'vitepress/theme'
// your demo component
import CustomDemoContainer from './components/CustomDemoContainer.vue'
export default {
...Theme,
enhanceApp({ app, router, siteData }) {
app.component('demo-container', CustomDemoContainer)
},
}
`
Presets
vitepress-plugin-demo pre-set common component library themes, which you can directly use:
Naive UI
`sh
npm install vitepress-plugin-demo naive-ui --save-dev
`
`js
import TwoslashFloating from '@shikijs/vitepress-twoslash/client'
import NaiveUIContainer from 'vitepress-plugin-demo/client/naive-ui'
import '@shikijs/vitepress-twoslash/style.css'
export default {
...Theme,
async enhanceApp({ app, router, siteData }) {
if (!import.meta.env.SSR) {
const { default: NaiveUI } = await import('naive-ui')
app.use(NaiveUI)
}
app.use(TwoslashFloating)
app.use(NaiveUIContainer, {
github: 'you github blob url',
codeeditor: {
editor: ['stackblitz', 'codesandbox'],
globals: {
package: {/ ... /},
files: {/ ... /},
opens: ['App.vue']
},
resolve(props) {
const code = props.typescript || props.javascript
return { / cover global config / }
}
},
})
},
}
`
Customs
The demo-container component will receive relevant information about the demo, and you need to implement the rendering of the demo:
`vue
{{ title }}
Copy Code
`
Other props will not be processed and will be directly passed to the component. For example, you can customize whether the code is expanded using the prop:
`markdown
`
> however, it is important to note that is not strictly a component and cannot handle excessively complex custom props, such as v-bind.
`ts
const props = defineProps<{
// ...
expand: boolean
}>()
`
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:
`vue
`
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