tiptap-mermaid

A TipTap extension for creating and editing Mermaid diagrams with interactive editing capabilities. Compatible with TipTap v3.

Features

• 🎨 Interactive Mermaid diagrams in TipTap editor
• ✏️ Editable diagrams with click-to-edit functionality
• 🚀 Input rules - Type ```mermaid to create diagrams
• ⌨️ Keyboard shortcuts - Cmd/Ctrl+Alt+M to insert diagrams
• 🎯 Customizable styling and configuration
• 📱 Responsive diagram rendering
• 🔧 TypeScript support with full type definitions
• ⚡ TipTap v3 compatible

Installation

npm install tiptap-mermaid mermaid

Requirements

• TipTap v3.0.0+
• Mermaid v10.0.0+

Basic Usage

import { Editor } from '@tiptap/core';
import StarterKit from '@tiptap/starter-kit';
import { Mermaid } from 'tiptap-extension-mermaid';
import mermaid from 'mermaid';

// Initialize mermaid globally
mermaid.initialize({
  startOnLoad: false,
  theme: 'default',
  securityLevel: 'loose'
});

// Make mermaid available globally for the extension
window.mermaid = mermaid;

const editor = new Editor({
  element: document.querySelector('#editor'),
  extensions: [
    StarterKit,
    Mermaid.configure({
      editable: true,
      mermaidConfig: {
        theme: 'default',
        securityLevel: 'loose'
      }
    })
  ],
  content: '<p>Start typing...</p>'
});

Configuration Options

Mermaid.configure({
  // HTML attributes for the mermaid container
  HTMLAttributes: {},

  // CSS class name for the container
  className: 'mermaid-diagram',

  // Mermaid configuration object
  mermaidConfig: {
    theme: 'default', // 'default', 'dark', 'forest', 'neutral'
    securityLevel: 'loose', // 'strict', 'loose', 'antiscript', 'sandbox'
    startOnLoad: false,
    flowchart: {
      useMaxWidth: true,
      htmlLabels: true
    }
  },

  // Enable/disable editing functionality
  editable: true
});

Usage Examples

Creating Diagrams

Method 1: Input Rules

Type ```mermaid in the editor to create a new diagram:

```mermaid
graph TD
    A[Start] --> B{Decision}
    B -->|Yes| C[Action 1]
    B -->|No| D[Action 2]

Method 2: Commands

editor.commands.setMermaidDiagram({
  code: `graph TD
    A[Start] --> B{Decision}
    B -->|Yes| C[Action 1]
    B -->|No| D[Action 2]`
});

Method 3: Keyboard Shortcut

Press Cmd/Ctrl + Alt + M to insert a new diagram.

Diagram Types

Flowcharts

graph TD
    A[Start] --> B{Decision}
    B -->|Yes| C[Success]
    B -->|No| D[Retry]

Sequence Diagrams

sequenceDiagram
    participant A as Alice
    participant B as Bob
    A->>B: Hello Bob, how are you?
    B-->>A: Great!

Gantt Charts

gantt
    title Project Timeline
    dateFormat  YYYY-MM-DD
    section Planning
    Research       :done, 2024-01-01, 2024-01-15
    Design         :active, 2024-01-16, 30d

Class Diagrams

classDiagram
    class Animal {
        +String name
        +makeSound()
    }
    class Dog {
        +bark()
    }
    Animal <|-- Dog

Rendering Diagrams

The extension automatically renders diagrams, but you can also manually trigger rendering:

import { renderMermaidDiagrams } from '@tiptap/extension-mermaid';

// Render all unprocessed diagrams
renderMermaidDiagrams();

Styling

The extension creates the following HTML structure:

<div class="mermaid-diagram mermaid-container" data-type="mermaid" data-mermaid-code="...">
  <div class="mermaid-label">📊 Mermaid Diagram</div>
  <button class="mermaid-edit-btn">✏️ Edit</button>
  <div class="mermaid-content" data-mermaid-code="...">
    <!-- Rendered SVG appears here -->
  </div>
</div>

CSS Customization

.mermaid-container {
  border: 2px dashed #e2e8f0;
  border-radius: 8px;
  padding: 1rem;
  margin: 1rem 0;
}

.mermaid-content svg {
  max-width: 100%;
  height: auto;
}

.mermaid-edit-btn {
  background: #f8f9fa;
  border: 1px solid #dee2e6;
  border-radius: 4px;
  padding: 0.25rem 0.5rem;
  cursor: pointer;
}

.mermaid-edit-btn:hover {
  background: #e9ecef;
}

Advanced Usage

Custom Mermaid Configuration

Mermaid.configure({
  mermaidConfig: {
    theme: 'dark',
    securityLevel: 'loose',
    flowchart: {
      useMaxWidth: false,
      htmlLabels: true,
      curve: 'cardinal'
    },
    sequence: {
      diagramMarginX: 50,
      diagramMarginY: 10,
      actorMargin: 50,
      width: 150,
      height: 65,
      boxMargin: 10,
      boxTextMargin: 5,
      noteMargin: 10,
      messageMargin: 35
    }
  }
});

Event Handling

const editor = new Editor({
  extensions: [Mermaid],
  onUpdate: ({ editor }) => {
    // Re-render diagrams when content changes
    setTimeout(() => {
      renderMermaidDiagrams();
    }, 100);
  }
});

Read-only Mode

Mermaid.configure({
  editable: false // Disable editing buttons
});

Browser Compatibility

• Modern browsers supporting ES6+
• Chrome 60+
• Firefox 60+
• Safari 12+
• Edge 79+

Dependencies

• @tiptap/core >= 2.0.0
• mermaid >= 9.0.0

TypeScript Support

This package includes TypeScript definitions. For the best experience:

import { Editor } from '@tiptap/core';
import { Mermaid, MermaidOptions, renderMermaidDiagrams } from '@tiptap/extension-mermaid';

interface MyMermaidOptions extends MermaidOptions {
  customOption?: string;
}

const editor = new Editor({
  extensions: [
    Mermaid.configure<MyMermaidOptions>({
      editable: true,
      customOption: 'value'
    })
  ]
});

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

1. Fork the repository
2. Create your feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add some amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

License

MIT © [Your Name]

Changelog

2.0.0

• TipTap v3 support

• Complete Mermaid diagram support with all diagram types

• Interactive editing capabilities

• Input rules (```mermaid) and keyboard shortcuts (Cmd/Ctrl+Alt+M)

• Configurable styling and Mermaid options

• Framework-agnostic implementation

• Full TypeScript support with declarations

• ESM and CommonJS builds

• Initial release

• Basic Mermaid diagram support

• Editable diagrams

• Input rules and keyboard shortcuts

• TypeScript support

• Compatible with TipTap v2.x

Support

If you encounter any issues or have questions:

1. Check the GitHub Issues
2. Create a new issue with detailed information
3. Include code examples and error messages

Related Packages

• @tiptap/core - The core TipTap package
• @tiptap/starter-kit - Essential TipTap extensions
• mermaid - The Mermaid diagramming library

Made with ❤️ for the TipTap community