组件预览与展示代码

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

✨ 特点

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

📦 安装

包名	版本
@movk-repo/demo-preview-plugin
@movk-repo/demo-preview-container

推荐使用 pnpm 安装，以获得更快的安装速度。

pnpm add @movk-repo/demo-preview-plugin @movk-repo/demo-preview-container

🚀 使用

添加插件

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

import { demoPreviewPlugin } from '@movk-repo/demo-preview-plugin'
import { defineConfig } from 'vitepress'

export default defineConfig({
  markdown: {
    config: (md) => {
      md.use(demoPreviewPlugin)
    },
  },
})

注册容器组件

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

• 如何在 VitePress 中注册组件

import { DemoPreviewContainer } from '@movk-repo/demo-preview-container'
import { EnhanceAppContext } from 'vitepress'
import DefaultTheme from 'vitepress/theme'
import '@movk-repo/demo-preview-container/dist/style.css'

export default {
  extends: DefaultTheme,
  async enhanceApp({ app }: EnhanceAppContext) {
    app.component('DemoPreview', DemoPreviewContainer)
  },
}

🛠️ 配置

marker

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

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

root

• 类型: string
• 默认值: /examples

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

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

name

• 类型: string
• 默认值: demo

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

📝 示例

Vue 组件

::: demo 这是一个预览 `Vue` 组件简介的示例

/basic/counter.vue

:::

这是一个预览 Vue 组件简介的示例

Count: 0

<script lang="ts" setup>
import { ref } from 'vue'

const count = ref(0)
const increment = () => count.value++
</script>

<template>
  <div>
    <p>Count: {{ count }}</p>
    <button :class="$style.modalButton" @click="increment">
      Increment
    </button>
  </div>
</template>

<style module>
.modalButton {
  padding: 4px 8px;
  border-radius: 4px;
  border-color: var(--vp-button-alt-border);
  color: var(--vp-button-alt-text);
  background-color: var(--vp-button-alt-bg);
}
</style>

隐藏源代码

TypeScript 组件

::: demo 这是一个预览 `TypeScript` 组件的示例

/basic/counter.tsx

:::

这是一个预览 TypeScript 组件的示例

Count：0

import { defineComponent, ref } from 'vue'
import './counter.css'

export default defineComponent({
  setup() {
    const counter = ref(0)
    return () => (
      <div>
        <p>
          Count：
          {counter.value}
        </p>
        <button class="modal-button" onClick={() => counter.value++}>Increment</button>
      </div>
    )
  },
})

隐藏源代码

兼容非 SSR 组件

::: demo 使用 `teleport` 传递组件内容的示例

/basic/non-ssr.vue

:::

使用 teleport 传递组件内容的示例

<script setup lang="ts">
const showModal = ref(false)
</script>

<template>
  <button class="modal-button" @click="showModal = true">
    Show Modal
  </button>

  <Teleport to="body">
    <Transition name="modal">
      <div v-show="showModal" class="modal-mask">
        <div class="modal-container">
          <p>Hello from the modal!</p>
          <div class="model-footer">
            <button class="modal-button" @click="showModal = false">
              Close
            </button>
          </div>
        </div>
      </div>
    </Transition>
  </Teleport>
</template>

<style scoped>
.modal-mask {
  position: fixed;
  z-index: 200;
  top: 0;
  left: 0;
  width: 100%;
  height: 100%;
  background-color: rgba(0, 0, 0, 0.5);
  display: flex;
  align-items: center;
  justify-content: center;
  transition: opacity 0.3s ease;
}

.modal-container {
  width: 300px;
  margin: auto;
  padding: 20px 30px;
  background-color: var(--vp-c-bg);
  border-radius: 2px;
  box-shadow: 0 2px 8px rgba(0, 0, 0, 0.33);
  transition: all 0.3s ease;
}

.model-footer {
  margin-top: 8px;
  text-align: right;
}

.modal-button {
  padding: 4px 8px;
  border-radius: 4px;
  border-color: var(--vp-button-alt-border);
  color: var(--vp-button-alt-text);
  background-color: var(--vp-button-alt-bg);
}

.modal-button:hover {
  border-color: var(--vp-button-alt-hover-border);
  color: var(--vp-button-alt-hover-text);
  background-color: var(--vp-button-alt-hover-bg);
}

.modal-enter-from,
.modal-leave-to {
  opacity: 0;
}

.modal-enter-from .modal-container,
.modal-leave-to .modal-container {
  transform: scale(1.1);
}
</style>

隐藏源代码

提示

当打包不支持 SSR 的组件时，需要在容器中添加 {ClientOnly} 选项，确保组件在客户端渲染。

本插件使用官方 ClientOnly 组件与 defineClientComponent 辅助函数。

详情请查看 VitePress 官方文档。

行高亮

• 配置语法参考 VitePress 官方文档：在代码块中实现行高亮

::: demo 这是一个行高亮的示例

<!-- 带行高亮 -->

/basic/counter.vue {1,4,10-13}

:::

这是一个行高亮的示例

Count: 0

<script lang="ts" setup>
import { ref } from 'vue'

const count = ref(0)
const increment = () => count.value++
</script>

<template>
  <div>
    <p>Count: {{ count }}</p>
    <button :class="$style.modalButton" @click="increment">
      Increment
    </button>
  </div>
</template>

<style module>
.modalButton {
  padding: 4px 8px;
  border-radius: 4px;
  border-color: var(--vp-button-alt-border);
  color: var(--vp-button-alt-text);
  background-color: var(--vp-button-alt-bg);
}
</style>

隐藏源代码

行号

• 配置语法参考 VitePress 官方文档：在代码块中显示行号

::: demo 这是一个行号的示例

<!-- 带行高亮与带行号 -->

/basic/counter.vue {1,4,10-13 vue:line-numbers=2 }

:::

这是一个行号的示例

Count: 0

<script lang="ts" setup>
import { ref } from 'vue'

const count = ref(0)
const increment = () => count.value++
</script>

<template>
  <div>
    <p>Count: {{ count }}</p>
    <button :class="$style.modalButton" @click="increment">
      Increment
    </button>
  </div>
</template>

<style module>
.modalButton {
  padding: 4px 8px;
  border-radius: 4px;
  border-color: var(--vp-button-alt-border);
  color: var(--vp-button-alt-text);
  background-color: var(--vp-button-alt-bg);
}
</style>

隐藏源代码

注意

行号使用时需添加语言，例如 {vue:line-numbers}

代码组

• 配置语法参考 VitePress 官方文档：代码组
• {code-group} 选项或文件路径数量大于 1 时，渲染代码组

::: demo 这是一个代码组的示例,`{code-group}` 非必传 {code-group ClientOnly}

<!-- 行号 ,自定义源语言-->

/basic/non-ssr.vue { vue 1,4}

<!-- 文件名默认用作标题,也可以自定义标题 -->

/basic/counter.vue {1,4,10-13 vue:line-numbers=2 } [counter标题]

<!-- 支持 Twoslash（类型悬停显示） -->

/basic/twoslash.ts { ts:line-numbers twoslash} [twoslash标题]

:::

这是一个代码组的示例，{code-group} 非必传

non-ssr.vue

<script setup lang="ts">
const showModal = ref(false)
</script>

<template>
  <button class="modal-button" @click="showModal = true">
    Show Modal
  </button>

  <Teleport to="body">
    <Transition name="modal">
      <div v-show="showModal" class="modal-mask">
        <div class="modal-container">
          <p>Hello from the modal!</p>
          <div class="model-footer">
            <button class="modal-button" @click="showModal = false">
              Close
            </button>
          </div>
        </div>
      </div>
    </Transition>
  </Teleport>
</template>

<style scoped>
.modal-mask {
  position: fixed;
  z-index: 200;
  top: 0;
  left: 0;
  width: 100%;
  height: 100%;
  background-color: rgba(0, 0, 0, 0.5);
  display: flex;
  align-items: center;
  justify-content: center;
  transition: opacity 0.3s ease;
}

.modal-container {
  width: 300px;
  margin: auto;
  padding: 20px 30px;
  background-color: var(--vp-c-bg);
  border-radius: 2px;
  box-shadow: 0 2px 8px rgba(0, 0, 0, 0.33);
  transition: all 0.3s ease;
}

.model-footer {
  margin-top: 8px;
  text-align: right;
}

.modal-button {
  padding: 4px 8px;
  border-radius: 4px;
  border-color: var(--vp-button-alt-border);
  color: var(--vp-button-alt-text);
  background-color: var(--vp-button-alt-bg);
}

.modal-button:hover {
  border-color: var(--vp-button-alt-hover-border);
  color: var(--vp-button-alt-hover-text);
  background-color: var(--vp-button-alt-hover-bg);
}

.modal-enter-from,
.modal-leave-to {
  opacity: 0;
}

.modal-enter-from .modal-container,
.modal-leave-to .modal-container {
  transform: scale(1.1);
}
</style>

counter标题

<script lang="ts" setup>
import { ref } from 'vue'

const count = ref(0)
const increment = () => count.value++
</script>

<template>
  <div>
    <p>Count: {{ count }}</p>
    <button :class="$style.modalButton" @click="increment">
      Increment
    </button>
  </div>
</template>

<style module>
.modalButton {
  padding: 4px 8px;
  border-radius: 4px;
  border-color: var(--vp-button-alt-border);
  color: var(--vp-button-alt-text);
  background-color: var(--vp-button-alt-bg);
}
</style>

twoslash标题

import type { EnhanceAppContext } from 'vitepress'
import TwoslashFloatingVue from '@shikijs/vitepress-twoslash/client'
import '@shikijs/vitepress-twoslash/style.css'

export default {
  enhanceApp({ app }: EnhanceAppContext) {
    app.use(TwoslashFloatingVue)
  },
}

隐藏源代码

注意

仅渲染第一个代码块的组件。

🗓️ 更新日志

plugin

### 1.1.3 (2024-09-24)

**Performance Improvements**

- 恢复 README.md

### 1.1.2 (2024-09-23)

**Performance Improvements**

- 代码逻辑优化
- README.md 更新

### 1.1.1 (2024-09-18)

**Improvements**

- 简化了 `Plugin` 插件的代码组判断：当携带参数 `code-group` 或文件路径数量大于 1 时，渲染代码组

### 1.1.0 (2024-09-13)

**New Features**

- 添加 `VitePress` 默认扩展支持
- 支持 VitePress 的 `行内语法高亮` 、`代码行号` 及 `代码组` 功能，提升文档的可读性和交互性

### 1.0.2 (2024-09-10)

**Bug Fixes**

- 将 `description` 改为组件引用，由 VitePress 渲染

### 1.0.1 (2024-09-06)

**Performance Improvements**

- 更新了 README.md

### 1.0.0 (2024-09-01)

**Initial release**

container

### 1.1.2 (2024-10-14)

**Bug Fixes**

- 修复了 `message` 组件的初始高度问题

### 1.1.1 (2024-09-23)

**Performance Improvements**

- 代码逻辑优化
- README.md 更新

### 1.1.0 (2024-09-18)

**New Features**

- 添加 `VitePress` 默认扩展支持，删除多余代码

### 1.0.2 (2024-09-13)

**Bug Fixes**

- 将 `description` 改为组件引用，由 VitePress 渲染

### 1.0.1 (2024-09-06)

**Performance Improvements**

- 更新了 README.md

### 1.0.0 (2024-09-01)

**Initial release**