How to Import Mermaid Diagrams into the Diagram Design Tool

The Diagram Design tool provides a built-in import-mermaid command that converts .mmd, .mermaid, or Markdown files containing fenced Mermaid blocks into the tool's internal diagram model while stripping visual styling to guarantee clean, style-agnostic redesigns.

The cathrynlavery/diagram-design repository ships with a declarative import pipeline that ingests existing Mermaid definitions and transforms them into the tool's native design system. This process extracts only structural information—components, relationships, and grouping—while explicitly discarding original coordinates, color palettes, and layout directives.

Supported File Formats and Route Detection

The import system recognizes source files through extension mapping defined in skills/diagram-design/SKILL.md. The tool accepts:

• .mmd and .mermaid files containing raw Mermaid syntax
• .drawio* files (draw.io XML variants)
• Markdown files with fenced mermaid code blocks

When you invoke the import command, the SKILL definition routes these file types to the appropriate reference processor automatically.

The Import Pipeline Architecture

Route Detection and File Routing

In skills/diagram-design/SKILL.md, the system maps source file extensions to specific import references. This declarative routing ensures that Mermaid-specific files trigger the correct parsing logic located in skills/diagram-design/references/import-mermaid.md without manual configuration.

Parsing and Normalization

The skills/diagram-design/references/import-mermaid.md reference file defines the parsing algorithm that converts raw Mermaid source into the internal diagram model. According to the implementation, the parser extracts structural elements—including nodes, edges, subgraphs, and directional flow—while intentionally ignoring visual attributes such as positioning, colors, fonts, and auto-layout hints.

Output Specification

After parsing, the pipeline consults skills/diagram-design/references/output-spec.md to determine rendering constraints. This specification controls output parameters including size (doc-inline, slide-16x9), detail level (simplified, balanced, comprehensive), and audience targeting (technical, executive, mixed).

Command Execution

The concrete user-facing implementation resides in commands/import-mermaid.md. This command file forwards arguments to the import routine and returns rendered output according to the selected specification from the output spec.

Import Commands and Syntax

Chat Interface Usage

Within the Pi chat interface, invoke the import using the following syntax:

# Import a standalone Mermaid file

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

# Import from Markdown containing fenced blocks

/diagram-design:import-mermaid README.md --diagram=all

# Control output format and detail level

/diagram-design:import-mermaid architecture.mmd \
    --size=slide-16x9 \
    --detail=simplified \
    --audience=executive

CLI Implementation

When using the CLI wrapper (dd), the syntax follows standard POSIX conventions:

dd import-mermaid path/to/diagram.mmd \
    --size=doc-inline \
    --detail=balanced \
    --audience=mixed

The command returns an HTML snippet (or your specified format) ready for embedding in presentations or documentation.

Data Integrity and Design Constraints

The import process enforces a strict separation of structure and style. According to skills/diagram-design/references/import-mermaid.md, the pipeline guarantees that:

• Preserved: Component hierarchies, relationship types, directional flow, and grouping semantics
• Discarded: X/Y coordinates, hex color codes, font families, stroke widths, and auto-layout engines

This architectural constraint ensures that imported diagrams receive a clean visual redesign consistent with the Diagram Design system's aesthetic standards, rather than inheriting potentially inconsistent styling from the source Mermaid.

Summary

• The Diagram Design tool supports importing .mmd, .mermaid, and Markdown files containing fenced Mermaid blocks via the import-mermaid command.
• Route detection occurs in skills/diagram-design/SKILL.md, which maps file extensions to the import pipeline.
• The parsing logic in skills/diagram-design/references/import-mermaid.md extracts only structural data, guaranteeing style-agnostic output.
• Rendering parameters (size, detail, audience) are controlled by skills/diagram-design/references/output-spec.md.
• The command implementation lives in commands/import-mermaid.md and supports both chat interface and CLI invocations.

Frequently Asked Questions

What file formats does the Diagram Design tool support for Mermaid import?

The tool recognizes files ending in .mmd or .mermaid, Markdown documents containing fenced mermaid code blocks, and .drawio* variants. The routing logic in skills/diagram-design/SKILL.md automatically directs these formats to the import pipeline.

Does the import preserve my original Mermaid styling and colors?

No. According to the reference implementation in skills/diagram-design/references/import-mermaid.md, the import process explicitly discards visual attributes including coordinates, color palettes, fonts, and layout engines. Only structural information—components, relationships, and grouping—is retained to ensure the diagram conforms to the Diagram Design system's visual language.

How do I import multiple diagrams from a single Markdown file?

Use the --diagram=all flag when importing a Markdown file that contains multiple fenced Mermaid blocks. The parser defined in the import reference processes all detected blocks and generates corresponding diagram outputs according to the specified parameters.

Where is the import logic implemented in the source code?

The import logic spans four critical files: skills/diagram-design/SKILL.md handles routing, skills/diagram-design/references/import-mermaid.md defines the parsing algorithm, skills/diagram-design/references/output-spec.md sets rendering constraints, and commands/import-mermaid.md provides the user-facing command interface.

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