工作原理

这个包出现的原因很直接：原始 Mermaid HTML 只解决了第一段工作，真正的文档站还需要挂载 重渲染 导出 缩放 全屏 与路由切换后的生命周期控制

它解决了什么

markdown-it 只负责把 fence 变成 HTML，不负责浏览器状态，不负责路由切换后的再初始化，也不会自带工具栏

markdown-it-mermaid-enhanced 把这部分工作拆成两段

1. markdown-it 插件把 Mermaid fence 改写成面向运行时的 wrapper
2. 浏览器运行时把 wrapper 升级成可交互的图表壳层

渲染管线

flowchart LR
  Source["Mermaid fence"] --> Parse["parseMermaidFenceOptions"]
  Parse --> Wrapper["wrapper HTML + data-mermaid-config"]
  Wrapper --> Mount["initMermaidIt 或 VitePress helper"]
  Mount --> Runtime["Vue wrapper runtime"]
  Runtime --> Engine["Mermaid.js 或 Excalidraw"]
  Runtime --> Tools["缩放 复制 导出 全屏"]

Loading diagram…

主包架构

flowchart LR
  subgraph Host["宿主应用"]
    Markdown["Markdown 源文"]
    MarkdownIt["markdown-it"]
    HostDom["浏览器或 VitePress 页面"]
  end

  subgraph Package["markdown-it-mermaid-enhanced"]
    Entry["src/index.ts<br/>公共插件入口"]
    Plugin["src/markdown-it/plugin.ts<br/>fence 解析与 wrapper HTML"]
    Runtime["src/runtime.ts<br/>运行时门面"]
    RuntimeVue["src/runtime/MermaidWrapperRuntime.vue<br/>运行时交互壳层"]
    RuntimeCore["src/runtime/core.ts<br/>渲染 导出 与缩放控制"]
    VitePressAdapter["src/vitepress.ts<br/>面向路由切换的适配层"]
    Shared["src/shared/*<br/>配置 主题 与类型"]
    Styles["src/styles.css<br/>wrapper 舞台 与工具栏样式"]
  end

  subgraph Engines["渲染引擎"]
    Mermaid["Mermaid.js"]
    Excalidraw["Excalidraw"]
  end

  Markdown --> MarkdownIt --> Entry --> Plugin --> HostDom
  HostDom --> Runtime --> RuntimeVue --> RuntimeCore
  VitePressAdapter --> Runtime
  Plugin -. data-mermaid-config .-> Shared
  RuntimeCore --> Shared
  RuntimeVue --> Styles
  RuntimeCore --> Mermaid
  RuntimeCore --> Excalidraw

Loading diagram…

这样拆分之后，编译期 HTML 生成 浏览器交互 共享配置 与 VitePress 接入边界会更清晰

工作流程图

sequenceDiagram
  autonumber
  participant Host as 宿主应用
  participant Plugin as markdown-it 插件
  participant Wrapper as Wrapper HTML
  participant Runtime as initMermaidIt 或 rerenderMermaidIt
  participant Vue as MermaidWrapperRuntime.vue
  participant Core as runtime/core.ts
  participant Engine as Mermaid.js 或 Excalidraw

  Host->>Plugin: 渲染带 mermaid fence 的 Markdown
  Plugin->>Plugin: 解析 fence 选项并合并配置
  Plugin->>Wrapper: 输出 wrapper HTML 与 data-mermaid-config
  Host->>Runtime: initMermaidIt(root)
  Runtime->>Vue: 为每个 wrapper 挂载一个运行时实例
  Vue->>Core: 读取 wrapper 快照
  Core->>Core: 解析主题 字体 与渲染引擎
  Core->>Engine: 渲染 Mermaid 源码
  Engine-->>Core: 返回 SVG
  Core-->>Vue: 挂载 SVG 与缩放控制器
  Vue-->>Wrapper: 同步工具栏 加载态 报错态 与全屏态
  Host->>Runtime: 当 DOM 或配置变化时触发 rerenderMermaidIt(root)

Loading diagram…

关键边界在于 markdown-it 侧只负责序列化状态，运行时侧才负责异步渲染与交互状态

插件实际输出了什么

每张图都会变成一层 wrapper，核心元素有三块

• 隐藏的 <pre>，负责保留原始 Mermaid 源码
• data-mermaid-config，负责携带解析后的配置
• 默认工具栏，负责缩放 复制 导出 与全屏

这套结构的意义在于原地重渲染，而不是整块替换 DOM

运行时模型

浏览器运行时会按需把 wrapper 升级成 Vue 应用

• initMermaidIt() 查找未挂载 wrapper，并只挂载一次
• rerenderMermaidIt() 重新读取 wrapper 状态，再原地刷新
• 缩放状态与 wrapper 绑在一起，所以纯配置刷新时可以保住当前视口

运行时设计图

flowchart TD
  Wrapper["Wrapper 元素<br/>data-mermaid-config"] --> Snapshot["readWrapperSnapshot"]
  Snapshot --> State["config ref 与 diagramCode ref"]
  State --> Queue["queueRender"]
  Queue --> Theme["resolveTheme 与 syncWrapperClasses"]
  Theme --> Engine{renderEngine}
  Engine -->|mermaidjs| MermaidRender["renderMermaidSvg"]
  Engine -->|excalidraw| ExcalidrawRender["renderExcalidrawSvg"]
  MermaidRender --> Mount["mountSvgIntoHost"]
  ExcalidrawRender --> Mount
  Mount --> PanZoom["createPanZoom 或 setSvgEl"]
  PanZoom --> Toolbar["工具栏动作"]
  Toolbar --> PanZoom
  Toolbar --> Export["复制 SVG PNG 全屏"]
  Queue --> Feedback["加载态 与 报错态"]
  Feedback --> Wrapper

Loading diagram…

每个 wrapper 都会保留一份很小的运行时状态，这样重渲染时可以原地替换 SVG，而不是销毁整个宿主节点

为什么路由切换需要额外处理

单页文档框架切换页面时不会重载整个浏览器环境，所以新的 wrapper 需要在路由切换后重新发现并挂载

VitePress helper 的工作就是等待 DOM 更新 重试 wrapper 发现 然后再执行挂载

关键源码

• src/markdown-it/plugin.ts 负责 fence 解析与 wrapper HTML
• src/runtime.ts 负责公开运行时入口
• src/runtime/MermaidWrapperRuntime.vue 负责交互壳层
• src/runtime/core.ts 负责渲染 导出 SVG 挂载 与缩放控制
• src/vitepress.ts 负责把运行时接入 VitePress 路由