# How to Import Mermaid Diagrams into the Diagram Design Tool

> Easily import Mermaid diagrams into the Diagram Design tool using the import-mermaid command. Convert .mmd or Markdown files for clean, style-agnostic redesigns.

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

---

**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`](https://github.com/cathrynlavery/diagram-design/blob/main/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`](https://github.com/cathrynlavery/diagram-design/blob/main/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`](https://github.com/cathrynlavery/diagram-design/blob/main/skills/diagram-design/references/import-mermaid.md) without manual configuration.

### Parsing and Normalization

The [`skills/diagram-design/references/import-mermaid.md`](https://github.com/cathrynlavery/diagram-design/blob/main/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`](https://github.com/cathrynlavery/diagram-design/blob/main/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`](https://github.com/cathrynlavery/diagram-design/blob/main/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:

```text

# 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:

```bash
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`](https://github.com/cathrynlavery/diagram-design/blob/main/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`](https://github.com/cathrynlavery/diagram-design/blob/main/skills/diagram-design/SKILL.md), which maps file extensions to the import pipeline.
- The parsing logic in [`skills/diagram-design/references/import-mermaid.md`](https://github.com/cathrynlavery/diagram-design/blob/main/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`](https://github.com/cathrynlavery/diagram-design/blob/main/skills/diagram-design/references/output-spec.md).
- The command implementation lives in [`commands/import-mermaid.md`](https://github.com/cathrynlavery/diagram-design/blob/main/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`](https://github.com/cathrynlavery/diagram-design/blob/main/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`](https://github.com/cathrynlavery/diagram-design/blob/main/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`](https://github.com/cathrynlavery/diagram-design/blob/main/skills/diagram-design/SKILL.md) handles routing, [`skills/diagram-design/references/import-mermaid.md`](https://github.com/cathrynlavery/diagram-design/blob/main/skills/diagram-design/references/import-mermaid.md) defines the parsing algorithm, [`skills/diagram-design/references/output-spec.md`](https://github.com/cathrynlavery/diagram-design/blob/main/skills/diagram-design/references/output-spec.md) sets rendering constraints, and [`commands/import-mermaid.md`](https://github.com/cathrynlavery/diagram-design/blob/main/commands/import-mermaid.md) provides the user-facing command interface.