专为增强 Markdown 文档设计，特别适用于 Vue 和 TSX 组件的实时预览与代码展示，支持自定义容器及 SSR 兼容。

在线示例

更新日志

✨ 特点 {#features}

• 自定义容器：支持灵活配置容器符号和名称，满足不同文档结构的需求。
• 样式隔离机制：提供 vp-raw 类名控制隔离区域，确保示例组件样式不受影响。
• 组件支持：兼容 .vue 和 .tsx 组件，轻松引入多种前端框架示例。
• 可修改根目录：支持自定义根目录（默认 /examples），便于项目示例文件的组织和管理。
• 简化路径管理：通过相对路径直接引入示例文件，如 /demo/test.tsx，简化路径配置。
• SSR 兼容性：轻松使用 {ClientOnly} 选项，灵活控制组件加载方式，增强服务端渲染兼容性。
• VitePress 扩展支持：完美支持 VitePress 的 行内语法高亮 、代码行号 及 代码组 功能，提升文档的可读性和交互性。
• 高效渲染：基于 VitePress 默认的服务端渲染机制，确保示例演示内容快速加载，提升用户体验和搜索引擎优化（SEO）。
• 暗黑模式兼容：原生支持暗黑模式，为用户提供更好的视觉体验。

📦 安装 {#install}

::: code-group

1pnpm add @movk-repo/demo-preview

1npm add @movk-repo/demo-preview

1yarn add @movk-repo/demo-preview

:::

🚀 使用 {#usage}

添加插件 {#plugin}

在 .vitepress/config.ts 中添加插件

1import { demoPreviewPlugin } from '@movk-repo/demo-preview' // [!code ++]
2import { defineConfig } from 'vitepress'
3
4export default defineConfig({
5  markdown: {
6    config: (md) => {
7      md.use(demoPreviewPlugin) // [!code ++]
8    },
9  },
10})

注册容器组件 {#container}

在 .vitepress/theme/index.ts 中注册容器组件

• 如何在 VitePress 中注册组件

1import type { Theme } from 'vitepress'
2import { DemoPreviewContainer } from '@movk-repo/demo-preview/container' // [!code ++]
3import DefaultTheme from 'vitepress/theme'
4import '@movk-repo/demo-preview/style.css' // [!code ++]
5
6export default {
7  extends: DefaultTheme,
8  enhanceApp({ app }) {
9    // 注册自定义全局组件
10    app.component('DemoPreview', DemoPreviewContainer) // [!code ++]
11  },
12} satisfies Theme

添加样式隔离 {#vp-raw}

配置详情参考 vitepress 自定义容器

1import { postcssIsolateStyles } from 'vitepress'
2
3export default {
4  plugins: [
5    postcssIsolateStyles({
6      includeFiles: [/base\.css/, /vp-doc\.css/],
7    })
8  ]
9}

🛠️ 配置 {#config}

root

• 类型: string
• 默认值: join(process.cwd(), 'examples')

示例文件所在的根目录，默认值为 /examples，文件目录结构如下：

1.
2├─ docs
3│  ├─ .vitepress
4│  │  ├─ theme
5│  │  │  └─ index.ts
6│  │  └─ config.ts
7│  └─ index.md
8├─ examples
9│  ├─ test.tsx
10│  └─ test.vue
11└─ package.json

::: tip 提示

如果需要修改根目录，请确保在 .vitepress/config.ts 中配置 root 选项。

1import { resolve } from 'node:path' // [!code ++]
2import { demoPreviewPlugin } from '@movk-repo/demo-preview' // [!code ++]
3import { defineConfig } from 'vitepress'
4
5export default defineConfig({
6  markdown: {
7    config: (md) => {
8      md.use(demoPreviewPlugin, {
9        root: resolve('./docs') // [!code ++]
10      })
11    },
12  },
13})

:::

marker

• 类型: string
• 默认值: ':'

容器标记符号，用于标识容器的开始和结束。

name

• 类型: string
• 默认值: demo

自定义容器名称，用于标识容器的类型。