Mermaid Support

atelier/diagram parses Mermaid-like grammars including stateDiagram-v2, gitGraph, sequenceDiagram, flowchart, classDiagram, erDiagram, timeline, journey, mindmap, requirementDiagram, kanban, block, architecture, C4Context, C4Container, and C4Component. The supported subsets are deliberately small, exactly specified, and symmetric: everything the parser accepts, the markdown renderer emits, and round-trip tests hold both sides to it. Venn diagrams currently have no text form in this package. Each subset below builds the model its own diagram type page documents.

Parsing

use Atelier\Diagram\Diagram;

$diagram = Diagram::fromMermaid($source);   // grammar auto-detected
$svg = $diagram->toSvg();

Diagram::fromMermaid() (backed by Parser\MermaidParser) dispatches on the first significant line through Parser\MermaidGrammarRegistry: stateDiagram-v2 or stateDiagram selects the state parser, gitGraph the git parser, sequenceDiagram the sequence parser, flowchart the flowchart parser, classDiagram the class parser, erDiagram the ER parser, timeline the timeline parser, journey the journey parser, mindmap the mindmap parser, requirementDiagram the requirement parser, kanban the kanban parser, block the block parser, architecture the architecture parser, and C4Context, C4Container, or C4Component the C4 parser. Anything else throws a ParseException at line 1. All grammars skip blank lines and %% comment lines. Most grammars ignore indentation; mindmap and kanban use strict indentation because indentation is part of their structure.

State, git graph, sequence, flowchart, and class are the mature textual grammars. They carry the highest expectations for parser clarity, canonical Mermaid output, layout polish, and documentation. The other textual grammars are supported but earlier: they fail loudly on unsupported syntax and keep intentionally smaller subsets while the shared layout layer matures.

State diagram subset

Header: stateDiagram-v2 (or stateDiagram). Then, in any order:

State ids match [A-Za-z_][A-Za-z0-9_]*. Everything else is rejected, never skipped: composite state { } blocks, forks, joins, notes, concurrency, and --> annotations beyond a plain label.

Git graph subset

Header: gitGraph, optionally suffixed LR: or TB: (LR is the default). Then:

Branch names are whitespace-free tokens. Everything else is rejected: cherry-pick, commit type:, order:, and options blocks.

Sequence diagram subset

Header: sequenceDiagram. Then:

Participant ids match [A-Za-z_][A-Za-z0-9_]*. Everything else is rejected: actors, notes, nested blocks, autonumber, and destruction markers.

Flowchart subset

Header: flowchart TD, flowchart TB, or flowchart LR. Then:

Node ids match [A-Za-z_][A-Za-z0-9_]*. Everything else is rejected: alternate shapes, edge variants, classes, and markdown labels.

Class diagram subset

Header: classDiagram. Then:

Class ids match [A-Za-z_][A-Za-z0-9_]*. Everything else is rejected for now: inheritance arrows, visibility parsing, methods as structured members, annotations, namespaces, and class blocks.

ER diagram subset

Header: erDiagram. Then:

Cardinality tokens are \|o (zero or one), \|\| (exactly one), o{ (zero or more), and \|{ (one or more); the pair is written <left>--<right>. Entity ids match [A-Za-z_][A-Za-z0-9_]*. Everything else is rejected for now: identifying/non-identifying styling, attribute keys and comments, quoted labels, and alias blocks.

Timeline subset

Header: timeline. Then:

Events must belong to an explicit section. Date values are labels in v0: they are not parsed, sorted, scaled, or treated as durations. Everything else is rejected for now: calendar scaling, range bars, nested phases, styling, and date arithmetic.

Journey diagram subset

Header: journey. Then:

Scores must be integers from 1 to 5. Tasks must belong to a section and must declare at least one actor. The layout renders score as a badge/intensity, not as a chart axis.

Mindmap subset

Header: mindmap. Then:

The v0 parser requires spaces only, exactly two spaces per level, one root, and no skipped indentation levels. Unsupported Mermaid mindmap features are rejected for now: icons, classes, markdown labels, arbitrary shapes, and multiple roots.

Requirement diagram subset

Header: requirementDiagram. Then:

Relationship kinds are validated: contains, copies, derives, satisfies, verifies, refines, and traces. Full SysML requirement semantics, nested packages, quoted rich fields, and generated IDs are intentionally out of scope for v0.

Kanban subset

Header: kanban. Then:

Columns and cards render in source order. Column/card ids match [A-Za-z_][A-Za-z0-9_-]*; labels are bracket text and cannot contain ] in v0. Unsupported board features are rejected for now: WIP limits, tags, assignees, priorities, swimlanes, and nested card metadata.

Block diagram subset

Header: block. Then:

Blocks and relationships render in source order. Block and group ids match [A-Za-z_][A-Za-z0-9_]*; labels are bracket text and cannot contain ] in v0. Unsupported features are rejected for now: nested groups, ports, alternate shapes, style directives, manual coordinates, and automatic graph solving.

Architecture subset

Header: architecture. Then:

Supported node kinds are person, system, container, component, database, queue, and external. Group and node ids match [A-Za-z_][A-Za-z0-9_]*. Labels are bracket text and cannot contain ] in v0. Full C4 semantics, icons, deployment nodes, nested arbitrary containers, and indentation-derived hierarchy are intentionally out of scope for v0.

C4 subset

Headers: C4Context, C4Container, or C4Component. Then:

Element and boundary ids match [A-Za-z_][A-Za-z0-9_]*. Text fields are quoted, cannot contain quotes or newlines, and are emitted canonically by toMermaid(). Unsupported C4 features are rejected for now: nested boundaries, deployment nodes, dynamic views, sprites, tags, links, styling macros, layout directives, and macros outside the subset above.

Debugging

Every violation throws Exception\ParseException, never a silent skip. The exception message names the problem and carries the position:

use Atelier\Diagram\Exception\ParseException;

try {
    Diagram::fromMermaid($source);
} catch (ParseException $e) {
    $e->getMessage();     // 'Unsupported gitGraph statement at line 4: "cherry-pick"'
    $e->getLineNumber();  // 4 (1-based, counted in the raw input)
    $e->getSourceLine();  // 'cherry-pick'
    $e->getDiagnostic()->code;             // 'parser.unsupported_syntax'
    $e->getDiagnostic()->span->startLine;  // 4
}

Two error classes share this shape:

• Syntax errors: a line the grammar does not accept.
• Semantic errors: a line the builder rejects (merge of an unknown branch, duplicate commit id, transition out of [*] final). The builder's InvalidDiagramException is wrapped in a ParseException carrying the offending line, with the original as previous. End-of-source validation reports the most specific known line when the parser tracks one, such as an empty timeline/journey section; otherwise it falls back to the header line.

ParseException::getDiagnostic() is the structured form for tooling. It contains the human message without location suffix, a stable optional code, a 1-based, end-exclusive source span, and a short source excerpt when the parser knows the offending line. Parser\Support\ParserDiagnosticCode is the source of truth for known parser codes; it includes header errors, unsupported syntax, semantic builder failures, empty labels/blocks/branches, indentation errors, branch context errors, and unclosed block spans. The text message remains the compatibility surface; diagnostics are the path for future CLI/editor output.

For human-facing tools, Parser\Support\ParserDiagnosticFormatter renders the same diagnostic as a compact code frame:

use Atelier\Diagram\Parser\MermaidParser;
use Atelier\Diagram\Parser\Support\ParserDiagnosticFormatter;

echo ParserDiagnosticFormatter::format($exception->getDiagnostic());

$result = (new MermaidParser())->tryParse($source);
if (null !== $result->getDiagnostic()) {
    echo ParserDiagnosticFormatter::format($result->getDiagnostic());
}

Diagram::tryFromMermaid() offers the same non-throwing shape at the facade level. On success, ParseResult::getModel() is a wrapped Diagram; on failure, it is null and getDiagnostic() / getException() expose the parse failure.

The parser bounds untrusted input before any line-level work: by default the source is capped at 1,000,000 bytes (DEFAULT_MAX_SOURCE_BYTES) and any single raw line at 16,384 bytes (DEFAULT_MAX_LINE_BYTES). These limits are the first-line defense against oversized or pathological input and are configurable through ParserInputLimits:

use Atelier\Diagram\Parser\MermaidParser;
use Atelier\Diagram\Parser\Support\ParserInputLimits;

$diagram = Diagram::fromMermaid($source, new ParserInputLimits(
    maxSourceBytes: 250_000,
    maxLineBytes: 8_192,
));

$parser = new MermaidParser(limits: new ParserInputLimits(
    maxSourceBytes: 250_000,
    maxLineBytes: 8_192,
));

$diagram = $parser->parse($source);

// Per-call limits override constructor limits.
$diagram = $parser->parse($source, new ParserInputLimits(maxSourceBytes: 1_000_000));

Oversized payloads fail with parser.source_too_large; oversized raw lines fail with parser.line_too_long.

Round-trip guarantees

The parser and the markdown renderer are inverses over the subset:

• parse(renderMermaid($model)) yields a model that renders byte-identical SVG to $model, except for state titles and the git legend flag, which the supported grammar cannot express and the renderer drops. Sequence and flowchart titles are serialized.
• renderMermaid(parse($text)) is canonical: parsing the result and rendering again returns the same string. Equivalent spellings normalize (A : d → state "d" as A, switch → checkout, attribute order id then tag); the user's original formatting is not preserved.
• Auto-generated commit ids are deterministic and omitted on rendering, so they survive any number of round-trips.
• Auto-declared participants, flow nodes, and classes are serialized explicitly, so the canonical form is stable.
• Sequence loop / alt / opt / par blocks, activations, and nested flowchart subgraphs are serialized canonically.