Learn / Mermaid & the text format

Mermaid & the text format

Diagrams-as-text is how diagrams live in git. Grafloria reads and writes Mermaid-compatible text — and adds the one thing Mermaid cannot express: your hand-arranged positions, in a sidecar that keeps the text valid Mermaid.

Import

import { importDiagramText } from '@grafloria/engine';

const result = importDiagramText(`flowchart LR
  a[Start] --> b{Gate}
  b -->|yes| c[Ship]
  b -->|no| a`);

result.diagram;             // a live DiagramModel — 3 nodes, 3 links
result.diagram.getNodes()[0].getData('label');   // 'Start'
result.diagram.getNodes()[0].type;               // 'flowchart:process' — typed, not generic

Imported nodes carry semantic types (flowchart:process, flowchart:decision, ER entities, class boxes…), so they render with the right glyphs and get type-aware layout — a state machine lays out differently from an entity-relationship diagram.

Supported types — and the honest line

flowchart/graph, erDiagram, classDiagram, stateDiagram/stateDiagram-v2. These four are verified against real Mermaid by a CI oracle — the same text rendered by Mermaid itself and by Grafloria, compared structurally. Everything else is refused loudly rather than rendered wrongly:

const r = importDiagramText('sequenceDiagram\n  A->>B: hi');
r.unsupported;   // 'sequenceDiagram' — check this field; there is no silent wrong guess

The full Mermaid compatibility story →

Export — and the sidecar trick

import { exportDiagramText } from '@grafloria/engine';

const text = exportDiagramText(diagram);

The output is valid Mermaid that any Mermaid renderer accepts. Positions, sizes and styling — things Mermaid has no syntax for — ride in a %%grafloria:document comment block at the end. Mermaid ignores comments; Grafloria reads them back. So the round trip is lossless for Grafloria and legible for everyone else: hand-arrange a diagram, export, commit, re-import — your arrangement survives, and GitHub still previews the file.

Text and canvas, live

The framework surfaces wire both directions into the live canvas — instance.exportText() / instance.loadText(text) (React/Vue) and exportText() / loadText() on the Angular canvas. loadText reconciles into the existing diagram rather than replacing it — listeners, plugins and selection survive. That's the pattern behind the Monaco side-by-side demos: edit text, watch the canvas; drag the canvas, watch the text.

Live: the Mermaid round-trip demos →

Where next

• Grafloria vs Mermaid — when text-only is enough and when it isn't.
• Layout — what happens when imported text has no positions.