How it works

The package exists because raw Mermaid HTML is only the first half of the job. A real docs site still needs hydration, rerendering, export, zoom, fullscreen, and route-aware lifecycle control

The problem it solves

markdown-it turns a fence into HTML. It does not keep browser state, rerender on route changes, or provide a toolbar

markdown-it-mermaid-enhanced fills that gap in two stages

1. The markdown-it plugin converts each Mermaid fence into a runtime-friendly wrapper
2. The browser runtime upgrades that wrapper into an interactive diagram shell

The pipeline

flowchart LR
  Source["Mermaid fence"] --> Parse["parseMermaidFenceOptions"]
  Parse --> Wrapper["wrapper HTML + data-mermaid-config"]
  Wrapper --> Mount["initMermaidIt or VitePress helper"]
  Mount --> Runtime["Vue wrapper runtime"]
  Runtime --> Engine["Mermaid.js or Excalidraw"]
  Runtime --> Tools["zoom copy export fullscreen"]

Loading diagram…

Package architecture

flowchart LR
  subgraph Host["Host application"]
    Markdown["Markdown source"]
    MarkdownIt["markdown-it"]
    HostDom["Browser or VitePress page"]
  end

  subgraph Package["markdown-it-mermaid-enhanced"]
    Entry["src/index.ts<br/>public plugin entry"]
    Plugin["src/markdown-it/plugin.ts<br/>fence parsing + wrapper HTML"]
    Runtime["src/runtime.ts<br/>runtime facade"]
    RuntimeVue["src/runtime/MermaidWrapperRuntime.vue<br/>runtime UI shell"]
    RuntimeCore["src/runtime/core.ts<br/>rendering + export + pan or zoom"]
    VitePressAdapter["src/vitepress.ts<br/>route-aware adapter"]
    Shared["src/shared/*<br/>config + themes + types"]
    Styles["src/styles.css<br/>wrapper + stage + toolbar styles"]
  end

  subgraph Engines["Rendering 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…

This split keeps compile-time HTML generation browser-side interactivity shared config resolution and VitePress integration clearly separated

Rendering workflow

sequenceDiagram
  autonumber
  participant Host as Host app
  participant Plugin as markdown-it plugin
  participant Wrapper as Wrapper HTML
  participant Runtime as initMermaidIt or rerenderMermaidIt
  participant Vue as MermaidWrapperRuntime.vue
  participant Core as runtime/core.ts
  participant Engine as Mermaid.js or Excalidraw

  Host->>Plugin: Render Markdown with mermaid fences
  Plugin->>Plugin: Parse fence info and merge options
  Plugin->>Wrapper: Emit wrapper HTML and data-mermaid-config
  Host->>Runtime: initMermaidIt(root)
  Runtime->>Vue: Mount one wrapper runtime per node
  Vue->>Core: Read wrapper snapshot
  Core->>Core: Resolve theme font and render engine
  Core->>Engine: Render Mermaid source
  Engine-->>Core: SVG output
  Core-->>Vue: Mount SVG and pan or zoom controller
  Vue-->>Wrapper: Toolbar loading error and fullscreen state
  Host->>Runtime: rerenderMermaidIt(root) after config or DOM updates

Loading diagram…

The key boundary is that the markdown-it side only serializes state while the runtime side owns async rendering and interaction state

What the plugin emits

Each diagram becomes a wrapper with three important parts

• A hidden <pre> that stores the original Mermaid source
• A data-mermaid-config payload that captures the resolved config
• A toolbar with zoom, copy, export, and fullscreen actions

That wrapper format matters because rerendering reads from the same DOM node instead of replacing the whole block

Runtime model

The browser runtime upgrades wrappers into Vue apps on demand

• initMermaidIt() finds unmounted wrappers and mounts them once
• rerenderMermaidIt() rereads wrapper state and rerenders in place
• Pan and zoom state live beside the wrapper, so config-only updates can preserve the current viewport

Runtime design

flowchart TD
  Wrapper["Wrapper element<br/>data-mermaid-config"] --> Snapshot["readWrapperSnapshot"]
  Snapshot --> State["config ref and diagramCode ref"]
  State --> Queue["queueRender"]
  Queue --> Theme["resolveTheme and syncWrapperClasses"]
  Theme --> Engine{renderEngine}
  Engine -->|mermaidjs| MermaidRender["renderMermaidSvg"]
  Engine -->|excalidraw| ExcalidrawRender["renderExcalidrawSvg"]
  MermaidRender --> Mount["mountSvgIntoHost"]
  ExcalidrawRender --> Mount
  Mount --> PanZoom["createPanZoom or setSvgEl"]
  PanZoom --> Toolbar["toolbar actions"]
  Toolbar --> PanZoom
  Toolbar --> Export["copy SVG PNG fullscreen"]
  Queue --> Feedback["loading and error state"]
  Feedback --> Wrapper

Loading diagram…

Each wrapper keeps a small runtime state bag so rerenders can swap SVG content in place instead of destroying the host node

Why route changes need help

Single-page docs frameworks replace page content without reloading the browser runtime. That is why the VitePress integration waits for DOM updates, retries wrapper discovery, and then mounts new diagrams after navigation

Key source files

• src/markdown-it/plugin.ts handles fences and wrapper HTML
• src/runtime.ts exposes the public runtime entry points
• src/runtime/MermaidWrapperRuntime.vue owns the interactive shell
• src/runtime/core.ts handles rendering, export, SVG mounting, and pan or zoom
• src/vitepress.ts adapts the runtime to VitePress route changes