Tiptap Extension Mermaid

🪄 A drop-in Tiptap extension that adds live Mermaid diagram rendering to CodeBlockLowlight — powered by prosemirror-mermaid.

✨ Features

• Live Mermaid diagrams — render instantly as you type
• Debounced updates — smooth editing experience (default: 300 ms)
• Syntax highlighting — integrates with lowlight and lowlight-mermaid
• Tight SVG output — powered by @svg-fns/layout
• Automatic stable IDs — each diagram gets a persistent ID via data-id
• Drop-in for CodeBlockLowlight — no extra node definitions required

🚀 Installation

pnpm add tiptap-extension-mermaid

or

npm install tiptap-extension-mermaid

or

yarn add tiptap-extension-mermaid

🧩 Quick Start

import { CodeblockLowlightMermaid } from "tiptap-extension-mermaid";
import { createLowlight } from "lowlight";
import { Editor } from "@tiptap/core";
import mermaid from "mermaid";

// Important: initialize Mermaid manually
mermaid.initialize({ startOnLoad: false });

const lowlight = createLowlight();

const editor = new Editor({
  extensions: [
    CodeblockLowlightMermaid.configure({
      lowlight,
      classList: "mermaid-container",
      debounce: 400,
      mermaidConfig: {
        theme: "neutral",
      },
    }),
  ],
  content: `
  \`\`\`mermaid
  graph TD
    A[Start] --> B{Is it working?}
    B -- Yes --> C[Ship it!]
    B -- No --> D[Fix and retry]
  \`\`\`
  `,
});

⚙️ Options

| Option | Type | Default | Description | | ------------------- | ----------------------------------- | ------------------ | ------------------------------------------------ | | lowlight | ReturnType<typeof createLowlight> | {} | Lowlight instance for syntax highlighting. | | debounce | number | 300 | Delay (ms) before re-render after typing stops. | | mermaidConfig | MermaidConfig | {} | Passed directly to mermaid.initialize(). | | classList | string[] \| string | "" | CSS class(es) applied to each diagram container. | | id (auto) | string | Random mxxxxxxxx | Auto-generated, persisted via data-id. |

🧠 How It Works

• Extends @tiptap/extension-code-block-lowlight
• Adds an id attribute per node for stable Mermaid rendering
• Injects the prosemirror-mermaid plugin to manage rendering, caching, and SVG lifecycle
• Registers Mermaid grammars (mermaid, mmd, mindmap) in lowlight if available

🧰 Example Styling

.mermaid-container {
  display: flex;
  justify-content: center;
  padding: 0.5rem;
  overflow-x: auto;
  border-radius: 0.5rem;
  background: var(--code-bg, #f8f9fa);
}

🧩 Advanced Example (React + Tiptap)

import { useEditor, EditorContent } from "@tiptap/react";
import { CodeblockLowlightMermaid } from "tiptap-extension-mermaid";
import { createLowlight } from "lowlight";
import mermaid from "mermaid";

const lowlight = createLowlight();
mermaid.initialize({ startOnLoad: false });

export const MermaidEditor = () => {
  const editor = useEditor({
    extensions: [
      CodeblockLowlightMermaid.configure({
        lowlight,
        classList: ["mermaid-container", "diagram"],
      }),
    ],
  });

  return <EditorContent editor={editor} />;
};

🪄 Integration Notes

• Works seamlessly with Tiptap v2+
• You must manually initialize Mermaid before using
• Diagrams render only for code blocks with language = mermaid, mmd, or mindmap
• Errors during rendering are displayed inline (non-blocking)

🙏 Credits

• Mermaid for diagrams
• Tiptap for the editor framework
• @svg-fns for SVG manipulation utilities
• prosemirror-mermaid — the rendering engine underneath

License

This library is licensed under the MPL-2.0 open-source license.

Please enroll in our courses or sponsor our work.