组件预览与展示代码

专为增强 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` 被元素加 `ElTooltip` 组件内部使用的示例

/basic/non-ssr.vue

:::

这是一个Teleport 被元素加 ElTooltip 组件内部使用的示例

<script lang="ts" setup>
</script>

<template>
  <ElTooltip content="the tooltip content">
    <ElButton>hover to show tooltip</ElButton>
  </ElTooltip>
</template>

<style>
</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 lang="ts" setup>
</script>

<template>
  <ElTooltip content="the tooltip content">
    <ElButton>hover to show tooltip</ElButton>
  </ElTooltip>
</template>

<style>
</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)

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

1.1.0 (2024-09-13)

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.1 (2024-09-23)

Performance Improvements

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

1.1.0 (2024-09-18)

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