在 Markdown 使用 Vue

在 VitePress 中，每个 Markdown 文件都被编译成 HTML，而且将其作为 Vue 单文件组件处理。这意味着可以在 Markdown 中使用任何 Vue 功能，包括动态模板、使用 Vue 组件或通过添加 <script> 标签为页面的 Vue 组件添加逻辑。

值得注意的是，VitePress 利用 Vue 的编译器自动检测和优化 Markdown 内容的纯静态部分。静态内容被优化为单个占位符节点，并从页面的 JavaScript 负载中删除以供初始访问。在客户端激活期间也会跳过它们。简而言之，只需注意任何给定页面上的动态部分。

SSR 兼容性

所有的 Vue 用法都需要兼容 SSR。

模板化

插值语法

每个 Markdown 文件首先被编译成 HTML，然后作为 Vue 组件传递给 Vite 流程管道。这意味着可以在文本中使用 Vue 的插值语法：

输入

{{ 1 + 1 }}

输出

2

指令

也可以使用指令 (请注意，原始 HTML 在 Markdown 中也有效):

输入

<span v-for="i in 3">{{ i }}</span>

输出

1 2 3 

<script> 和 <style>

Markdown 文件中的根级 <script> 和 <style> 标签与 Vue SFC 中的一样，包括 <script setup>、<style module> 等。这里的主要区别是没有 <template> 标签：所有其他根级内容都是 Markdown。另请注意，所有标签都应放在 frontmatter 之后：

---
hello: world
---

<script setup>
  import { ref } from 'vue'

  const count = ref(0)
</script>

## Markdown Content The count is: {{ count }}

<button :class="$style.button" @click="count++">Increment</button>

<style module>
  .button {
    color: red;
    font-weight: bold;
  }
</style>

避免在 Markdown 中使用 <style scoped>

在 Markdown 中使用时，<style scoped> 需要为当前页面的每个元素添加特殊属性，这将显著增加页面的大小。当我们需要局部范围的样式时 <style module> 是首选。

输入

<script setup>
  import { useData } from 'vitepress'

  const { page } = useData()
</script>

<pre>{{ page }}</pre>

输出

{
  "path": "/using-vue.html",
  "title": "Using Vue in Markdown",
  "frontmatter": {},
  ...
}

使用组件

可以直接在 Markdown 文件中导入和使用 Vue 组件。

在 Markdown 中导入组件

如果一个组件只被几个页面使用，建议在使用它们的地方显式导入它们。这使它们可以正确地进行代码拆分，并且仅在显示相关页面时才加载：

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

# Docs

This is a .md using a custom component

<CustomComponent />

## More docs

...

注册全局组件

如果一个组件要在大多数页面上使用，可以通过自定义 Vue 实例来全局注册它们。

重要

确保自定义组件的名称包含连字符或采用 PascalCase。否则，它将被视为内联元素并包裹在 <p> 标签内，这将导致激活不匹配，因为 <p> 不允许将块元素放置在其中。

在标题中使用组件

可以在标题中使用 Vue 组件，但请注意以下语法之间的区别：

Markdown	输出的 HTML	被解析的标题
# text <Tag/>	<h1>text <Tag/></h1>	text
# text `<Tag/>`	<h1>text <code>&lt;Tag/&gt;</code></h1>	text <Tag/>

被 <code> 包裹的 HTML 将按原样显示，只有未包裹的 HTML 才会被 Vue 解析。

TIP

输出 HTML 由 Markdown-it 完成，而解析的标题由 VitePress 处理 (并用于侧边栏和文档标题)。

转义

可以通过使用 v-pre 指令将它们包裹在 <span> 或其他元素中来转义 Vue 插值：

输入

This <span v-pre>{{ will be displayed as-is }}</span>

输出

This {{ will be displayed as-is }}

也可以将整个段落包装在 v-pre 自定义容器中：

::: v-pre
{{ This will be displayed as-is }}`
:::

输出

{{ This will be displayed as-is }}

代码块中不转义

默认情况下，代码块是受到保护的，都会自动使用 v-pre 包装，因此内部不会处理任何 Vue 语法。要在代码块内启用 Vue 插值语法，可以在代码语言后附加 -vue 后缀，例如 js-vue：

输入

```js-vue
Hello {{ 1 + 1 }}
```

输出

Hello 2

请注意，这可能会让某些字符不能正确地进行语法高亮显示。