What Draw.io and Mermaid Elements Are Not Carried Over During Import to Diagram-Design

Embedded raster images, custom draw.io XML extensions, embedded scripts, and unrecognized Mermaid extensions are stripped during import, while basic shapes, text labels, styling attributes, and connectors are fully preserved.

When importing diagrams into Diagram-Design from draw.io or Mermaid sources, the extraction pipeline defined in skills/diagram-design/scripts/drawio_extract.py and mermaid_extract.py intentionally filters out proprietary and binary elements that cannot be expressed in the internal model. Only structural and stylistic components that map directly to Diagram-Design's object model survive the conversion, ensuring consistent rendering across .drawio, .drawio.png, .drawio.svg, and .mmd file formats.

Draw.io Elements Removed During Import

While the drawio_extract.py parser retains standard geometry and styling, several draw.io-specific features are deliberately discarded.

Embedded Images and Binary Assets

Embedded raster images are not imported and are stripped out during the extraction process. The drawio_extract.py script processes the XML structure of .drawio, .drawio.png, and .drawio.svg files but cannot convert embedded binary image data into Diagram-Design's vector-based model. If your diagram relies on imported PNGs or JPEGs within draw.io cells, these will appear as empty placeholders or be removed entirely after import.

Custom XML Extensions and Scripts

Any element that relies on draw.io-only extensions—including custom XML tags, embedded JavaScript, or proprietary mxGraph extensions—is discarded. The parser validates elements against the supported subset defined in commands/import-drawio.md, silently removing script tags and unrecognized XML namespaces that could execute code or reference external resources.

Mermaid Elements Removed During Import

The mermaid_extract.py processor handles standard Mermaid syntax but ignores unsupported directives.

Unrecognized Mermaid Extensions

Mermaid extensions not recognized by Diagram-Design are ignored during import. While standard flowcharts, state diagrams, and sequence diagrams convert correctly, any custom Mermaid plugins or extended syntax not documented in commands/import-mermaid.md are stripped. The verification script scripts/verify-mermaid-import.py explicitly checks that only recognized node definitions, edge types, and style directives survive the conversion.

What Elements Are Preserved During Import

Understanding what survives the import process clarifies the boundaries of the filtering logic. According to the verification scripts scripts/verify-drawio-import.py and scripts/verify-mermaid-import.py, the following elements are retained:

• Basic Shapes and Nodes: All standard draw.io shape types (rectangles, ellipses, diamonds) and Mermaid node definitions map to corresponding shape objects.
• Text and Labels: Multiline text inside draw.io cells and Mermaid node/edge labels are preserved exactly.
• Styling Attributes: Fill color, stroke color, stroke width, line style (solid/dashed), and round-corner radius are kept, along with Mermaid style, classDef, and linkStyle directives.
• Structural Hierarchy: Draw.io mxGraph groups become Diagram-Design layers, while Mermaid sub-graphs (subgraph … end) convert to nested groups.
• Connectivity: Edge source/target relationships, routing points, arrow heads, and Mermaid connectors (-->, ---, -.->) are maintained.
• Identifiers and Hyperlinks: Draw.io cell id attributes and Mermaid node IDs persist as referenceable IDs, while link attributes and Mermaid click syntax become interactive URLs.

How the Import Pipeline Validates Element Retention

The repository includes automated verification to ensure only supported elements survive import.

scripts/verify-drawio-import.py asserts that extracted data retains .drawio extensions, cell IDs, style sections, and that reference documentation (commands/import-drawio.md) accurately reflects supported containers. This script validates that binary image data and custom XML extensions are absent from the output.

scripts/verify-mermaid-import.py performs analogous checks for Mermaid imports, confirming that node IDs, edge definitions, and style directives survive while unrecognized extensions are filtered. Both scripts run against the core extractors to guarantee compliance with the supported feature set.

Import Commands and Verification

Import supported draw.io content while accepting that images will be stripped:

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

diagram-design import-drawio my-diagram.drawio

Import Mermaid flowcharts with standard syntax:

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

diagram-design import-mermaid flowchart.mmd

After each command, inspect the resulting diagram to verify retention:

diagram-design view my-diagram.drawio

Summary

• Embedded raster images in draw.io files are stripped and not converted.
• Custom draw.io XML extensions, scripts, and proprietary tags are discarded during parsing.
• Unrecognized Mermaid extensions and custom plugins are ignored.
• The verification scripts (verify-drawio-import.py and verify-mermaid-import.py) automatically confirm that only compatible elements survive import.
• Core extractors (drawio_extract.py and mermaid_extract.py) define the supported subset referenced in commands/import-drawio.md and commands/import-mermaid.md.

Frequently Asked Questions

Does Diagram-Design support importing draw.io files with embedded PNG images?

No. While Diagram-Design accepts .drawio, .drawio.png, and .drawio.svg file extensions, the import pipeline specifically strips embedded raster images during extraction. Only vector-based shapes and text defined in the draw.io XML structure survive the conversion process handled by skills/diagram-design/scripts/drawio_extract.py.

What happens to custom scripts in my draw.io diagrams?

Any JavaScript or custom XML scripts embedded within draw.io files are discarded. The drawio_extract.py parser validates elements against the supported subset and removes draw.io-only extensions that could pose security risks or fail to render in Diagram-Design's simplified model.

Are Mermaid class diagrams fully supported during import?

Standard Mermaid syntax for flowcharts, state diagrams, and sequence diagrams imports correctly, including classDef styling and subgraph structures. However, unrecognized Mermaid extensions or custom plugin syntax are filtered out by mermaid_extract.py and will not appear in the final diagram.

How can I verify what elements survived the import process?

Run the verification scripts included in the repository. scripts/verify-drawio-import.py and scripts/verify-mermaid-import.py automatically check that IDs, styles, and structural elements are preserved while confirming that restricted elements like embedded images have been removed. You can also manually inspect the output using diagram-design view <filename>.

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