# How to Convert Mermaid Diagrams to Diagram-Design IR: The Complete Guide

> Easily convert Mermaid diagrams to Diagram-Design IR with the built-in import-mermaid command. Follow this complete guide to streamline your diagramming workflow.

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

---

**Yes—Diagram-Design provides a built-in `import-mermaid` command that parses Mermaid source code and outputs the library's JSON-based intermediate representation (IR).**

The diagram-design repository by cathrynlavery includes native support for converting Mermaid diagrams into its structured IR format. This conversion enables you to import existing Mermaid workflows, flowcharts, and sequence diagrams for further processing, export to other formats, or integration with the broader Diagram-Design toolchain.

## How the Mermaid-to-IR Conversion Works

The `import-mermaid` command performs a four-stage pipeline to transform Mermaid syntax into Diagram-Design's native structure. According to the repository's command documentation at [[`commands/import-mermaid.md`](https://github.com/cathrynlavery/diagram-design/blob/main/commands/import-mermaid.md)](https://github.com/cathrynlavery/diagram-design/blob/main/commands/import-mermaid.md), the process follows this flow:

1. **Read the Mermaid source** — the input file is loaded as plain text.
2. **Parse with Mermaid** — the command uses the official `mermaidAPI` JavaScript parser to build an AST.
3. **Transform to Diagram-Design IR** — a mapper walks the AST and generates Diagram-Design-specific nodes including `Node`, `Edge`, `Group`, and `Style` objects.
4. **Write the IR** — the resulting JSON is serialized to your specified output location.

The IR itself is defined in the core source tree (typically [`src/ir.ts`](https://github.com/cathrynlavery/diagram-design/blob/main/src/ir.ts)), which establishes the schema for diagram topology, styling, and metadata that all other Diagram-Design commands consume.

## Converting Mermaid to IR: CLI Commands

### Basic File Conversion

Convert a `.mmd` file to IR with explicit input and output paths:

```bash
diagram-design import-mermaid \
  --input my-diagram.mmd \
  --output my-diagram.ir.json

```

### Pipeline from stdin

Process Mermaid source through Unix pipes for automation workflows:

```bash
cat my-diagram.mmd | diagram-design import-mermaid \
  --output my-diagram.ir.json

```

### Chained Workflow

Combine conversion with export to generate finalized assets:

```bash
diagram-design import-mermaid --input flow.mmd --output flow.ir.json && \
diagram-design export-diagram --input flow.ir.json --format svg --output flow.svg

```

## Working with the IR Programmatically

Once converted, the IR is standard JSON that any language can manipulate. Here's a Python example for inspecting node structures:

```python
import json
from pathlib import Path

ir_path = Path("my-diagram.ir.json")
ir_data = json.loads(ir_path.read_text())

# Extract all nodes from the elements array

nodes = [n for n in ir_data["elements"] if n["type"] == "node"]
print("Nodes:", [n["id"] for n in nodes])

# Example: find all edges

edges = [e for e in ir_data["elements"] if e["type"] == "edge"]
print(f"Found {len(edges)} connections between nodes")

```

The IR structure follows the schema defined in the core source, with each element containing standardized fields for identifiers, positional data, styling properties, and relationship metadata.

## Key Implementation Files

| File | Purpose |
|------|---------|
| [`commands/import-mermaid.md`](https://github.com/cathrynlavery/diagram-design/blob/main/commands/import-mermaid.md) | CLI documentation and usage reference |
| [`src/import/mermaid.ts`](https://github.com/cathrynlavery/diagram-design/blob/main/src/import/mermaid.ts) | Parser implementation and AST-to-IR transformer |
| [`src/ir.ts`](https://github.com/cathrynlavery/diagram-design/blob/main/src/ir.ts) | IR schema definition for nodes, edges, groups, and styles |

These files work together to provide end-to-end Mermaid compatibility without requiring manual parser invocation or custom mapping logic.

## Supported Mermaid Diagram Types

The `import-mermaid` command handles the most commonly used Mermaid syntax variants. Based on the parser implementation leveraging `mermaidAPI`, you can expect reliable conversion for:

- **Flowcharts** — directional graphs with nodes and edges
- **Sequence diagrams** — actor interactions and message flows
- **Class diagrams** — inheritance and association relationships
- **State diagrams** — state machines and transitions
- **Entity relationship diagrams** — database schema representations

Complex diagrams with extensive custom styling may require post-conversion adjustment of the IR's `Style` objects.

## Summary

- **Use `diagram-design import-mermaid`** to convert Mermaid source to IR without manual parsing.
- The conversion pipeline leverages the official `mermaidAPI` parser for AST generation.
- Output IR conforms to the schema in [`src/ir.ts`](https://github.com/cathrynlavery/diagram-design/blob/main/src/ir.ts) with standardized `Node`, `Edge`, `Group`, and `Style` objects.
- The resulting JSON integrates directly with `export-diagram`, `doctor`, and custom Diagram-Design plugins.
- Both file-based and stdin input modes support automation and CI/CD workflows.

## Frequently Asked Questions

### What is Diagram-Design IR?

**Diagram-Design IR (Intermediate Representation)** is a JSON-based format that serves as the central data model for all diagram operations in the library. It decouples parsing from rendering, enabling multiple import sources (Mermaid, Draw.IO, etc.) and multiple export targets (SVG, PNG, PDF, etc.) through a unified internal structure.

### Can I convert IR back to Mermaid format?

The repository focuses on import functionality; bidirectional conversion would require a custom exporter. The IR schema in [`src/ir.ts`](https://github.com/cathrynlavery/diagram-design/blob/main/src/ir.ts) contains sufficient topology information to regenerate Mermaid syntax, though no built-in `export-mermaid` command is documented in the current release.

### Does the import preserve Mermaid styling?

**Partially.** The mapper extracts explicit style definitions and CSS classes into IR `Style` objects. However, Mermaid's default theme variables and runtime-rendered styling may not translate completely. Review the `style` properties in your output IR and adjust as needed before final export.

### Can I use import-mermaid in programmatic JavaScript/TypeScript?

While the CLI is the primary interface, the underlying parser in [`src/import/mermaid.ts`](https://github.com/cathrynlavery/diagram-design/blob/main/src/import/mermaid.ts) exposes functions that can be imported directly. The `mermaidAPI` dependency and transformation logic are available for integration into custom build tools or web applications requiring server-side diagram processing.