Vitepress 中使用 Vue 的完整指南

Vitepress 中使用 Vue 的完整指南

vitepress Vite & Vue powered static site generator. 项目地址: https://gitcode.com/gh_mirrors/vi/vitepress

前言

在 Vitepress 项目中，Markdown 文件不仅仅是静态文档，它们实际上是 Vue 单文件组件(SFC)的变体。这种设计使得我们可以在 Markdown 中直接使用 Vue 的各种功能，包括组件、动态模板和脚本逻辑。本文将全面介绍如何在 Vitepress 的 Markdown 文件中充分发挥 Vue 的能力。

基础概念

Markdown 与 Vue 的关系

Vitepress 处理 Markdown 文件的过程分为两个阶段：

1. 首先将 Markdown 转换为 HTML
2. 然后将生成的 HTML 作为 Vue 单文件组件处理

这意味着每个 Markdown 文件本质上就是一个 Vue 组件，只是没有显式的 <template> 标签部分。

静态内容优化

Vitepress 会自动识别和优化 Markdown 中的静态内容：

• 静态内容会被转换为单个占位节点
• 这些内容不会包含在初始 JavaScript 负载中
• 客户端 hydration 时会跳过这些静态部分

这种优化确保了只有动态部分才会产生运行时开销。

Vue 功能在 Markdown 中的使用

模板语法

插值表达式

可以直接在 Markdown 文本中使用 Vue 风格的插值：

当前时间是：{{ new Date().toLocaleTimeString() }}

指令

Vue 指令也可以直接使用：

<div v-if="Math.random() > 0.5">
  你有50%的几率看到这段文字
</div>

脚本与样式

<script> 标签

可以在 Markdown 中使用 <script> 标签，支持所有 Vue SFC 中的特性，包括 <script setup>：

<script setup>
import { ref } from 'vue'
const count = ref(0)
</script>

计数器: {{ count }}

<button @click="count++">增加</button>

<style> 标签

同样支持 <style> 标签，包括模块化样式：

<style module>
.red {
  color: red;
}
</style>

<span :class="$style.red">红色文字</span>

重要提示：避免在 Markdown 中使用 <style scoped>，因为它会为页面所有元素添加特殊属性，显著增加页面体积。推荐使用 <style module> 替代。

组件使用

局部导入组件

在需要的地方直接导入组件：

<script setup>
import MyComponent from '../components/MyComponent.vue'
</script>

<MyComponent />

全局注册组件

对于频繁使用的组件，可以在主题配置中全局注册：

// .vitepress/theme/index.js
import DefaultTheme from 'vitepress/theme'
import MyComponent from '../components/MyComponent.vue'

export default {
  extends: DefaultTheme,
  enhanceApp({ app }) {
    app.component('MyComponent', MyComponent)
  }
}

命名规范：组件名称必须包含连字符或使用 PascalCase，否则会被当作内联元素处理，可能导致 hydration 不匹配。

标题中的组件

在标题中使用组件需要注意语法差异：

| Markdown 语法 | 解析结果 | 注意事项 | |--------------|---------|---------| | # 文本 <Tag/> | 标题包含 Vue 组件 | 仅显示文本部分 | | # 文本 \ `` | 标题包含代码片段 | 完整显示 |

转义处理

禁用 Vue 解析

使用 v-pre 指令可以跳过 Vue 解析：

<span v-pre>{{ 这里的内容不会被解析 }}</span>

或者对整个段落使用：

::: v-pre
{{ 这里的内容不会被解析 }}
:::

代码块中的 Vue

默认情况下，代码块会自动使用 v-pre。要启用 Vue 解析，添加 -vue 后缀：

```js-vue
// 这里可以使用 Vue 语法
const message = '{{ hello }}'
```

高级功能

CSS 预处理器

Vitepress 内置支持主流 CSS 预处理器，只需安装相应依赖：

# Sass/SCSS
npm install -D sass

# Less
npm install -D less

# Stylus
npm install -D stylus

使用示例：

<style lang="scss">
$primary: #42b983;
.title {
  color: $primary;
}
</style>

Teleport 使用

Vitepress 目前仅支持将内容传送到 body 的 SSG 场景。如需传送到其他目标，有两种解决方案：

1. 使用 <ClientOnly> 包装：

<ClientOnly>
  <Teleport to="#target">
    <div>传送内容</div>
  </Teleport>
</ClientOnly>

2. 使用 postRender 钩子手动处理

运行时 API

可以访问 Vitepress 提供的运行时 API，如 useData：

<script setup>
import { useData } from 'vitepress'
const { page } = useData()
</script>

当前页面路径: {{ page.path }}

最佳实践

1. 组件导入策略：仅在需要的地方导入组件，优化代码分割
2. 样式处理：优先使用 CSS Modules 而非 scoped styles
3. 性能优化：合理使用静态内容，减少不必要的动态部分
4. SSR 兼容：确保所有 Vue 用法都兼容服务器端渲染

通过合理利用这些特性，你可以在 Vitepress 文档中创建出既内容丰富又交互性强的页面，同时保持良好的性能表现。

vitepress Vite & Vue powered static site generator. 项目地址: https://gitcode.com/gh_mirrors/vi/vitepress