Docs / Reference

Importing draw.io, PlantUML and Visio

Turn draw.io, Visio and PlantUML files into Yantra diagrams and answer pages with yantra import, then review the warnings and add a walkthrough.

Besides Mermaid (mermaid.md), Yantra imports draw.io / diagrams.net files (also PNG exports with the diagram embedded), Visio .vsdx files and PlantUML sequence, component / deployment / use-case, activity (new and old syntax), state, class, object and entity-relationship diagrams, mind maps, work breakdowns and Gantt charts. Each import produces a normal payload (roles, groups, a walkthrough) that you then review, label and extend. The parsers are small and dependency-free (src/core/drawio.js, src/core/visio.js, src/core/plantuml.js, chart pages in src/core/importcharts.js, shared assembly in src/core/importkit.js); they run in Node and in the browser. They are best effort, so read the warnings they print.

yantra import architecture.drawio              # -> architecture.json, then lint report
yantra import export.xml                       # uncompressed draw.io XML export
yantra import diagram.drawio.svg               # draw.io SVG with the embedded diagram
yantra import diagram.drawio.png               # draw.io PNG export with the diagram embedded
yantra import process.vsdx                     # Visio (2013+): shapes and glued connectors
yantra import model.drawio --page 2            # pick a page by number ...
yantra import model.drawio --page "Payments"   # ... or by name
yantra import model.drawio --all               # every page -> model-1.json, model-2.json, ...
yantra import login.puml                       # PlantUML (.puml, .plantuml, .pu, .iuml, .wsd)
yantra import notes.md                         # first ```plantuml / ```puml (or ```mermaid) block
yantra import diagram.txt --from plantuml      # force the format: mermaid | drawio | plantuml | visio

Format detection. A zip archive is Visio and a PNG is draw.io, whatever the name; then --from wins; otherwise the extension (.vsdx → Visio; .drawio, .dio, .drawio.xml, .drawio.svg, .drawio.png → draw.io; .puml & co. → PlantUML; .mmd → Mermaid), then the content (<mxfile> / <mxGraphModel> → draw.io, @startuml / @startgantt or a plantuml code fence → PlantUML), else Mermaid. Chart-like sources (Mermaid gantt / pie / timeline / quadrantChart, PlantUML @startgantt) become answer pages ("kind": "page").

The command prints import warnings, writes the JSON, validates it and exits 1 only if validation reports errors.

• MCP: yantra_import with { text | filePath, format?, page?, all?, title?, outputPath? } returns { format, payload | outputPath, warnings, validation } (with all: { format, results: [...] }). filePath must be inside YANTRA_INPUT_ROOT and end with a known extension (.mmd .md .drawio .dio .xml .svg .png .vsdx .puml .plantuml .pu .iuml .wsd .txt); PlantUML !include is resolved inside YANTRA_INPUT_ROOT only; outputPath must be a .json inside YANTRA_OUTPUT_ROOT. yantra_import_mermaid is kept for compatibility.
• JavaScript: importText(textOrBytes, { format?, filename?, title?, page?, all?, include?, path? }) from src/core/import.js (bytes: a .vsdx, a PNG, or UTF-8 text; include(target, fromPath) resolves PlantUML includes, see lib/includes.js for the Node one), or fromDrawio(text, { title, page }) / fromPlantUml(text, { title, include?, path? }) / fromVisio(bytes, { title, page }).
• Python: yantra.import_diagram("model.drawio", format=None, page=None, title=None) (also .vsdx, .drawio.png) returns the payload as a dict (runs the CLI, so Node.js >= 20.19 is needed).

Samples: examples/drawio/ (plain, compressed, an ER schema, payment-services.drawio with fill colours and cloud icons, support-triage.drawio.png), examples/visio/order-approval.vsdx and examples/plantuml/ (including shop-entities.puml, order-objects.puml, launch-plan.puml (Gantt), legacy-approval.puml (old activity syntax) and shared-services.puml, which includes shared/styles.iuml). Every sample imports and validates with no warnings.

#draw.io / diagrams.net

Coordinates are ignored; the only thing taken from the drawing is the direction: LR when edges mostly run sideways, else TB. Ids come from labels (Orders DB → orders-db). Waypoints are ignored by design: layout and routing are automatic, so hand-placed bends would fight the router. Fonts and per-node styles other than colour are not imported.

#Visio (.vsdx)

A .vsdx file is a zip of XML parts; Yantra reads it with its own small unzip and inflater (no dependencies). The older binary .vsd format is not supported: save as .vsdx, or export to draw.io and import the .drawio file.

Positions only hint the direction (LR when connectors mostly run sideways). Themes, layers, comments and data graphics are not read; colours only as in the table above.

#PlantUML

The importer reads the first @startuml ... @enduml block (--all for every one) and picks the kind from the content: (*) → old-style activity; entity X { blocks or crow's-foot links (||--o{) → entity-relationship; object / map → object; class keywords (class, abstract, enum, interface X {) → class; [*] or state → state; activity syntax (start, :action;, if (...) then, swimlanes) → activity; component / use-case syntax ([A], (Use case), component, package {, left to right direction) without sequence-only keywords → component; anything else → sequence, as in PlantUML itself. Comments (', /' ... '/) are dropped; title becomes meta.title; creole (**bold**, //italic//), \n, <b>-style tags and <<stereotypes>> are cleaned.

#Sequence diagrams (meta.view: "sequence")

#Component, deployment and use-case diagrams

#State diagrams

Rewritten to Mermaid stateDiagram-v2 and converted by the Mermaid state importer (see mermaid.md): [*] start and end become initial / final shapes, state X <<choice>> a choice, <<fork>> / <<join>> a fork / join bar (shape: "fork"), other states shape: "state"; state "Long name" as X, state X : text (subtitle), composite state X { ... } (groups), -- / || concurrent regions (child groups with "kind": "region"), and self-transitions (self-loops). A -> B, A -down-> B, A -[#red]-> B and B <-- A all become A --> B; colours, skinparam, hide and scale are dropped with a warning.

#Class diagrams

Rewritten to Mermaid classDiagram and converted by the Mermaid class importer: class cards with data.fields and data.methods (visibility, types, parameters), interface, abstract and enum as stereotypes (<<interface>> etc.), package X { } as groups, relations <|-- (inheritance), <|.. (realization), *-- (composition), o-- (aggregation), --> (association), ..> (dependency). Direction hints (-up-|>) and {static} / {abstract} modifiers are dropped; notes are ignored with a warning. Multiplicities ("1" *-- "many") become end labels (sourceLabel / targetLabel); lollipops (A ()-- B) are realizations of the interface A; self-relationships are loops.

#Object diagrams

#Entity-relationship diagrams

Rewritten to a Mermaid erDiagram and converted by the Mermaid ER importer.

#Gantt charts (@startgantt)

A Gantt chart becomes an answer page with a gantt block (see pages.md); the headline gives the span of the plan and the last task.

#Activity diagrams (old syntax)

#Preprocessor

A safe subset runs before parsing (src/core/plantuml.js, preprocessPlantUml):

#Mind maps and work breakdowns

@startmindmap and @startwbs outlines (*, **, ...; + / - sides; _ boxless items; :multi-line; items keep their first line) are converted through the Mermaid mind-map importer: a mind map uses meta.layout.algorithm: "mindmap", a WBS "tree" (top to bottom). Colours and styles are dropped.

#Activity diagrams (new syntax)

Activity arrows are rarely labelled, so unlabelled transitions are named then (sequential), otherwise (from a decision) or done (into End), with one import warning; replace them with -> label; in PlantUML or in the JSON for a better walkthrough.

#Walkthrough

Flow imports get the same walkthrough as Mermaid flowcharts: an overview, then one step per node in topological order (bucketed by rank above seven nodes), each lighting the node, its incoming edges and their sources; decisions list their branches. Sequence imports get an overview plus one step per message.

#Limitations

• draw.io: waypoints (by design), fonts and rotated labels are not imported; images become icons only when their name matches a built-in one. A page with many shapes imports but may exceed the 14-node / 20-edge budget (split it, see docs/authoring.md). Layers are flattened.
• Visio: .vsdx only (not .vsd, .vsdm macros are ignored); ZIP64 archives are not read; connectors must be glued to shapes at both ends.
• PlantUML: JSON / YAML / salt / timing / network and other @start... kinds are rejected with an error. Preprocessor conditions, functions and macros with arguments are not evaluated.
• Identifiers containing - must be quoted or aliased in PlantUML (as in PlantUML itself).
• Imports are a starting point: tighten labels, add descriptions and a better walkthrough before sharing.