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

> Easily import Mermaid diagrams into Diagram Design using the import-mermaid command. This guide shows developers how to parse Mermaid source and redraw diagrams with Diagram Design's powerful tools.

- Repository: [Cathryn Lavery/diagram-design](https://github.com/cathrynlavery/diagram-design)
- Tags: how-to-guide
- Published: 2026-08-14

---

**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`](https://github.com/cathrynlavery/diagram-design/blob/main/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`](https://github.com/cathrynlavery/diagram-design/blob/main/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`](https://github.com/cathrynlavery/diagram-design/blob/main/style-guide.md) skin settings for colors, fonts, and accessibility. A fidelity ledger reports what was merged, collapsed, or dropped.

---

## Command Reference

### Basic Syntax

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

```

The command definition lives in [`commands/import-mermaid.md`](https://github.com/cathrynlavery/diagram-design/blob/main/commands/import-mermaid.md) and points to [`references/import-mermaid.md`](https://github.com/cathrynlavery/diagram-design/blob/main/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

```bash

# Redraw to HTML with default settings

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

```

### Full-Featured Export for Presentations

```bash

# 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`](https://github.com/cathrynlavery/diagram-design/blob/main/outputs/my-diagram.html)
- `outputs/my-diagram.png`

### Process All Mermaid Blocks in a Markdown File

```bash

# 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

```bash

# Force Architecture layout even for flowchart grammar

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

```

### Extract IR as JSON for Custom Processing

```bash
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`](https://github.com/cathrynlavery/diagram-design/blob/main/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`](https://github.com/cathrynlavery/diagram-design/blob/main/skills/diagram-design/references/import-mermaid.md)** — Canonical import procedure with anti-pattern rules and grammar support matrix.

- **[`commands/import-mermaid.md`](https://github.com/cathrynlavery/diagram-design/blob/main/commands/import-mermaid.md)** — Slash-command definition with argument schema and routing logic.

- **[`skills/diagram-design/references/output-spec.md`](https://github.com/cathrynlavery/diagram-design/blob/main/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`](https://github.com/cathrynlavery/diagram-design/blob/main/scripts/verify-mermaid-import.py)** — CI validation script ensuring extractor, references, and command wiring stay synchronized.

- **[`skills/diagram-design/SKILL.md`](https://github.com/cathrynlavery/diagram-design/blob/main/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`](https://github.com/cathrynlavery/diagram-design/blob/main/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`](https://github.com/cathrynlavery/diagram-design/blob/main/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`](https://github.com/cathrynlavery/diagram-design/blob/main/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`](https://github.com/cathrynlavery/diagram-design/blob/main/output-spec.md) §6) — Verifies format compliance and resource limits.

In CI, [`scripts/verify-mermaid-import.py`](https://github.com/cathrynlavery/diagram-design/blob/main/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`](https://github.com/cathrynlavery/diagram-design/blob/main/style-guide.md) skins.
- Key files: [`mermaid_extract.py`](https://github.com/cathrynlavery/diagram-design/blob/main/mermaid_extract.py) for parsing, [`import-mermaid.md`](https://github.com/cathrynlavery/diagram-design/blob/main/import-mermaid.md) for procedure, and [`output-spec.md`](https://github.com/cathrynlavery/diagram-design/blob/main/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`](https://github.com/cathrynlavery/diagram-design/blob/main/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`](https://github.com/cathrynlavery/diagram-design/blob/main/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.