What draw.io and Mermaid Elements Are Preserved During Import to Diagram-Design

Diagram-Design retains basic shapes, text labels, styling attributes, persistent IDs, hierarchical groups, connectors, and hyperlinks when importing draw.io and Mermaid files, while stripping embedded images and unsupported extensions.

The cathrynlavery/diagram-design repository supports importing diagrams from both draw.io (.drawio, .drawio.png, .drawio.svg) and Mermaid (.mmd) formats into its internal model. When you import files, the extraction pipeline in skills/diagram-design/scripts/drawio_extract.py and skills/diagram-design/scripts/mermaid_extract.py translates compatible elements while discarding anything that cannot be represented natively. Understanding exactly which draw.io and Mermaid elements are preserved during import ensures your diagrams maintain their structure and visual fidelity.

Preserved draw.io Elements

Basic Shapes and Geometry

All standard draw.io shape types—including rectangles, ellipses, diamonds, and custom geometry—are mapped directly to Diagram-Design shape objects. The import process preserves the exact dimensions and positioning defined in the original XML.

Text and Labels

Multiline text content inside draw.io cells survives the import intact. The drawio_extract.py parser extracts label content and maintains line breaks and basic formatting.

Styling Attributes

The following visual properties are retained:

• Fill colour and stroke colour
• Stroke width and line-style (solid or dashed)
• Round-corner radius settings

These attributes are extracted from the style sections of draw.io cells and applied to the corresponding Diagram-Design objects.

IDs and Custom Data

The id attribute of each mxGraph cell is preserved as a persistent identifier. This allows later reference and linking between diagram elements after import.

Groups and Layers

mxGraph "group" cells become Diagram-Design layers, preserving the hierarchical nesting structure of your original diagram. Parent-child relationships between containers and their contents remain intact.

Connectors and Routing

Edge definitions—including source/target references, routing points, and arrow head styles—are maintained. The import retains directional flow and connection logic.

Hyperlinks

Cell link attributes are converted to clickable URLs in the resulting diagram, preserving interactivity.

Unsupported draw.io Features

Embedded raster images are not imported and are stripped out during extraction. Additionally, any elements relying on draw.io-only extensions—such as custom XML tags or scripts—are discarded.

Preserved Mermaid Elements

Node Definitions and IDs

Mermaid node identifiers (the text before [ or ( characters) are preserved as persistent IDs. Node definitions from graph, flowchart, stateDiagram, and other diagram types are mapped to corresponding shape objects.

Edges and Connectors

Edge definitions using -->, ---, -.->, and other arrow syntax are translated into directional connectors. The mermaid_extract.py script maintains the relationship logic between nodes.

Labels and Text

Node labels and edge labels are retained exactly as written in the source .mmd file, including any text formatting.

Styling Directives

Mermaid style commands are translated into Diagram-Design attributes:

• style assignments for individual nodes
• classDef definitions for reusable style classes
• linkStyle directives for edge appearance

Sub-graphs and Nesting

Sub-graphs defined with subgraph … end syntax are kept as nested groups within Diagram-Design, preserving containment hierarchies.

Hyperlinks

Mermaid link syntax (click … "url") is preserved as interactive links in the final diagram.

Unsupported Mermaid Features

Since Mermaid does not support embedded raster images, none are imported. Extensions not recognized by Diagram-Design are ignored during parsing.

Verification and Quality Assurance

The repository includes automated verification scripts that assert exactly which elements survive the import pipeline.

The scripts/verify-drawio-import.py script validates that imports retain .drawio extensions, cell IDs, style sections, and supported containers (.drawio.png, .drawio.svg). It also verifies that commands/import-drawio.md documentation accurately reflects these preserved elements.

The scripts/verify-mermaid-import.py script performs analogous checks for Mermaid files, ensuring node IDs, edge definitions, and style directives survive conversion and that commands/import-mermaid.md remains accurate.

These tests guarantee that only the supported elements described above are kept, while unsupported features are safely omitted.

How to Import Files

Use the CLI commands to import diagrams while preserving the supported elements:

# Import a draw.io file (preserves shapes, text, colours, IDs, layers)

diagram-design import-drawio my-diagram.drawio

# Import a Mermaid file (preserves nodes, edges, labels, sub-graphs, styles)

diagram-design import-mermaid flowchart.mmd

After execution, inspect the retained elements using:

diagram-design view my-diagram

Key Source Files

The import functionality is implemented across the following files:

• skills/diagram-design/scripts/drawio_extract.py – Core extractor that parses draw.io XML and translates supported elements into the internal model.

• skills/diagram-design/scripts/mermaid_extract.py – Core extractor that parses Mermaid source files and maps compatible syntax.

• scripts/verify-drawio-import.py – Automated verification that draw.io imports retain supported elements and documentation accuracy.

• scripts/verify-mermaid-import.py – Verification script for Mermaid import integrity.

• commands/import-drawio.md – User-facing documentation describing the draw.io import process and supported features.

• commands/import-mermaid.md – Documentation for Mermaid import capabilities and preserved elements.

Summary

• draw.io imports preserve standard shapes, text labels, colours, stroke styles, cell IDs, groups, edge routing, and hyperlinks, but strip embedded images and custom scripts.
• Mermaid imports retain node definitions, edge connections, labels, style directives, sub-graphs, and click URLs, ignoring unsupported extensions.
• The verification scripts in scripts/verify-drawio-import.py and scripts/verify-mermaid-import.py enforce these preservation rules.
• Core extraction logic resides in skills/diagram-design/scripts/drawio_extract.py and mermaid_extract.py.

Frequently Asked Questions

What happens to images in draw.io files during import?

Embedded raster images are stripped out and not included in the Diagram-Design model. Only vector geometry and text elements survive the import process. If your diagram relies on images, you must re-add them manually after import or convert them to vector shapes first.

Are custom draw.io plugins or scripts preserved?

No. Any elements depending on draw.io-only extensions, custom XML tags, or embedded scripts are discarded during import. The extraction pipeline in drawio_extract.py focuses solely on standard mxGraph elements that map to Diagram-Design's internal representation.

Do Mermaid theme settings transfer to Diagram-Design?

Mermaid classDef and inline style directives are preserved and translated into Diagram-Design styling attributes. However, global theme declarations that affect the entire diagram canvas may not map directly, as Diagram-Design uses its own styling system defined in the import pipeline.

Can I import draw.io files with multiple pages?

The current implementation in drawio_extract.py processes the standard diagram structure. While individual elements from the active or default page are preserved, multi-page handling depends on how the specific file structure is parsed. Check commands/import-drawio.md for the latest supported capabilities regarding multi-page documents.

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