@mdast2docx/mermaid NPM

`@m2d/mermaid`

Minzipped

🧠 A plugin for @m2d/core that transforms mermaid, mmd, and mindmap code blocks into high-quality inline SVGs, ready for DOCX, HTML, or future PDF export. ✨ Built with caching, configurability, and AI/automation-friendly hooks in mind.

✨ Why `@m2d/mermaid`?

This plugin is part of the mdast2docx ecosystem — a modular pipeline to convert Markdown (via MDAST) into richly formatted documents.

Whether you're using this in a generative AI pipeline, a Markdown editor, or a publishing workflow, @m2d/mermaid helps you render diagrams just once, cache the result smartly, and export it across formats.

⚡ Features at a Glance

✅ Supports mermaid, mmd, and mindmap code blocks.
🖼️ Converts diagrams into inline SVGs compatible with DOCX/HTML.
🧠 Smart persistent caching via IndexedDB and deduplication via in-memory layer.
🛠️ Fully configurable via Mermaid config.
💥 Handles rendering quirks (e.g. mindmaps, whitespace trimming).
🤖 Built-in hook to fix broken diagrams using LLMs or custom logic.
🧩 Seamless integration with @m2d/core and mdast2docx ecosystem.

📦 Installation

pnpm install @m2d/mermaid

yarn add @m2d/mermaid

npm add @m2d/mermaid

🚀 Quick Start

import { mermaidPlugin } from "@m2d/mermaid";
import { imagePlugin } from "@m2d/image";
import { toDocx } from "@m2d/core";

const converter = await toDocx({
  plugins: [mermaidPlugin(), imagePlugin()],
});

const docxBuffer = await converter.convert(`# Flow\n\n\`\`\`mermaid\ngraph TD; A-->B;\`\`\``);

✅ You can use mindmap or mmd code blocks too — the plugin handles them all.

🧙‍♀️ Plugin Options

mermaidPlugin({
  mermaidConfig: {
    theme: "default",
    fontFamily: "Arial",
    // See all options: https://mermaid.js.org/configuration.html
  },
  idb: true, // Enable IndexedDB caching (default: true)
  maxAgeMinutes: 60 * 24 * 30, // Optional cache expiry (default: 30 days)
  fixMermaid: (code, error) => {
    // Optional: auto-fix bad syntax using AI or heuristics
    return code.replace(/;/g, " --> ");
  },
});

🛠 How It Works

Looks for code blocks with lang = mermaid, mmd, or mindmap.
Cleans and normalizes the code (but leaves sensitive diagram types untouched).
Uses Mermaid to generate an SVG.
Replaces the block with a centered <svg> node inside your MDAST.
Adds caching to speed up repeated renders:
- 🧠 In-memory: avoids duplicate renders during the same session
- 💾 IndexedDB: keeps results between sessions

🤖 Use with AI / Fixing Mermaid Diagrams

Let’s say your users generate Mermaid charts via LLMs (and they sometimes mess up):

mermaidPlugin({
  fixMermaid: async (code, error) => {
    const response = await fetch("/fix-diagram", {
      method: "POST",
      body: JSON.stringify({ code, error: error.message }),
    });
    return await response.text(); // New (hopefully fixed) diagram code
  },
});

📚 See Mermaid docs for supported syntax and examples.

🧩 Part of the `@m2d` Ecosystem

This plugin works best when used with:

@m2d/core – Orchestrates plugins and generates DOCX
@m2d/image – Handles image conversion and embedding
@m2d/html – Parses inline HTML into MDAST nodes

🌐 Try it live: mdast2docx.vercel.app

🧼 Cache Cleanup

To avoid indexed-db bloat, the plugin:

Automatically cleans up expired cache entries after document export.
Ensures cleanup runs only once per session via a cleanupDone flag.
Stores rendered diagrams by language and content hash to prevent duplicates.