How to Import Mermaid Diagrams into Diagram-Design: A Complete Developer Guide

Use the /diagram-design:import-mermaid command with the file path and optional flags to parse Mermaid source into Diagram-Design's intermediate representation and redraw it using the project's layout engine and style system.

Diagram-Design can import and redraw Mermaid diagrams—files with .mmd or .mermaid extensions, or Markdown files containing fenced mermaid code blocks—into any of 27 editorial-style diagram types. This process is not a simple render or convert step. Instead, the Mermaid source is parsed into a language-agnostic intermediate representation (IR) and rebuilt using Diagram-Design's own layout engine, giving you full control over output format, size, detail level, audience wording, and visual variant.

---

The Three-Phase Import Architecture

Understanding how Diagram-Design handles Mermaid imports helps you troubleshoot issues and optimize your workflow.

1. Extraction: Parsing Mermaid to IR

The skill locates the installed repository and runs skills/diagram-design/scripts/mermaid_extract.py on your supplied file. This script produces a structured intermediate representation containing nodes, edges, containers, and layout hints.

No JavaScript, network calls, or Mermaid rendering occur during this phase. The extractor supports these grammars:

• flowchart
• sequenceDiagram
• stateDiagram-v2
• erDiagram

If the extractor exits with code 2, its message is reported verbatim and the process aborts.

2. Dial-Setting and Type Selection

Using the four "dials" defined in skills/diagram-design/references/output-spec.md—--format, --size, --detail, and --audience—the skill selects a diagram type that best matches the Mermaid grammar. The grammar-to-type mapping follows standard conventions: flowchart maps to Flowchart, sequenceDiagram to Sequence, and so on.

The skill checks the IR's budget line to confirm your chosen dial combination is feasible. If not, it proposes a reduced-detail or overview output.

3. Redraw: Generating Fresh Layout

A new layout is generated from scratch, discarding Mermaid-specific themes, classes, or positional data. The resulting SVG/HTML respects style-guide.md skin settings for colors, fonts, and accessibility. A fidelity ledger reports what was merged, collapsed, or dropped.

---

Command Reference

Basic Syntax

/diagram-design:import-mermaid <path-to-file> [flags]

The command definition lives in commands/import-mermaid.md and points to references/import-mermaid.md for the full workflow specification.

Available Flags

Flag	Description	Default
--format	Output format: html, svg, png, html+png	html
--size	Canvas preset: slide-16x9, slide-4x3, a4, letter, etc.	inferred
--detail	Complexity level: faithful, balanced, simplified	balanced
--audience	Wording style: technical, executive, general	technical
--variant	Visual style: light, dark, full	light
--type	Force specific diagram type (overrides auto-detection)	auto
--diagram	Select specific diagram from multi-block file (N or all)	0 (first)
--output	Base path for output files	same as input
--json	Emit IR as JSON instead of redrawing	off
--max-rows	Limit parsed rows for large files	unlimited

---

Practical Code Examples

Import a Single Mermaid File

# Redraw to HTML with default settings

/diagram-design:import-mermaid scripts/fixtures/sample-flowchart.mmd

Full-Featured Export for Presentations

# PNG output, 16:9 slide size, simplified detail, executive audience, dark theme

/diagram-design:import-mermaid README.md \
    --format=png \
    --size=slide-16x9 \
    --detail=simplified \
    --audience=executive \
    --variant=dark \
    --output=outputs/my-diagram

This produces:

• outputs/my-diagram.html
• outputs/my-diagram.png

Process All Mermaid Blocks in a Markdown File

# Generate separate HTML files for each fenced mermaid block

/diagram-design:import-mermaid docs/complex-diagrams.md --diagram=all --variant=full

Output files follow the pattern:

docs/complex-diagrams-0.html
docs/complex-diagrams-1.html
...

Override Auto-Detected Diagram Type

# Force Architecture layout even for flowchart grammar

/diagram-design:import-mermaid architecture.mmd --type=architecture

Extract IR as JSON for Custom Processing

python3 skills/diagram-design/scripts/mermaid_extract.py \
    my-diagram.mmd \
    --json \
    --out intermediate.json \
    --max-rows 500

---

Key Implementation Files

Understanding these source files helps you debug import issues and extend functionality:

• skills/diagram-design/scripts/mermaid_extract.py — Core parser that converts Mermaid source to structured IR. Handles node extraction, edge detection, and container hierarchy.

• skills/diagram-design/references/import-mermaid.md — Canonical import procedure with anti-pattern rules and grammar support matrix.

• commands/import-mermaid.md — Slash-command definition with argument schema and routing logic.

• skills/diagram-design/references/output-spec.md — Complete specification of the four dials (format, size, detail, audience) and valid combinations.

• scripts/verify-mermaid-import.py — CI validation script ensuring extractor, references, and command wiring stay synchronized.

• skills/diagram-design/SKILL.md — Top-level skill description with taste-gate logic (section 9) that enforces quality checks before output delivery.

• skills/diagram-design/assets/example-import-mermaid.html — Live reference implementation showing a rendered Mermaid import.

---

Direction Hints and Styling Behavior

Mermaid directional keywords (TD, LR, BT, RL) are treated as soft hints, not hard constraints. The Diagram-Design layout algorithm may override these to achieve optimal readability.

Similarly, Mermaid-specific styling instructions do not survive import:

• classDef declarations are ignored
• Inline style statements are discarded
• linkStyle properties are removed

The output uses only the single accent color and ink/muted palette defined in style-guide.md, ensuring visual consistency across all diagram types.

---

Validation and Quality Gates

Before final delivery, imports pass two validation layers:

1. Taste Gate (SKILL.md §9) — Enforces minimum readability standards and checks for anti-patterns like excessive node counts or unclear edge labels.

2. Output Checklist (output-spec.md §6) — Verifies format compliance and resource limits.

In CI, scripts/verify-mermaid-import.py runs on every push to guarantee that changes to the extractor or references don't break the import pipeline.

---

Summary

• Import Mermaid diagrams using /diagram-design:import-mermaid <file> with optional flags for precise output control.
• The three-phase architecture—extraction, dial-setting, and redraw—parses Mermaid source into an intermediate representation and rebuilds it with Diagram-Design's layout engine.
• Supported grammars include flowchart, sequenceDiagram, stateDiagram-v2, and erDiagram.
• Four dials control output: --format, --size, --detail, and --audience.
• Mermaid-specific styling and positional hints are discarded; output uses standard style-guide.md skins.
• Key files: mermaid_extract.py for parsing, import-mermaid.md for procedure, and output-spec.md for dial specifications.

---

Frequently Asked Questions

What file formats can I import into Diagram-Design?

You can import standalone .mmd or .mermaid files, or Markdown files containing fenced mermaid code blocks. The extractor automatically detects and parses all supported grammar types within these files.

Why doesn't my Mermaid styling appear in the output?

Diagram-Design intentionally discards Mermaid-specific styling—including classDef, style, and linkStyle declarations—to ensure consistent, accessible output. The redraw phase applies only the color palette and typography defined in style-guide.md, using a single accent color plus ink and muted tones.

How do I handle multiple diagrams in one Markdown file?

Use the --diagram flag with all to process every fenced mermaid block separately: /diagram-design:import-mermaid docs/file.md --diagram=all. This generates numbered output files for each diagram found. Alternatively, specify a number (--diagram=2) to target a specific block.

What happens if the extractor fails?

If mermaid_extract.py exits with code 2, Diagram-Design reports the extractor's error message verbatim and aborts the import process. This typically indicates unsupported grammar, malformed syntax, or file access issues. Check that your Mermaid syntax is valid and uses one of the four supported grammars.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}