Walkthrough: migrating a draw.io diagram

The example below is a four-shape support flow saved from diagrams.net (support-flow.drawio). Every step was run against the app and checked.

1. Bring the file in#

Import Diagram in the toolbar, or Ctrl/⌘ O, and pick the .drawio file.

Detection is by content, not extension, and all the shapes draw.io saves in are understood:

• a bare <mxGraphModel>,
• <mxfile><diagram> with uncompressed XML inside,
• <mxfile><diagram> with the default deflate-raw → base64 → URI-encoded payload,
• <mxlibrary> blobs.

So a .xml file, a .drawio file and a paste of the same bytes all land the same way.

2. Choose where it lands#

The dialog reports what it recognised — “draw.io · support-flow.drawio — 4 shapes · 3 connectors” — and offers:

• Import into this page — merged at the viewport centre, nudged clear of what is already there, ids rewritten with a paste_ prefix, everything that arrived left selected, all in one undo entry.
• Import as new document — replaces the current document.

Anything the reader had to approximate is listed as a warning here, and repeated in the toast.

3. What comes across#

In the run above, 4 shapes and 3 connectors arrived, the labels came through verbatim (Ticket raised, Triage, Urgent?, Escalate), the edge label yes survived, and rhombus correctly became a decision.

4. Make it look like it belongs#

Once it is in, it is an ordinary document:

1. R — Smart Route re-routes the imported connectors around the shapes.
2. Select everything (Ctrl/⌘ A) → right-click → Arrange ▸ Size ▸ Match width and Align ▸ Distribute vertically, or AI: check this diagram for problems and apply the mechanical fixes.
3. Inspector ▸ Theme to put it on the house palette; per-shape overrides from draw.io survive on top, so Reset in the Typography section is the quick way to make a shape follow the theme again.
4. Right-click → Change shape for anything that landed as a plain rectangle.

5. Going back the other way#

Export ▸ draw.io writes mxGraph cells, including the UML and crow's-foot arrow heads, so a colleague can carry on in diagrams.net. Export ▸ Mermaid gives the text form — for the imported flow above it produces:

flowchart TD
  n1(("Ticket raised"))
  n2["Triage"]
  n3{"Urgent?"}
  n4["Escalate"]
  n1 --> n2
  n2 --> n3
  n3 -->|yes| n4

Migrating a whole folder#

There is no batch importer in the UI. Two options:

• Import them one at a time, adding each as a page of one document (toolbar Page, then import into that page), and export the result as a single PDF or one Plota JSON.
• Drive the MCP server (the sibling mcp-diagram-server repository) from an agent: import_diagram per file, then export_diagram. Its readers are the same ones this app uses.