VitePress 集成

VitePress 最容易忽略的部分就是图表生命周期，Markdown 渲染发生在路由切换里，而不是整页刷新里，所以 wrapper 发现与挂载必须能跨路由工作

最小接线

// docs/.vitepress/config.ts
import { defineConfig } from 'vitepress'
import markdownItMermaidEnhanced from 'markdown-it-mermaid-enhanced'

export default defineConfig({
  markdown: {
    config: (md) => {
      md.use(markdownItMermaidEnhanced, {
        theme: 'auto',
        renderEngine: 'mermaidjs',
      })
    },
  },
})

// docs/.vitepress/theme/index.ts
import type { Theme } from 'vitepress'
import DefaultTheme from 'vitepress/theme'
import 'markdown-it-mermaid-enhanced/styles.css'
import mermaidPlugin from 'markdown-it-mermaid-enhanced/vitepress'

export default {
  extends: DefaultTheme,
  enhanceApp(ctx) {
    mermaidPlugin(ctx, {
      waitFor: 'animation-frame',
    })
  },
} satisfies Theme

Helper 实际做了什么

• 在加载浏览器运行时前关闭自动初始化
• 在页面切换后等待 DOM 更新
• 在页面仍处于挂载期时重试 wrapper 发现
• 对当前 root 执行 initMermaidIt()

可选参数

字段	类型	说明
root	ParentNode | string | () => ParentNode | null	限定渲染范围
waitFor	'animation-frame' | 'microtask'	指定等待的 DOM 更新边界

作用域渲染

mermaidPlugin(ctx, {
  root: '.VPDoc',
  waitFor: 'animation-frame',
})

这个模式适合含有其他运行时岛屿的页面布局