@movk-repo/demo-preview v1.1.0

组件预览与展示代码 {#start}

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

在线示例

更新日志

✨ 特点 {#features}

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

📦 安装 {#install}

::: code-group

pnpm add @movk-repo/demo-preview

npm add @movk-repo/demo-preview

yarn add @movk-repo/demo-preview

:::

🚀 使用 {#usage}

添加插件 {#plugin}

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

import { demoPreviewPlugin } from '@movk-repo/demo-preview' // [!code ++]
import { defineConfig } from 'vitepress'

export default defineConfig({
  markdown: {
    config: (md) => {
      md.use(demoPreviewPlugin) // [!code ++]
    },
  },
})

注册容器组件 {#container}

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

• 如何在 VitePress 中注册组件

import type { Theme } from 'vitepress'
import { DemoPreviewContainer } from '@movk-repo/demo-preview/container' // [!code ++]
import DefaultTheme from 'vitepress/theme'
import '@movk-repo/demo-preview/style.css' // [!code ++]

export default {
  extends: DefaultTheme,
  enhanceApp({ app }) {
    // 注册自定义全局组件
    app.component('DemoPreview', DemoPreviewContainer) // [!code ++]
  },
} satisfies Theme

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

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

import { postcssIsolateStyles } from 'vitepress'

export default {
  plugins: [
    postcssIsolateStyles({
      includeFiles: [/base\.css/, /vp-doc\.css/],
    })
  ]
}

🛠️ 配置 {#config}

root

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

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

.
├─ docs
│  ├─ .vitepress
│  │  ├─ theme
│  │  │  └─ index.ts
│  │  └─ config.ts
│  └─ index.md
├─ examples
│  ├─ test.tsx
│  └─ test.vue
└─ package.json

::: tip 提示

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

import { resolve } from 'node:path' // [!code ++]
import { demoPreviewPlugin } from '@movk-repo/demo-preview' // [!code ++]
import { defineConfig } from 'vitepress'

export default defineConfig({
  markdown: {
    config: (md) => {
      md.use(demoPreviewPlugin, {
        root: resolve('./docs') // [!code ++]
      })
    },
  },
})

:::

marker

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

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

name

• 类型: string
• 默认值: demo

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