Quick Start

Installation

Choose your preferred package manager for installation:

npm install vitepress-demo-plugin -D

yarn add vitepress-demo-plugin -D

pnpm add vitepress-demo-plugin -D

Import Plugin

Add the following code to .vitepress/config.ts to import the vitepressDemoPlugin:

import { defineConfig } from 'vitepress';
import { vitepressDemoPlugin } from 'vitepress-demo-plugin/markdown'; 
import path from 'node:path';

export default defineConfig({
  // other configs...
  markdown: { 
    config(md) { 
      md.use(vitepressDemoPlugin); 
    }, 
  }, 
});

Vue Demo

You can set path of .vue file by <demo vue="xxx/path" /> in .md file, render this vue component and display source code.

<demo vue="../demos/demo.vue" />

The corresponding rendering result is as follows:

loading

Html Demo

You can set path of .html file by <demo html="xxx/path" /> in .md file, render this html file and display source code.

<demo html="../demos/demo.html" />

The corresponding rendering result is as follows:

loading

React Demo

Tip

If you want to display React Demo in your vitepress site, you need install related decencies by command below

npm install react react-dom -D

You can set path of .jsx/.tsx file by <demo react="xxx/path" /> in .md file, render this html file and display source code.

<demo react="../demos/demo.tsx" />

The corresponding rendering result is as follows:

loading

Svelte Demo

Tip

If you want to display Svelte Demo in your vitepress site, you need to execute the following command to install the corresponding dependencies:

npm install svelte @sveltejs/vite-plugin-svelte -D

And import the svelte plugin in vite.plugins of .vitepress/config.ts:

import { svelte } from '@sveltejs/vite-plugin-svelte'; 

export default defineConfig({
  // other configs...
  vite: { 
    plugins: [svelte()], 
  }, 
});

You can set path of .svelte file by <demo svelte="xxx/path" /> in .md file, render this svelte component and display source code.

<demo svelte="../demos/demo.svelte" />

The corresponding rendering result is as follows:

loading

Preact Demo

Tip

To display a Preact Demo in your VitePress site, install the required dependencies:

npm install preact @preact/preset-vite -D

Then import the Preact plugin in vite.plugins of .vitepress/config.ts. Since Preact, React and Solid all use the .jsx/.tsx extensions, name Preact components *.preact.tsx, use include so the plugin only processes those files, and disable React compatibility aliases:

import preact from '@preact/preset-vite'; 

export default defineConfig({
  // other configs...
  vite: { 
    plugins: [ 
      preact({ 
        include: [/\.preact\.tsx$/], 
        reactAliasesEnabled: false, 
        babel: {}, 
      }), 
    ], 
  }, 
});

Set the path of a .jsx/.tsx file with <demo preact="xxx/path" /> to render the Preact component and display its source code:

<demo preact="../demos/demo.preact.tsx" />

The corresponding rendering result is as follows:

loading

Solid Demo

Tip

If you want to display Solid Demo in your vitepress site, you need to execute the following command to install the corresponding dependencies:

npm install solid-js vite-plugin-solid -D

And import the solid plugin in vite.plugins of .vitepress/config.ts. Since both Solid and React use the .jsx/.tsx extension, it is recommended to name Solid components as *.solid.tsx and use include to restrict the solid plugin to these files only, so it won't affect the compilation of React components:

import solid from 'vite-plugin-solid'; 

export default defineConfig({
  // other configs...
  vite: { 
    plugins: [solid({ include: [/\.solid\.tsx$/] })], 
  }, 
});

You can set path of solid component file by <demo solid="xxx/path" /> in .md file, render this solid component and display source code.

<demo solid="../demos/demo.solid.tsx" />

The corresponding rendering result is as follows:

loading

---

Mixed Demo

Tip

Same as above, if you want to display React, Svelte, Preact or Solid Demo in your VitePress site, install the corresponding dependencies:

npm install react react-dom -D
npm install svelte @sveltejs/vite-plugin-svelte -D
npm install preact @preact/preset-vite -D
npm install solid-js vite-plugin-solid -D

You can specify multiple vue/react/svelte/solid/preact/html in <demo /> at the same time to display demos with different syntaxes in one block.

<demo
  vue="../demos/demo.vue"
  react="../demos/demo.tsx"
  svelte="../demos/demo.svelte"
  preact="../demos/demo.preact.tsx"
  solid="../demos/demo.solid.tsx"
  html="../demos/demo.html"
/>

The corresponding rendering result is as follows:

loading

Title And Description

Set demo title and description by title 和 description:

<demo
  vue="../demos/demo.vue"
  react="../demos/demo.tsx"
  html="../demos/demo.html"
  title="Multiple Syntax DEMO"
  description="This is an example of a mixed demo. You can use title and description to specify the title and description of the demo."
/>

The corresponding rendering result is as follows:

loading

Open Github And Gitlab

You can add link by github and gitlab in <demo />. It will navigate to corresponding address.

<demo
  vue="../demos/demo.vue"
  github="https://github.com/zh-lx/vitepress-demo-plugin/blob/main/packages/docs/demos/demo.vue" 
/>

The corresponding rendering result is as follows:

loading

For GitLab, the usage is the same as GitHub. Simply replace github with gitlab.

SSG

To avoid using window、document 等 browser environment variables in user components, vitepress-demo-plugin defaults to using the <ClientOnly> component to wrap user components. However, this will cause the user's components to not participate in static compilation, thus slowing down the loading speed of the components on the page.

If you are sure that your components do not use window、document etc. browser environment variables and only use vue components, you can close the <ClientOnly> component's packaging by setting the ssg attribute, thus speeding up the loading speed of the components.

<demo
  vue="../demos/demo.vue"
  ssg="true"
/>

The corresponding rendering result is as follows:

在 Stackblitz 中打开

展开代码

复制代码