文档站与 VitePress 集成
当你在做文档站、知识库、官网内容页，或者任何“Markdown 主要作为稳定页面内容来展示，而不是像聊天那样持续流式变化”的场景时，就走这条路径。
这页的目标是一次解决 VitePress 用户最常见的几个连环问题：
- 我该用
content还是nodes MarkdownRender和自定义节点该注册到哪里enhanceApp应该怎么用markstream-vue/index.css该放在哪thinking这类可信标签在文档页里怎么接
1. 除非你已经拥有 AST，否则优先用 content
对文档站来说，content 通常就是更合适的默认值：
| 场景 | 推荐输入 |
|---|---|
| Markdown 来自页面内容、CMS 字段或普通文档页 | content |
| 你已经在服务端或内容流水线里预解析好了 | nodes |
| 你做的是实时流式输出或 AI 聊天 | 改走 AI 聊天与流式输出 |
2. 先装一套适合文档站的最小依赖
bash
pnpm add markstream-vue shiki stream-markdown这套组合很适合作为文档站默认值：基础 Markdown 渲染，加上轻量代码高亮。
只有真的需要时再继续补：
mermaid：Mermaid 图表katex：数学公式stream-monaco：Monaco 代码块
3. 在 enhanceApp 中注册渲染器和自定义节点
对 VitePress 来说，最稳妥的全局接入位置通常是 docs/.vitepress/theme/index.ts。
ts
// docs/.vitepress/theme/index.ts
import DefaultTheme from 'vitepress/theme'
import MarkdownRender, { setCustomComponents } from 'markstream-vue'
import ThinkingNode from './components/ThinkingNode.vue'
import './style.css'
export default {
extends: DefaultTheme,
enhanceApp({ app }) {
app.component('MarkdownRender', MarkdownRender)
setCustomComponents('docs', {
thinking: ThinkingNode,
})
},
}这样做的好处：
- Markdown 页面里可以直接使用
MarkdownRender，不用每页单独导入 - 文档站专用覆盖都能收口在
custom-id="docs"下 - 主题层配置集中管理，不会散落在各个页面里
4. 在文档页里渲染 Markdown
md
<script setup lang="ts">
const source = `
# Hello docs
<thinking>
这个块会被自定义 Vue 组件接管渲染。
</thinking>
`
</script>
<MarkdownRender
custom-id="docs"
:content="source"
:custom-html-tags="['thinking']"
/>这里有三个关键点：
custom-id="docs"用来把覆盖范围限制在文档站custom-html-tags告诉解析器把标签变成真正的自定义节点，而不是原样输出 HTML- 对普通文档内容来说，
content比手动维护nodes更简单
5. 把 CSS 放到可预期的位置
如果你的文档主题有自己的样式文件，推荐在主题样式里引入 markstream-vue/index.css，并确保它位于 reset 或基础层之后。
css
/* docs/.vitepress/theme/style.css */
@layer components {
@import 'markstream-vue/index.css';
}
[data-custom-id='docs'] .prose {
max-width: 72ch;
}实用规则：
- 站点有 reset，就先加载 reset，再加载这里
- 如果你用了 Tailwind / UnoCSS，把它放进
@layer components - 如果你启用了 KaTeX，还要额外引入
katex/dist/katex.min.css
深入看： Tailwind 集成与样式顺序
6. thinking 这类可信标签的推荐接法
对文档页来说，推荐流程仍然是：
- 用
custom-html-tags声明标签 - 用
setCustomComponents('docs', mapping)注册对应渲染器 - 让页面渲染器始终带着
custom-id="docs"
大多数情况下这就够了。只有当源格式本身需要改 AST，而不只是换个组件渲染时，才需要 parser hooks。
深入看： 自定义标签与高级组件、API 参考
7. 文档站里最常见的几个坑
- 自定义标签被当成原生 HTML：少了
custom-html-tags - 组件一直没生效：没有在
enhanceApp注册，或映射 key 和标签名不一致 - 样式错乱：CSS 导入顺序不对，或者被 utility layer 覆盖
- 覆盖影响到别的页面：用了全局映射，没有通过
custom-id限定作用域 - Mermaid 或 Monaco 在 SSR 类环境里异常：继续看对应专题页和客户端边界说明
如果页面布局或样式还是不对，先从这里排： 故障排除
下一步继续看
- 安装：选 peer 依赖
- 使用与流式渲染：理解
contentvsnodes - 自定义标签与高级组件：处理嵌套标签和更复杂场景
- Tailwind 集成与样式顺序：处理 utility CSS 技术栈
- 故障排除：继续排样式、peers 和 SSR