Tiptap Extension Mermaid

npm bundle size

🪄 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

npm install tiptap-extension-mermaid

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.

with 💖 by Mayank Kumar Chaudhari