unplugin-vue-markdown 将 .md 文件编译为 Vue 组件，支持在路由中直接使用 Markdown 文件作为页面，并可在 Markdown 中嵌入 Vue 组件。本文讲解其配置方式和实际应用场景。
pnpm add -D unplugin-vue-markdown markdown-it// vite.config.ts
import Markdown from 'unplugin-vue-markdown/vite'
export default defineConfig({
plugins: [
vue(),
Markdown({
// markdown-it 配置
markdownItOptions: {
html: true,
linkify: true,
typographer: true,
},
}),
],
})// src/types/shims.d.ts
declare module '*.md' {
import type { ComponentOptions } from 'vue'
const component: ComponentOptions
export default component
}<script setup lang="ts">
import Readme from '../README.md'
</script>
<template>
<Readme />
</template>将 .md 文件放入 pages 目录，自动生成路由：
// vite.config.ts
Pages({
extensions: ['vue', 'md'], // 支持 md 文件
})src/pages/
├── index.vue
├── about.md → /about
└── docs/
└── guide.md → /docs/guide# 文档标题
这是一段 Markdown 内容。
<!-- 直接使用 Vue 组件 -->
<DemoCounter />
<Alert type="warning">
这是一条警告信息
</Alert>
## 代码示例
```vue
<script setup>
const msg = ref('Hello')
</script>
```import MarkdownIt from 'markdown-it'
import anchor from 'markdown-it-anchor'
import toc from 'markdown-it-toc-done-right'
Markdown({
markdownItSetup(md: MarkdownIt) {
md.use(anchor, { permalink: true })
md.use(toc)
},
})pnpm add -D shikiimport Shiki from '@shikijs/markdown-it'
Markdown({
markdownItSetup(md) {
md.use(Shiki({ theme: 'github-dark' }))
},
})| 场景 | 说明 |
|---|---|
| 文档站点 | Markdown 写文档，Vue 组件做交互演示 |
| 博客系统 | Markdown 写文章，支持自定义组件 |
| 项目 README 展示 | 将 README.md 渲染为页面 |
| 变更日志 | CHANGELOG.md 作为页面展示 |
Q: Markdown 中的 Vue 组件需要注册吗？
如果配置了 unplugin-vue-components 自动导入，则无需手动注册。否则需要在 Markdown 文件的 <script> 块中手动导入。
Q: 支持 MDX 语法吗？
unplugin-vue-markdown 使用 markdown-it 引擎，语法与 MDX（基于 remark）不同。如需 MDX 生态，考虑使用 @mdx-js/vue。