VitePress 的 Markdown 文件天然支持 Vue 语法，包括 <script setup>，每个 .md 文件被当作 Vue 单文件组件处理，无需额外配置即可内联定义和使用自定义组件。
VitePress 的 Markdown 文件天然支持 Vue 语法，包括 <script setup> —— 因为每个 .md 文件在构建时会被当作一个 Vue 单文件组件（SFC）处理。你不需要额外配置，就能在 Markdown 中直接定义并使用带 script setup 的自定义组件。
在 .md 文件中内联定义组件
直接在 Markdown 文件顶部或任意位置用 <script setup> 声明组件逻辑和响应式数据，再用 <template> 渲染结构。VitePress 会自动识别并编译：
- 组件必须写在 Markdown 内容之外（推荐放在文件开头或结尾），不能嵌套在段落、列表等 Markdown 解析上下文中
-
<script setup>和<template>必须成对出现，且不能跨多个代码块 - 支持
defineProps、defineEmits、组合式 API 及顶层import
示例：
<script setup>
import { ref } from 'vue'
const count = ref(0)
const increment = () => count.value++
</script>
<p><template>
<button @click="increment">点击 {{ count }} 次</button>
</template></p><hr /><p>上面就是一个可交互的按钮，它就定义在当前 Markdown 文件里。
在 Markdown 中使用已注册的全局/局部组件
如果你已在项目中全局注册了组件（如通过 app.component()），或在当前 .md 文件中通过 <script setup> 显式 import 并使用，就能直接在 Markdown 正文中调用：
立即学习“前端免费学习笔记（深入）”；
- 确保组件名符合 PascalCase（如
MyCard），并在 Markdown 中用 kebab-case 使用（<my-card></my-card>） - 支持 props 传递、事件绑定、插槽内容（包括默认插槽和具名插槽）
- 注意：Markdown 解析器默认会把
<my-card>...当作 HTML 标签处理，所以需开启 VitePress 的markdown.html配置（默认已启用）
例如，在 docs/guide.md 中：
import MyCard from '../components/MyCard.vue' <p><MyCard title="Vue + Markdown"> 这段文字会作为默认插槽内容传入。 </MyCard>
渲染含 Vue 组件的 Markdown 内容（非 VitePress 场景）
若你不是用 VitePress，而是用 markdown-it 或 marked 在普通 Vue 组件中渲染 Markdown 字符串，那原生不支持 <script setup>。此时要让自定义组件生效，需走「运行时挂载」方案：
- 先用
markdown-it解析 Markdown，开启html: true，使自定义标签（如<my-button>）保留在输出 HTML 中 - 在渲染后的 DOM 节点中，查找这些自定义标签，用
createApp()手动挂载对应 Vue 组件到该节点 - 适合轻量场景；复杂交互建议改用 VitePress 或封装专用 Markdown 渲染器（如基于 remark/rehype）
注意事项与避坑点
常见问题多源于作用域和解析顺序：
- 不要在 Markdown 列表项或段落内部写
<script setup>—— 它不会被识别，会被当作普通文本或解析错误 - 组件中使用的响应式数据无法通过 Markdown 前置元数据（frontmatter）直接注入，需在
<script setup>内主动读取useData()（VitePress）或defineProps - 样式隔离需手动处理：
<style scoped>在.md文件中有效，但仅作用于该组件自身，不影响 Markdown 解析出的普通 HTML 元素 - SSR 场景下，确保组件无浏览器专属 API（如
window），否则构建报错
