@m2d/mermaid

🧠 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

or

yarn add @m2d/mermaid

or

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

1. Looks for code blocks with lang = mermaid, mmd, or mindmap.

2. Cleans and normalizes the code (but leaves sensitive diagram types untouched).

3. Uses Mermaid to generate an SVG.

4. Replaces the block with a centered <svg> node inside your MDAST.

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

📄 License

Licensed under the MPL-2.0 License.

🤝 Contribute & Collaborate

Have an idea? Spotted a bug? Want to level up documentation?

• 💬 File issues or discussions on GitHub
• 📦 Submit PRs – small or big!
• ⭐ Star the project if you find it helpful