Generate Mermaid Diagrams Without Leaving Inkscape — For Academic & Technical Illustrators

You’re mid-design in Inkscape, and you need to add a flowchart, sequence diagram, or state machine. Right now, your workflow looks like this: switch to a browser, open Mermaid’s online editor, create the diagram, export it as PNG or SVG, come back to Inkscape, import it, and hope the formatting survived the conversion. By the time you’ve done this three times, you’ve lost 20 minutes and broken your creative flow.

There’s a better way—and it lives inside Inkscape itself.

What This Is

The Mermaid Diagram Generator is a native Inkscape extension that renders publication-ready diagrams without leaving your canvas. Write or paste Mermaid code, hit Apply, and the rendered diagram lands on your canvas ready to resize, position, and edit. It supports all Mermaid diagram types—flowcharts, sequence diagrams, state machines, class diagrams, ERDs, Gantt charts—and outputs as editable SVG or raster PNG. For academic papers, technical documentation, and research figures, this eliminates the tool-switching tax and keeps your design system unified.

Prerequisites

• Inkscape 1.0 or later (tested on 1.2+)
• Node.js 14+ with npm
• Mermaid CLI (installed via npm)
• Basic terminal comfort
• ~10 minutes for setup

Installation & Setup

Step 1: Install Node.js and npm

Visit nodejs.org and download the LTS version. Run the installer and accept defaults.

Verify installation:

node --version
npm --version

Both should return version numbers.

Step 2: Install Mermaid CLI globally

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

Verify:

mmdc --help

Step 3: Download extension files

Download these two files from the GitHub repository:

• mermaid_diagram_generator.py
• mermaid_diagram_generator.inx

Save them to a temporary folder. Do not rename them.

Step 4: Locate Inkscape extensions folder

Open Inkscape → Edit → Preferences → System. Click the folder icon next to User Extensions to open your extensions directory.

Step 5: Install extension files

Create a subfolder named mermaid-ink in your extensions directory. Copy both files into it.

Typical paths:

• Windows: C:\Users\[YourUsername]\AppData\Roaming\inkscape\extensions\mermaid-ink\
• macOS: ~/Library/Application Support/Inkscape/extensions/mermaid-ink/
• Linux: ~/.config/inkscape/extensions/mermaid-ink/

Step 6: Configure extension (first run)

Restart Inkscape. Go to Extensions → Render → Mermaid Diagram Generator.

Click the Config tab:

• Mermaid CLI Path: On macOS/Linux, run which mmdc in terminal and paste the result. Windows users can leave blank (auto-detected).
• Temporary Folder: Create and set a writable directory:
  • Windows: C:\Temp\mermaid-ink\
  • macOS/Linux: /tmp/mermaid-ink/
• Timeout: Leave at 30 seconds (increase to 60 for complex diagrams)

Click Apply. Done.

Core Workflow

Step 1: Prepare Mermaid code

Write or copy your diagram code. Example flowchart:

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

Browse mermaid.js.org for syntax and diagram types.

Step 2: Open extension

Extensions → Render → Mermaid Diagram Generator

Step 3: Input your code

Option A (Paste): Click the Mermaid Code tab and paste your diagram code.

Option B (Load file): Click the Load from File tab, browse for a .mmd or .txt file.

Step 4: Configure output

In the Diagram tab, set:

• Format: SVG (editable vector) or PNG (raster, use if SVG breaks)
• Theme: default, dark, forest, neutral, etc.
• Background: Transparent or white
• Scale: Leave at 1.0

⚠️ Mermaid’s SVG output uses CSS that Inkscape doesn’t always parse correctly. If output looks broken, switch to PNG.

Step 5: Generate

Click Apply. The diagram appears on your canvas as a grouped object.

Step 6: Resize and position

Click the diagram, drag corner handles to scale, and reposition as needed.

Step 7: Edit (SVG only)

For SVG output, ungroup the diagram:

Right-click → Ungroup (or Ctrl+Shift+G / Cmd+Shift+G)

Now you can:

• Select individual elements (boxes, arrows, text)
• Change colors: Right-click → Set Fill or Set Stroke
• Edit text: Double-click text elements
• Adjust line thickness: Select element, change stroke width in toolbar
• Add/delete elements manually with Inkscape’s drawing tools

Practical Example

Scenario: You’re writing a research paper on machine learning workflows.

Step 1: Write the Mermaid code:

graph LR
    A[Raw Data] --> B[Preprocessing]
    B --> C[Feature Engineering]
    C --> D[Model Training]
    D --> E{Validation}
    E -->|Pass| F[Deploy]
    E -->|Fail| G[Tune Hyperparameters]
    G --> D

Step 2: Open Inkscape. Go to Extensions → Render → Mermaid Diagram Generator.

Step 3: Paste the code in the Mermaid Code tab. Set Format to SVG and Theme to default.

Step 4: Click Apply. A flowchart appears on your canvas.

Step 5: Resize by dragging a corner handle to ~400px wide. Position in the center of your page.

Step 6: Ungroup (Ctrl+Shift+G). Select the “Deploy” box and change its fill to green: Right-click → Set Fill. Change “Tune Hyperparameters” to orange.

Step 7: Double-click “Validation” text and change it to “Accuracy > 95%?” to match your paper.

Step 8: Export as PDF or PNG: File → Export As.

Common Issues & Fixes

Next Steps

You’ve embedded a seamless diagram pipeline into your design tool. Consider:

1. Build a diagram library: Create .mmd files for common diagram types (state machines, architecture, ERDs). Load them via Load from File when needed.

2. Use Inkscape layers: Place each diagram on a separate layer for organization. Layer → New Layer and drag diagrams onto it.

3. Explore Mermaid syntax: Visit mermaid.js.org for radar charts, pie charts, mindmaps, and git graphs.

4. Batch-generate diagrams: Write a bash/PowerShell script to generate multiple Mermaid diagrams and import them into Inkscape templates.

What diagrams do you need most often in your research or technical writing? Reply and let me know—I’d love to hear how you’re using this extension.

What’s your current workflow for embedding diagrams in your papers or documentation—and would a native Inkscape integration change how you work?