markdown-it-mermaid-enhanced

[!WARNING] Powered by AI and reviewed by humans

markdown-it-mermaid-enhanced is a markdown-it plugin for rendering Mermaid fences into runtime-friendly wrappers with toolbar actions, browser rendering, export support, and optional VitePress integration

Documentation | Playground

Install

Use the Mermaid runtime

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

Use the Excalidraw render engine

bun install markdown-it markdown-it-mermaid-enhanced mermaid @excalidraw/excalidraw @excalidraw/mermaid-to-excalidraw

Use with markdown-it

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

const md = new MarkdownIt().use(markdownItMermaidEnhanced, {
  theme: 'auto',
  renderEngine: 'mermaidjs',
})

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

Use in the browser

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

await initMermaidIt()

If you update existing wrappers in place, rerender them like this

import { rerenderMermaidIt } from 'markdown-it-mermaid-enhanced/runtime'

await rerenderMermaidIt()

Use in VitePress

Register the markdown-it plugin

// .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',
      })
    },
  },
})

Load the stylesheet and VitePress runtime plugin

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

Font usage

Load fonts in the host page or app, then pass only the family name to the plugin

@import url('https://fonts.googleapis.com/css2?family=Allura&family=Architects+Daughter&family=Amatic+SC:wght@400;700&family=Caveat:wght@400;700&family=Comic+Relief&family=Covered+By+Your+Grace&family=Dancing+Script:wght@400;700&family=Great+Vibes&family=Indie+Flower&family=Just+Another+Hand&family=Kristi&family=Nanum+Pen+Script&family=Patrick+Hand&family=Playball&family=Shadows+Into+Light&display=swap');
@import url('https://cdn.jsdelivr.net/npm/[email protected]/lxgwwenkailite-regular.css');
@import url('https://cdn.jsdelivr.net/npm/[email protected]/font.min.css');
@import url('https://unpkg.com/@chinese-fonts/[email protected]/dist/Xiaolai/result.css');

@font-face {
  font-family: 'Excalifont';
  src: url('https://plus.excalidraw.com/_next/static/media/Excalifont-s.p.436754fa.woff2')
    format('woff2');
  font-style: normal;
  font-weight: 400;
  font-display: swap;
}

@font-face {
  font-family: 'Virgil';
  src: url('https://plus.excalidraw.com/virgil/Virgil.woff2') format('woff2');
  font-style: normal;
  font-weight: 400;
  font-display: swap;
}

const md = new MarkdownIt().use(markdownItMermaidEnhanced, {
  theme: 'auto',
  sketch: true,
  sketchFont: '"Excalifont"',
  fontFamily: '"Excalifont"',
})

The package no longer manages font files or font-face source arrays, so the same host-side loading pattern also applies when you use fontFamily for non-sketch Mermaid text

The playground follows the same pattern and ships ready-to-switch single-family presets for the popular handwritten families listed in the font guide

If you need bilingual handwritten output, pass a manual fallback chain such as "Excalifont", "Xiaolai SC"; Mermaid.js will use it directly, while Excalidraw exports reuse the stack on the SVG text layer without recomputing node sizes