Mermaid Diagram Generator for Inkscape

Create beautiful diagrams in Inkscape using Mermaid's simple text-based syntax

Transform text descriptions into professional flowcharts, sequence diagrams, class diagrams, and more—directly within Inkscape. Perfect for technical documentation, presentations, and design projects.

📺 Demo

Click to watch the full tutorial on YouTube

📋 Table of Contents

Features
Supported Diagrams
Requirements
Installation
Quick Start
Usage Guide
Configuration
Examples
Troubleshooting
Contributing
License

✨ Features

📊 Full Mermaid Support
- All diagram types supported
- Native SVG output for editability
- High-quality PNG export option

🎨 Rich Styling Options

Feature	Description
Themes	Default, Dark, Forest, Neutral, Base
Backgrounds	White, Transparent, Custom colors
Scaling	Manual scale factor or auto-fit
Quality	1x to 4x resolution for PNG

📍 Smart Positioning
- 9 preset positions (center, corners, edges)
- Selection-relative placement
- Custom X/Y offsets
- Page or viewport alignment
🔧 Advanced Features
- PDF-to-SVG pipeline for best quality
- Embed or link external images
- Custom config and CSS files
- Layer management
- Object locking
- Metadata support (title, description)

📊 Supported Diagrams

Diagram Type	Syntax Keyword	Description
Flowchart	`flowchart` or `graph`	Process flows and decision trees
Sequence	`sequenceDiagram`	Interaction between entities
Class	`classDiagram`	UML class relationships
State	`stateDiagram-v2`	State machine diagrams
ER Diagram	`erDiagram`	Entity-relationship models
Gantt	`gantt`	Project timelines
Pie Chart	`pie`	Proportional data
Git Graph	`gitGraph`	Git branch visualization
Mindmap	`mindmap`	Hierarchical ideas
Timeline	`timeline`	Chronological events
User Journey	`journey`	User experience mapping
Quadrant	`quadrantChart`	2x2 matrix analysis
Sankey	`sankey-beta`	Flow quantities

📦 Requirements

Core Requirements

Component	Version	Purpose
Inkscape	1.0+	Vector graphics editor
Node.js	14+	JavaScript runtime
Mermaid CLI	10+	Diagram generation

Optional Dependencies

Component	Purpose
Pillow (Python)	Automatic image dimension detection
Custom CSS	Advanced diagram styling

🚀 Installation

Step 1: Install Node.js

Windows

Download from nodejs.org
Run installer, accept defaults
Verify installation:
```
node --version
npm --version
```

macOS

# Using Homebrew
brew install node

# Or download from nodejs.org

Linux

# Ubuntu/Debian
sudo apt update
sudo apt install nodejs npm

# Fedora
sudo dnf install nodejs npm

# Arch
sudo pacman -S nodejs npm

Step 2: Install Mermaid CLI

npm install -g @mermaid-js/mermaid-cli

Verify installation:

mmdc --version
# Should output: x.x.x (e.g., 10.6.1)

⚠️ Windows Users: Note the full path to mmdc.cmd:
C:\Users\[YourName]\AppData\Roaming\npm\mmdc.cmd

Step 3: Install the Extension

Locate your Inkscape extensions directory:

OS	Path
Windows	`C:\Users\[YourName]\AppData\Roaming\inkscape\extensions\`
macOS	`~/Library/Application Support/org.inkscape.Inkscape/config/inkscape/extensions/`
Linux	`~/.config/inkscape/extensions/`

💡 Tip: In Inkscape: Edit → Preferences → System shows extensions path

Install files:

Create extension folder:

mkdir -p [extensions-directory]/mermaid_ink

Copy files:

cp mermaid_diagram.py [extensions-directory]/mermaid_ink/
cp mermaid_diagram.inx [extensions-directory]/mermaid_ink/

Set permissions (Linux/macOS):

chmod +x [extensions-directory]/mermaid_ink/mermaid_diagram.py

Restart Inkscape

Step 4: Verify Installation

Open Inkscape
Navigate to Extensions → Render → Mermaid Diagram
Extension dialog should appear

🎯 Quick Start

Create Your First Diagram

Open Inkscape
Go to Extensions → Render → Mermaid Diagram
In the Diagram tab, enter:

flowchart TD
    A[Start] --> B{Decision}
    B -->|Yes| C[Do Something]
    B -->|No| D[Do Something Else]
    C --> E[End]
    D --> E

Click Apply

Your flowchart appears in the document, fully editable as SVG!

📖 Usage Guide

Tab Overview

Tab	Purpose
Diagram	Enter Mermaid code or load from file
Style	Theme, background, dimensions
Format	Output format, scale, quality
Position	Placement and alignment options
Scale	Auto-scaling and size limits
Config	CLI path, config files
Advanced	Timeout, viewport, temp files
Layer	Layer management, object properties

Input Methods

Direct Code Entry

Enter Mermaid syntax directly in the code field:

sequenceDiagram
    Alice->>Bob: Hello Bob!
    Bob-->>Alice: Hi Alice!

Load from File

Check "Use external file"
Enter path to .mmd or .mermaid file
Click Apply

Output Formats

Format	Best For	Editable
SVG	Editing, scalability	✅ Yes
PNG	Presentations, sharing	❌ No

Theme Options

Theme	Description
`default`	Standard Mermaid colors
`dark`	Dark background, light elements
`forest`	Green nature palette
`neutral`	Grayscale, professional
`base`	Minimal, for custom CSS

Position Modes

┌─────────────────────────────────────┐
│ top_left    top_center    top_right │
│                                     │
│ middle_left   center   middle_right │
│                                     │
│ bottom_left bottom_center bottom_right │
└─────────────────────────────────────┘

Special modes:

cursor: Place at current view center
Use selection bbox: Position relative to selected object

⚙️ Configuration

Style Tab

Option	Description	Default
Theme	Color scheme	default
Background	Background color	white
Width	Diagram width (px)	800
Height	Diagram height (px)	600

Format Tab

Option	Description	Default
Output Format	SVG or PNG	SVG
Scale Factor	Size multiplier	1.0
Quality	PNG resolution (1-4x)	2
Embed Image	Embed or link PNG	✓

Scale Tab

Option	Description	Default
Auto Scale	Fit to max dimensions	✗
Max Width	Maximum width (0=none)	0
Max Height	Maximum height (0=none)	0
Maintain Aspect Ratio	Keep proportions	✓
Lock Object	Prevent edits	✗

Config Tab

Option	Description	Default
Mermaid CLI Path	Path to mmdc	mmdc
Config File	Custom mermaidConfig.json	(empty)
CSS File	Custom stylesheet	(empty)
Inkscape Path	Path to Inkscape CLI	inkscape

Advanced Tab

Option	Description	Default
Timeout	Generation timeout (sec)	30
Viewport Width	Puppeteer viewport	1920
Viewport Height	Puppeteer viewport	1080
Keep Temp Files	Don't delete temp files	✗
Quiet Mode	Suppress debug output	✓
Fit to Content	Crop empty space	✓

Layer Tab

Option	Description	Default
Create Layer	New layer for diagram	✗
Layer Name	Name for new layer	Mermaid Diagrams
Object ID	Custom SVG ID	(auto)
Add Title	Include title element	✗
Add Description	Include desc element	✗

💡 Examples

Example 1: Flowchart

flowchart LR
    A[Hard edge] -->|Link text| B(Round edge)
    B --> C{Decision}
    C -->|One| D[Result one]
    C -->|Two| E[Result two]

Example 2: Sequence Diagram

sequenceDiagram
    participant Browser
    participant Server
    participant Database
    
    Browser->>Server: HTTP Request
    Server->>Database: Query
    Database-->>Server: Results
    Server-->>Browser: HTTP Response

Example 3: Class Diagram

classDiagram
    Animal <|-- Duck
    Animal <|-- Fish
    Animal : +int age
    Animal : +String gender
    Animal: +isMammal()
    Animal: +mate()
    
    class Duck{
        +String beakColor
        +swim()
        +quack()
    }
    
    class Fish{
        -int sizeInFeet
        -canEat()
    }

Example 4: Gantt Chart

gantt
    title Project Schedule
    dateFormat  YYYY-MM-DD
    
    section Planning
    Requirements    :a1, 2024-01-01, 30d
    Design          :a2, after a1, 20d
    
    section Development
    Frontend        :b1, after a2, 40d
    Backend         :b2, after a2, 45d
    
    section Testing
    QA              :c1, after b2, 15d

Example 5: Entity Relationship

erDiagram
    CUSTOMER ||--o{ ORDER : places
    ORDER ||--|{ LINE-ITEM : contains
    CUSTOMER {
        string name
        string email
    }
    ORDER {
        int orderNumber
        date created
    }
    LINE-ITEM {
        string productCode
        int quantity
        float price
    }

Example 6: Mindmap

mindmap
  root((Project))
    Planning
      Requirements
      Timeline
      Budget
    Development
      Frontend
      Backend
      Database
    Testing
      Unit Tests
      Integration
      UAT

Example 7: Pie Chart

pie showData
    title Browser Market Share
    "Chrome" : 65
    "Safari" : 19
    "Firefox" : 4
    "Edge" : 4
    "Other" : 8

Example 8: Git Graph

gitGraph
    commit
    commit
    branch develop
    checkout develop
    commit
    commit
    checkout main
    merge develop
    commit
    branch feature
    checkout feature
    commit
    checkout main
    merge feature

🐛 Troubleshooting

Common Issues

Extension not appearing in menu

Solutions:

Verify files are correctly placed:

ls [extensions-directory]/mermaid_ink/
# Should show: mermaid_diagram.py, mermaid_diagram.inx

Check file permissions
Restart Inkscape completely
Check Inkscape error log: Edit → Preferences → System → Open Error Log

Mermaid CLI not found

Error: Mermaid CLI not found at: mmdc

Solutions:

Verify mmdc is installed:
```
mmdc --version
```
Install if missing:
```
npm install -g @mermaid-js/mermaid-cli
```

Windows: Use full path in Config tab:

C:\Users\[YourName]\AppData\Roaming\npm\mmdc.cmd

Linux/macOS: Find path:

which mmdc
# Use this path in Config tab

Diagram syntax error

Error: Mermaid CLI error: Parse error...

Solutions:

Validate syntax at mermaid.live
Check for:
- Missing diagram type declaration
- Unclosed brackets
- Invalid characters
- Incorrect indentation
Start with a simple example and build up

Puppeteer/Chrome errors

Error: Could not find Chrome... or Puppeteer timeout

Solutions:

Install Chrome/Chromium:

# Windows: Install Chrome normally
# Linux:
sudo apt install chromium-browser

Increase timeout in Advanced tab
Check system resources (RAM, CPU)

PDF conversion fails

Error: Inkscape conversion error...

Solutions:

Verify Inkscape CLI works:
```
inkscape --version
```
Update Inkscape path in Config tab

Windows: Use full path:

C:\Program Files\Inkscape\bin\inkscape.exe

Enable pdf-poppler option for better compatibility

Empty or corrupted output

Solutions:

Disable Quiet Mode to see debug output
Enable Keep Temp Files and check generated files
Try PNG format instead of SVG
Reduce diagram complexity
Check available disk space

Diagram appears but not editable (SVG)

Solutions:

Ungroup the imported diagram (Ctrl+Shift+G)
Check if object is locked (unlock in Object Properties)
Ensure "Output Format" is set to SVG, not PNG

Debug Mode

Enable detailed output for troubleshooting:

Uncheck Quiet Mode in Advanced tab
Check Keep Temp Files
Run Inkscape from terminal to see console output:
```
inkscape
```
Temp files location:
- Check the path in extension output
- Or set custom path in Temp Directory field

Checking Temp Files

With Keep Temp Files enabled:

File	Purpose
`diagram.mmd`	Input Mermaid code
`diagram.pdf`	Generated PDF
`diagram_converted.svg`	Converted SVG
`diagram_converted.png`	Converted PNG

📁 File Structure

mermaid_ink/
├── mermaid_diagram.py      # Main extension code
├── mermaid_diagram.inx     # Inkscape extension definition
├── README.md               # This file
└── examples/               # Example diagrams (optional)
    ├── flowchart.mmd
    ├── sequence.mmd
    └── class.mmd

🔧 Custom Configuration

Mermaid Config File

Create a JSON config file for advanced customization:

{
  "theme": "base",
  "themeVariables": {
    "primaryColor": "#4a90d9",
    "primaryTextColor": "#fff",
    "primaryBorderColor": "#2c5aa0",
    "lineColor": "#333",
    "secondaryColor": "#006100",
    "tertiaryColor": "#fff"
  },
  "flowchart": {
    "curve": "basis",
    "padding": 20
  },
  "sequence": {
    "diagramMarginX": 50,
    "diagramMarginY": 10,
    "actorMargin": 50,
    "width": 150,
    "height": 65
  }
}

Save as mermaid-config.json and reference in Config tab.

Custom CSS

Create a CSS file for diagram styling:

.node rect {
  fill: #f0f0f0;
  stroke: #333;
  stroke-width: 2px;
}

.edgePath .path {
  stroke: #666;
  stroke-width: 2px;
}

.label {
  font-family: 'Arial', sans-serif;
  font-size: 14px;
}

Save as mermaid-styles.css and reference in Config tab.

📚 Resources

Mermaid Documentation: mermaid.js.org/intro/
Live Editor: mermaid.live
Mermaid CLI: github.com/mermaid-js/mermaid-cli
Inkscape Extensions: inkscape.gitlab.io/extensions/documentation/

🤝 Contributing

Contributions are welcome!

Fork the repository
Create a feature branch (git checkout -b feature/new-feature)
Commit changes (git commit -m 'Add new feature')
Push to branch (git push origin feature/new-feature)
Open a Pull Request

Development Setup:

git clone https://github.com/YouvenZ/mermaid_ink.git
cd mermaid_ink
# Symlink for testing
ln -s $(pwd) ~/.config/inkscape/extensions/mermaid_ink

📄 License

This project is licensed under the MIT License - see LICENSE file for details.

📧 Support

Issues: GitHub Issues
Discussions: GitHub Discussions

🙏 Acknowledgments

Mermaid.js - The diagram rendering engine
Inkscape - Open source vector graphics
Node.js - JavaScript runtime

🔄 Changelog

v1.0.0 (2024)

✨ Initial release
✅ All Mermaid diagram types
✅ SVG and PNG output
✅ PDF-to-SVG conversion pipeline
✅ 5 built-in themes
✅ Auto-scaling
✅ Layer management
✅ Custom config/CSS support
✅ Position and alignment options

Name		Name	Last commit message	Last commit date
README.md		README.md
example.mmd		example.mmd
license		license
mermaid_diagram.inx		mermaid_diagram.inx
mermaid_diagram.py		mermaid_diagram.py

Latest commit

History

Folders and files

Repository files navigation

Mermaid Diagram Generator for Inkscape

📺 Demo

📋 Table of Contents

✨ Features

📊 Supported Diagrams

📦 Requirements

Core Requirements

Optional Dependencies

🚀 Installation

Step 1: Install Node.js

Step 2: Install Mermaid CLI

Step 3: Install the Extension

Step 4: Verify Installation

🎯 Quick Start

Create Your First Diagram

📖 Usage Guide

Tab Overview

Input Methods

Direct Code Entry

Load from File

Output Formats

Theme Options

Position Modes

⚙️ Configuration

Style Tab

Format Tab

Scale Tab

Config Tab

Advanced Tab

Layer Tab

💡 Examples

Example 1: Flowchart

Example 2: Sequence Diagram

Example 3: Class Diagram

Example 4: Gantt Chart

Example 5: Entity Relationship

Example 6: Mindmap

Example 7: Pie Chart

Example 8: Git Graph

🐛 Troubleshooting

Common Issues

Debug Mode

Checking Temp Files

📁 File Structure

🔧 Custom Configuration

Mermaid Config File

Custom CSS

📚 Resources

🤝 Contributing

📄 License

📧 Support

🙏 Acknowledgments

🔄 Changelog

v1.0.0 (2024)

About

Topics

Resources

Stars

Watchers

Forks

Releases

Packages

Contributors

Languages