Getting started

The shortest path has three pieces: the markdown-it plugin, the browser runtime, and the stylesheet

Install the runtime path

bun install markdown-it markdown-it-mermaid-enhanced mermaid

Register the markdown-it plugin

import MarkdownIt from 'markdown-it'
import markdownItMermaidEnhanced from 'markdown-it-mermaid-enhanced'

const markdown = new MarkdownIt().use(markdownItMermaidEnhanced, {
  theme: 'auto',
  renderEngine: 'mermaidjs',
  minHeight: '160px',
})

Load the browser runtime

import 'markdown-it-mermaid-enhanced/styles.css'
import { initMermaidIt } from 'markdown-it-mermaid-enhanced/runtime'

const html = markdown.render(`
\`\`\`mermaid
flowchart LR
  A[Build] --> B[Deploy]
\`\`\`
`)

document.querySelector('#app')!.innerHTML = html
await initMermaidIt(document.querySelector('#app')!)

VitePress wiring

// 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',
        minHeight: '160px',
      })
    },
  },
})

// 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

A first diagram

flowchart LR
  Fence["Markdown fence"] --> Plugin["markdown-it-mermaid-enhanced"]
  Plugin --> Wrapper["wrapper HTML"]
  Wrapper --> Runtime["runtime hydration"]
  Runtime --> Diagram["interactive SVG"]

Loading diagram…

Common next steps

• How it works for the rendering pipeline
• Rendering engines for Mermaid.js and Excalidraw trade-offs
• Sketch and fonts for host-side font loading
• Plugin options for the complete option surface