非标准图形

如果输入文本本身不是有效的 Mermaid 语法，markdown-it-mermaid-enhanced 就不能直接渲染，因为无论是 Mermaid 渲染还是 Excalidraw 渲染，入口都仍然是 Mermaid 兼容输入

不过像“盒子加箭头加标签”这一类图，依然有几条实际可用的路径

改写成标准 Mermaid

很多看起来像自定义 DSL 的图，实际上都可以翻译成标准 Mermaid 的节点和连线

flowchart TB
  Background["后台线程<br/>Vue 3 runtime • reactivity • lifecycle • app logic"]
  Main["主线程<br/>Native elements • layout • rendering • event handlers"]
  Background -->|ops| Main
  Main -->|events| Background

Loading diagram…

这条路最直接，也最稳定

切到 Excalidraw 渲染风格

renderEngine: 'excalidraw' 可以把 Mermaid 图画成更接近手绘的风格，但它不会让任意非 Mermaid 语法自动变成可解析输入

flowchart TB
  Background["后台线程<br/>Vue 3 runtime • reactivity • lifecycle • app logic"]
  Main["主线程<br/>Native elements • layout • rendering • event handlers"]
  Background -->|ops| Main
  Main -->|events| Background

Loading diagram…

这条路适合 Mermaid 语法已经成立，但视觉气质希望更粗粝的场景

先把自定义 DSL 预处理成 Mermaid

如果团队已经有自己的图形文本格式，可以在 markdown-it-mermaid-enhanced 前面加一层预处理插件，把自定义语法重写成 Mermaid fence

import { defineConfig } from 'vitepress'
import markdownItMermaidEnhanced from 'markdown-it-mermaid-enhanced'

function customDiagramPlugin(md: any) {
  md.core.ruler.before('normalize', 'custom-diagram-rewrite', (state) => {
    // 检测自定义语法并重写成 Mermaid fence
  })
}

export default defineConfig({
  markdown: {
    config: (md) => {
      md.use(customDiagramPlugin)
      md.use(markdownItMermaidEnhanced)
    },
  },
})

4 回退到 SVG 或 PNG 资源

如果排版规则完全不适合 Mermaid，最稳妥的方式仍然是先在别处产出图，再作为资源嵌入

![线程关系图](/images/worker-threading-overview.svg)

选择规则

结构本身兼容 Mermaid：优先改写成 Mermaid
结构兼容 Mermaid，但视觉想更像草图：切到 Excalidraw
团队已有稳定 DSL：增加预处理层
版式完全超出 Mermaid 能力：回退到静态资源

非标准图形 ​

改写成标准 Mermaid ​

切到 Excalidraw 渲染风格 ​

先把自定义 DSL 预处理成 Mermaid ​

4 回退到 SVG 或 PNG 资源 ​