# What draw.io and Mermaid Elements Are Preserved During Import to Diagram-Design > Learn what draw io and Mermaid elements Diagram Design preserves during import including shapes text styling groups connectors and hyperlinks - Repository: [Cathryn Lavery/diagram-design](https://github.com/cathrynlavery/diagram-design) - Tags: api-reference - Published: 2026-08-17 --- **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`](https://github.com/cathrynlavery/diagram-design/blob/main/skills/diagram-design/scripts/drawio_extract.py) and [`skills/diagram-design/scripts/mermaid_extract.py`](https://github.com/cathrynlavery/diagram-design/blob/main/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`](https://github.com/cathrynlavery/diagram-design/blob/main/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`](https://github.com/cathrynlavery/diagram-design/blob/main/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`](https://github.com/cathrynlavery/diagram-design/blob/main/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`](https://github.com/cathrynlavery/diagram-design/blob/main/commands/import-drawio.md) documentation accurately reflects these preserved elements. The **[`scripts/verify-mermaid-import.py`](https://github.com/cathrynlavery/diagram-design/blob/main/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`](https://github.com/cathrynlavery/diagram-design/blob/main/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: ```bash # 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: ```bash diagram-design view my-diagram ``` ## Key Source Files The import functionality is implemented across the following files: - **[`skills/diagram-design/scripts/drawio_extract.py`](https://github.com/cathrynlavery/diagram-design/blob/main/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`](https://github.com/cathrynlavery/diagram-design/blob/main/skills/diagram-design/scripts/mermaid_extract.py)** – Core extractor that parses Mermaid source files and maps compatible syntax. - **[`scripts/verify-drawio-import.py`](https://github.com/cathrynlavery/diagram-design/blob/main/scripts/verify-drawio-import.py)** – Automated verification that draw.io imports retain supported elements and documentation accuracy. - **[`scripts/verify-mermaid-import.py`](https://github.com/cathrynlavery/diagram-design/blob/main/scripts/verify-mermaid-import.py)** – Verification script for Mermaid import integrity. - **[`commands/import-drawio.md`](https://github.com/cathrynlavery/diagram-design/blob/main/commands/import-drawio.md)** – User-facing documentation describing the draw.io import process and supported features. - **[`commands/import-mermaid.md`](https://github.com/cathrynlavery/diagram-design/blob/main/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`](https://github.com/cathrynlavery/diagram-design/blob/main/scripts/verify-drawio-import.py) and [`scripts/verify-mermaid-import.py`](https://github.com/cathrynlavery/diagram-design/blob/main/scripts/verify-mermaid-import.py) enforce these preservation rules. - Core extraction logic resides in [`skills/diagram-design/scripts/drawio_extract.py`](https://github.com/cathrynlavery/diagram-design/blob/main/skills/diagram-design/scripts/drawio_extract.py) and [`mermaid_extract.py`](https://github.com/cathrynlavery/diagram-design/blob/main/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`](https://github.com/cathrynlavery/diagram-design/blob/main/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`](https://github.com/cathrynlavery/diagram-design/blob/main/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`](https://github.com/cathrynlavery/diagram-design/blob/main/commands/import-drawio.md) for the latest supported capabilities regarding multi-page documents.