npm package: @movk-repo/demo-preview
Description: vitepress 插件，用于预览 markdown 文件
Author: yixuan
Latest version: 1.1.0

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

<VPBadges name="@movk-repo/demo-preview" />

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

[在线示例](https://mhaibaraai.github.io/zh/demo-preview/start)

[更新日志](https://mhaibaraai.github.io/zh/demo-preview/changelog)

## ✨ 特点 {#features}

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

## 📦 安装 {#install}

::: code-group

```sh [pnpm]
pnpm add @movk-repo/demo-preview
```

```sh [npm]
npm add @movk-repo/demo-preview
```

```sh [yarn]
yarn add @movk-repo/demo-preview
```

:::

## 🚀 使用 {#usage}

### 添加插件 {#plugin}

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

```ts twoslash [.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 中注册组件](https://vitepress.dev/zh/guide/extending-default-theme#registering-global-components)

```ts twoslash [.vitepress/theme/index.ts]
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 自定义容器](https://vitepress.dev/zh/guide/markdown#raw)

```ts twoslash [docs/postcss.config.mjs]
import { postcssIsolateStyles } from 'vitepress'

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

## 🛠️ 配置 {#config}

### root

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

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

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

::: tip 提示

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

```ts twoslash [.vitepress/config.ts]
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`

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