Docs / Reference

Importing Mermaid

Turn Mermaid flowcharts, sequence, state, ER and class diagrams, mind maps, journeys and charts into Yantra diagrams and answer pages with yantra import.

Yantra can turn a Mermaid flowchart (graph / flowchart), sequence diagram (sequenceDiagram), state diagram (stateDiagram / stateDiagram-v2), ER diagram (erDiagram), class diagram (classDiagram), mind map (mindmap) or user journey (journey) into a diagram payload with roles, groups and a walkthrough, and a gantt, pie, timeline or quadrantChart into a one-page answer ("kind": "page", see Charts and plans). The parser is small and dependency-free (src/core/mermaid.js); it is not a full Mermaid implementation, so check the warnings it prints.

yantra import flow.mmd                      # -> flow.json, then lint report
yantra import notes.md -o diagram.json      # first ```mermaid block in a Markdown file
yantra import notes.md --all                # every block -> notes-1.json, notes-2.json, ...
yantra import flow.mmd --title "Checkout"   # override the title

The command prints import warnings, writes the JSON, runs the validator and exits 1 only if validation reports errors. From MCP, call yantra_import_mermaid with { mermaid, title?, outputPath? }; it returns { payload | outputPath, warnings, validation }. From JavaScript: fromMermaid(text, { title }) -> { payload, warnings }.

Samples: examples/mermaid/*.mmd. draw.io and PlantUML imports use the same command and are described in import.md; the MCP tool yantra_import handles all three.

#Flowcharts

Ids. Mermaid ids are kept when they are plain ([A-Za-z0-9_-]); other characters become - and collisions get -2, -3. Edge ids are source-target (-2 for repeats).

Roles. One role per type with a label (Step, Decision, Data store, Start / end, Input / output, Event, or the class name humanised). Class roles take colours first; shape roles keep their usual hue (blue, amber, violet, teal, green, orange) unless taken.

Walkthrough. An overview step, then one step per node in topological order (declaration order breaks ties and cycles). With more than seven nodes, nodes are bucketed by rank so the walkthrough stays at eight steps or fewer. Each step lights its nodes, their incoming edges and the sources of those edges; decisions list their branches.

Text budgets. Titles over 42 characters are shortened (full text in description), edge labels over 28 characters are shortened. Unlabelled edges are reported once; label them in Mermaid (-->|what flows|) to keep the validator quiet.

#Sequence diagrams

The scenario starts with an overview step and keeps every message as its own step.

#State diagrams

The walkthrough is built as for flowcharts (overview, then states in topological order); self-loops are mentioned on their state's step. Transitions out of a start or into an end need no label; the validator does not ask for one.

#ER diagrams

Entities with more than 12 attributes import whole but show 12 rows (warning). The walkthrough has an overview, then one step per relationship (per source entity when there are more than seven) describing both cardinalities.

#Class diagrams

The walkthrough reads the way UML is spoken: "Duck inherits from Animal", "Wheel is part of Car", "Order depends on PaymentMethod".

#Limitations

• Diagrams: flowcharts, sequence, state, ER, class, mind maps and journeys; pages: gantt, pie, timeline and quadrantChart. Other types (gitGraph, sankey-beta, xychart-beta, C4Context, block-beta, requirementDiagram, ...) are rejected with an error listing what is supported.
• Flowcharts: circle and cross heads (--o, --x, o--o) are drawn as plain arrows.
• State diagrams: notes are not drawn; composite states are groups, so a transition to the composite itself lands on its entry state (in every region).
• ER diagrams: key rows are matched by name only (<entity>_id); other relationships attach to card sides. Class relationships always attach to card sides.
• Mermaid styling (style, linkStyle, colours other than classDef fill) and interactions (click) are dropped.
• Per-subgraph direction is ignored (layout is automatic).
• Node ids with hyphens before -, ., o or x (e.g. a--ob) can be ambiguous; add spaces around links.
• Groups are emitted in the payload; how they are drawn depends on the viewer version.
• Larger graphs import but may exceed the 14-node / 20-edge budget; split them as described in docs/authoring.md.

#Charts and plans (answer pages)

These Mermaid types describe data rather than a structure, so they become a one-page answer ("kind": "page", see pages.md) whose headline is computed from the data (the span of the plan, the largest slice, the busiest quadrant). Rewrite it as the real answer before sharing; the page footer says so.

journey stays a diagram: one card per task with its score as the badge (4/5) and the actors as the subtitle, types good (4-5, green), neutral (3, amber) and pain (1-2, red), sections as groups, tasks linked in order (then, next stage) left to right, and a walkthrough with one step per section whose overview names the pain points.

Samples: launch-gantt.mmd, traffic-sources.mmd, product-timeline.mmd, feature-priorities.mmd, checkout-journey.mmd; also library-classes.mmd (one-line classes, multiplicities, a lollipop and a self-relationship), staff-schema.mmd (one-line entities, key rows, a self-relationship) and parallel-checkout.mmd (fork, join and regions).

#Mind maps

Walkthrough. An overview, then one step per first-level branch (its whole subtree and the edge from the root), at most seven. Big maps. Above 40 topics every branch opens folded (meta.layout.collapsed), with a warning; readers unfold branches with +N.

Sample: examples/mermaid/project-mindmap.mmd.