@mdast2docx/mermaid

@m2d/mermaid

@m2d/mermaid: Client-side Mermaid diagram plugin for @m2d/core. Transforms mermaid, mmd, and mindmap code blocks into responsive inline SVGs with auto-repair and caching.

---

Features

• Comprehensive Diagram Support: Supports all standard Mermaid diagram types (flowcharts, sequence, class, state, ER, Gantt, pie, gitGraph, mindmaps, quadrant charts).
• Built-In Self-Healing (defaultMermaidFixer): Automatically repairs common syntax errors such as unquoted colons, slashes, or special characters in node labels.
• Full Theme Customization: Compatible with all official Mermaid themes (default, neutral, forest, dark, base) and custom theme variables.
• IndexedDB & Memory Caching: Eliminates expensive repeated diagram compilation across page reloads.
• Graceful Fallbacks: Preserves diagram source so downstream rasterizers (@m2d/image) can cleanly render collapsible code blocks if rendering fails.

Looking for server-side (Node.js) Mermaid rendering? Use @m2d/mermaid-node powered by beautiful-mermaid (zero DOM / browser dependencies).

---

Installation

This package (@mdast2docx/mermaid) is an official alias of @m2d/mermaid.

Why does this exist?

We provide this package to offer shorter import paths and improved discoverability. While both packages provide identical functionality, @m2d/mermaid is the primary source of truth.

Which one should I use?

• Use @mdast2docx/mermaid if you prefer the shorter name or specific branding or ESM Only.
• Use @m2d/mermaid for the most stable long-term reference and standard alignment.

Feature	@m2d/mermaid	@mdast2docx/mermaid
Source Code	Primary	Proxy
Updates	Immediate	Synchronized (Immediately)
Bundle Size	100%	100% (Zero overhead)
Format	ESM + CJS	ESM Only
Maintenance	Primary	Proxy (inherits)
Security	Primary	Proxy (inherits)

Maintenance & Support

Security: Security audits are performed on the canonical package; this alias inherits all security patches automatically.

---

$ pnpm add @m2d/mermaid @m2d/image @m2d/core docx

or

$ npm install @m2d/mermaid @m2d/image @m2d/core docx

---

Quick Start

import { toDocx } from "@m2d/core";
import { mermaidPlugin } from "@m2d/mermaid";
import { imagePlugin } from "@m2d/image";
import remarkParse from "remark-parse";
import { unified } from "unified";

const markdown = `
# Architecture Overview

\`\`\`mermaid
graph TD
  Client[Web Client] --> Gateway[API Gateway]
  Gateway --> Service[Core Service]
\`\`\`
`;

const mdast = unified().use(remarkParse).parse(markdown);

const docxBlob = await toDocx(mdast, {}, {
  plugins: [
    mermaidPlugin(), // 1. Converts mermaid code blocks into SVG nodes
    imagePlugin(),   // 2. Rasterizes SVGs into OpenXML DrawingML runs
  ],
});

Plugin Ordering: Place mermaidPlugin() before imagePlugin() in the plugins array. mermaidPlugin generates the SVG nodes that imagePlugin subsequently compiles into Word images.

---

Plugin Options

export interface IMermaidPluginOptions {
  /** Mermaid configuration object passed to mermaid.initialize() */
  mermaidConfig?: MermaidConfig;

  /**
   * Optional custom fixer function called when initial rendering fails.
   * If omitted, uses the built-in defaultMermaidFixer.
   */
  fixMermaid?: (code: string, error: Error) => string;

  /** In-memory cache object for sharing across instances */
  cache?: Record<string, Promise<unknown>>;

  /** Duration in minutes before cached records expire (default: 30 days) */
  maxAgeMinutes?: number;
}

---

Deep Dive Guides

• Diagram Syntax & Theming Guide: Comprehensive list of supported diagram types and custom theme configurations.
• Auto-Fixing & Diagram Fallbacks Guide: Built-in syntax healing and graceful Word code block fallbacks.

---

License

This library is licensed under the MIT open-source license.

---

with by Mayank Kumar Chaudhari