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

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), 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), 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:

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:

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

Chained Workflow

Combine conversion with export to generate finalized assets:

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:

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	CLI documentation and usage reference
src/import/mermaid.ts	Parser implementation and AST-to-IR transformer
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 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 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 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.

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