Mermaid Compatibility
Mermaid is an import/export format, not a lossless representation of every canvas feature. Keep the original source when importing, and review the result before replacing an existing diagram.
Import Into The Editor
Importing sets the diagram type to the source's family (flowchart, class, sequence, state, er, or the C4 level), and keeps its direction, title, and styling directives (classDef, style, click, %%{init}%%, front-matter, C4 Update*, autonumber) so an export can write them back.
| Mermaid family | Current behavior |
|---|---|
flowchart / graph | Every classic shape and Mermaid 11 @{ shape: … } shapes, all link styles (dotted, thick, invisible, o/x ends, longer links), labels (including markdown strings), edge ids (e1@-->) with their e1@{ animate: true } properties, per-link linkStyle (kept with its link when links are added or removed), &, ;, nested subgraphs. |
classDiagram | Classes, interfaces, abstract classes, enums (including <<interface>> inside a class body), members (also Name : member), generics, namespaces, notes, and relations written in either direction, two-ended arrows (<|--|>, *--*) and lollipop interfaces (bar ()-- foo). |
sequenceDiagram | Participants/actors, every message arrow (->>, -->>, ->, -x, -), <<->>), activations, notes with their placement, control blocks including alt/else, loop, opt, par/and, critical/option, break, and rect, participant boxes, create/destroy, and participant types (A@{ "type": "database" }). See the limits below. |
stateDiagram-v2 | States, [*] start/end, <<choice>>/<<fork>>/<<join>>, composite states with concurrent regions (--), descriptions, and notes. |
erDiagram | Entities (also with an alias, p[Person]) with their attribute lines, crow's-foot cardinalities, identifying (--) and non-identifying (..) relationships. |
| C4 | Elements with their exact macro and $sprite/$tags/$link/$descr arguments, boundaries and deployment nodes (including Node, Node_L, Node_R), Rel/BiRel/Rel_*/RelIndex with technology, and title. |
| Mindmap | Tree by indentation, node shapes (id[square], ((circle)), ))bang((, )cloud(, {{hexagon}}), ::icon(…) and :::class lines. |
| Requirement | Requirements and elements with their fields, every relation (contains, copies, derives, satisfies, verifies, refines, traces) in either direction, quoted names. |
| Architecture | Groups (nested), services with icons, junctions, links with their ports (db:L -- R:server), arrows and {group} ends. |
| gitGraph | Commits (id, msg, tag, type), branches with order, merges, cherry-picks, LR/TB headers and mainBranchName. |
| Pie, journey, gantt, timeline | Each slice, task, section or period is a canvas item whose text (value, score and actors, dates, events) is editable; sections are frames; title, showData, dateFormat, axisFormat, excludes and the like are kept. |
| Quadrant chart, sankey, packet | Points with their [x, y], flows with their value, fields with their bit range; axes, quadrant names and titles are kept. |
These families have no diagram type of their own — the diagram is freeform and remembers which family it is, so editing it on the canvas still exports it as that family (it used to come out as a flowchart).
When a source can't be imported, the error names the unsupported text and its line. block and zenuml diagrams are not imported to the canvas yet.
Old diagrams
Diagrams made before the families existed are uml or freeform. An agent can ask the reclassify_diagrams MCP tool for a report (the default — nothing is written) of which of them are really a flowchart, class, sequence, state or ER diagram, and apply it with dryRun: false. A diagram moves only when everything on its canvas belongs to that one family; mixed drafts, UML-only diagrams and C4 (five levels) stay, with the reason.
Sequence Diagrams
Block row boundaries, branch captions, and nested-block depth are retained through the current import/export path. Self calls have loops, responses retain dashed lines, and explicit <br/> labels render on separate lines. Editor and interactive document views share block rendering.
Captions on newly created connectors start without a background. They sit above ordinary messages or beside self calls. Space is reserved for block captions and multiline messages.
Participant boxes, participant types and participants created mid-diagram are kept as notation: the canvas shows the participants, and the export writes the box, the @{ "type": … } and the create back. A rect is a block on the canvas. A destroy with no message after it produces a partial-import warning.
Previously imported diagrams may already have lost branch information. Reapply the original Mermaid source to recover it; a renderer update cannot recreate discarded information.
Export
The exporter writes the family of the diagram's type: flowchart, class, sequence, state, ER, or the C4 level (older uml/freeform diagrams have their family inferred from their nodes). It keeps the imported shapes, link styles, arrow directions, boundaries, direction, title, and directives, and every export is checked against the official Mermaid parser in the project's round-trip tests.
Elements the family can't express are skipped and listed in %% comments after the header. Manual routes, label offsets, line jumps, colors set on the canvas, cloud-provider metadata, and infrastructure shapes are not part of Mermaid text. Mermaid computes its own layout, so an export renders the same structure, not the same pixel positions.
Use the saved Ideagram diagram for continued visual editing. Use Mermaid for portable structure and text-based collaboration.
PlantUML
Mermaid is the notation you edit live; PlantUML is import and export, through the same model — a PlantUML diagram and the equivalent Mermaid diagram give the same canvas.
| PlantUML | Import | Export |
|---|---|---|
| Sequence | Participants (participant, actor, boundary, control, entity, database, collections, queue), every arrow (->, -->, ->>, ->x, -\, <->, either direction), ++/--/**/!! shorthands, activate/deactivate/create/destroy, alt/else/opt/loop/par/critical/break, box, notes, return, autonumber, title | Everything the canvas holds except rect blocks (PlantUML has none) |
| Class | class/abstract class/interface/enum/annotation, generics, stereotypes, extends/implements, members with {static}/{abstract}, every relation arrow with cardinalities and labels, package, notes, left to right direction | Declarations, members, relations, packages, notes |
| C4-PlantUML | Context, container, component, dynamic and deployment levels (!include <C4/…>), elements, boundaries, relations (Rel_Neighbor, BiRel_*, RelIndex), $tags/$sprite/$link | The same, with the library include of the diagram's level |
| State | States, state "Label" as id, [*], transitions with direction words (-right->) and colours, composite states, <<choice>>/<<fork>>/<<join>>, -- regions, notes | The same, with left to right direction |
| Entity (ER) | entity with attributes (* id : int <<PK>>, keys above --), crow's-foot relations, aliases | The same; attribute comments have no PlantUML form and are dropped |
| Flowchart | — | One way: a description diagram (rectangle, hexagon for decisions, database, …, package for subgraphs) — PlantUML has no flowchart notation |
Use diagrams' Code → PlantUML tab to copy or download the export (.puml). Other PlantUML diagrams (use case, activity, component, deployment, object) can't be imported yet — Ideagram has no canvas family for them; the import says which family it could not read, and statements with no canvas shape (dividers, ref, group) are reported with their line.
Every export in the project's PlantUML round-trip tests is checked against the official PlantUML parser when it is available (PLANTUML_JAR=/path/plantuml.jar).