Mermaid.js

Generate Mermaid.js diagrams from text descriptions and validate existing Mermaid syntax.

When to Use

• Creating any of the 18 Mermaid diagram types from structured descriptions
• Converting plain-language descriptions into visual diagrams
• Validating existing Mermaid syntax for common errors
• Choosing the right diagram type for a given scenario
• Styling or theming Mermaid diagrams

Diagram Types at a Glance

Universal Syntax

Every diagram begins with a diagram type keyword. Optional frontmatter and directives can configure the diagram before content.

Frontmatter

YAML between --- lines at the very start. Used for layout, look, and theme configuration.

---
config:
  layout: elk
  look: handDrawn
  theme: forest
---
flowchart LR
    A --> B

Directives

Inline configuration via %%{ }%%. Can appear above or below the diagram definition.

%%{init: {'theme': 'dark'}}%%
flowchart LR
    A --> B

Comments

%% starts a comment — everything after it on that line is ignored.

Diagram-Breaking Words

The word end inside flowchart and sequence diagrams breaks parsing. Wrap node text containing end in quotes: A["weekend"].

Layouts

• dagre (default) — standard layout engine
• elk — Eclipse Layout Kernel, better for complex diagrams (requires frontmatter config)

Looks

• classic (default)
• handDrawn — sketch-style rendering

Quick Syntax by Diagram Type

Flowchart

flowchart TD
    A[Start] --> B{Decision}
    B -->|Yes| C[Action]
    B -->|No| D[End]

Directions: TD/TB (top-down), BT, LR, RL. Node shapes: A[rect], A(rounded), A((circle)), A{diamond}, A>flag], A[/parallelogram/], A[\trapezoid\]. Links: -->, ---, -.->, ==>, -- text -->. Subgraphs: subgraph Name ... end. Styling: classDef name fill:#f9f,stroke:#333 then class nodeId name. Icons: A@{ icon: fa:database }. New shapes (v11.3.0+): A@{ shape: rect }.

See references/flowchart.md for all 30+ shapes, link types, subgraph options, and styling.

Sequence Diagram

sequenceDiagram
    Alice->>Bob: Hello
    Bob-->>Alice: Hi
    Alice->>Bob: How are you?
    Bob-->>Alice: Great!

Participants: participant Name or actor Name. Arrows: ->, -->, ->>, -->>, -x, --x, -), --). Half-arrows (v11.12.3+): ->>, -->> with half-arrow variants. Loops: loop Description ... end. Conditionals: alt Condition ... else ... end, opt Condition ... end. Parallel: par ... and ... end. Critical: critical ... option ... end. Break: break ... end. Notes: note left/right/over of Participant: text. Activation: activate/deactivate or +/- shorthand. autonumber adds sequence numbers.

See references/sequence.md for all arrow types, message grouping, notes, activations, and styling.

Gantt Chart

gantt
    title Project Schedule
    dateFormat YYYY-MM-DD
    section Design
    Task 1 :a1, 2024-01-01, 30d
    Task 2 :after a1, 20d
    section Development
    Task 3 :2024-02-15, 45d
    Milestone :milestone, 2024-04-01, 0d

dateFormat: YYYY-MM-DD (default). Duration units: ms, s, m, h, d, w, M, y. Excludes: excludes weekends. Today marker: todayMarker off or todayMarker stroke:#f00,stroke-width:2px. Compact mode: compact keyword. axisFormat for date display formatting.

See references/gantt.md for metadata syntax, section handling, dependencies, and styling.

Class Diagram

classDiagram
    class Animal {
        +String name
        -int age
        #makeSound() void
    }
    class Dog {
        +bark() void
    }
    Dog --|> Animal
    Dog --> Toy

Visibility: + public, - private, # protected, ~ package. Modifiers: abstract, $ static. Relationships: --|> inheritance, -- composition, o-- aggregation, --> association, ..> dependency, ..|> realization. Cardinality: Animal "1" --> "0..*" Dog. Generics: class List~T~. Namespaces: namespace Name { ... }. Notes: note for Class "text".

See references/class.md for all relationship types, annotations, generics, and styling.

State Diagram

stateDiagram-v2
    [*] --> Still
    Still --> Moving
    Moving --> Crash
    Crash --> [*]

States: stateId or state "Description" as id. Transitions: A --> B or A --> B : label. Start/end: [*]. Composite states: state Parent { ... }. Choice: state choiceState <<choice>>. Fork: state forkState <<fork>>. Notes: note left/right of StateId : text. Concurrency: -- separator inside composite states. Direction: direction LR.

See references/state.md for composite states, choice, fork, concurrency, and styling.

ER Diagram

erDiagram
    CUSTOMER ||--o{ ORDER : places
    ORDER ||--|{ LINE-ITEM : contains
    CUSTOMER {
        string name
        string email PK
    }
    ORDER {
        int order_id PK
        date order_date
    }

Cardinality (left/right): |o/o| zero-or-one, ||/|| exactly-one, }o/o{ zero-or-more, }|/|{ one-or-more. Identification: -- identifying (solid), .. non-identifying (dashed). Attributes: type name inside {}. Keys: PK, FK, UK. Comments: "comment" at end of attribute. Aliases: one or more, zero or one, etc. Direction: direction LR/RL/TB/BT.

See references/er.md for cardinality, identification, attributes, keys, subgraphs, and styling.

Git Graph

gitGraph
    commit
    commit
    branch develop
    checkout develop
    commit
    checkout main
    merge develop

Commands: commit, branch name, checkout name (or switch), merge name, cherry-pick id: "id". Commit attributes: id: "custom_id", type: NORMAL|REVERSE|HIGHLIGHT, tag: "v1.0". Merge attributes: same as commit. Orientation: gitGraph LR: / TB: / BT:. Config: showBranches, showCommitLabel, mainBranchName, parallelCommits.

See references/gitgraph.md for commit types, cherry-pick, branch ordering, orientation, and theming.

User Journey

journey
    title User shops online
    section Browse
        Visit homepage: 5: User
        Search product: 4: User
    section Purchase
        Add to cart: 5: User
        Checkout: 3: User, System

Tasks: Task name: score: actor. Score is 1–5 (higher = better sentiment). Sections group related tasks.

See references/journey.md for full syntax.

Quadrant Chart

quadrantChart
    title Impact vs Effort
    x-axis Low Effort --> High Effort
    y-axis Low Impact --> High Impact
    quadrant-1 Do First
    quadrant-2 Schedule
    quadrant-3 Delegate
    quadrant-4 Drop
    Task A: [0.3, 0.8]
    Task B: [0.7, 0.2]

Points: Name: [x, y] where x and y are 0–1. Axes: x-axis left --> right, y-axis bottom --> top. Quadrants: quadrant-1 through quadrant-4. Point styling: Name: [x, y] radius: 12, color: #ff0000. Classes: classDef name color: #109060 then Point:::className: [x, y].

See references/quadrant.md for axis config, point styling, classes, and theme variables.

XY Chart

xychart-beta
    title "Sales Q1"
    x-axis ["Jan", "Feb", "Mar"]
    y-axis "Revenue" 0 --> 10000
    bar [5000, 7000, 9000]
    line [3000, 6000, 8500]

Orientation: xychart-beta horizontal or vertical (default). x-axis: categorical [cat1, cat2] or numeric min --> max. y-axis: numeric range. Plots: line [values] or bar [values]. Named plots: line "Series" [values] (adds to legend). Per-point labels (v11.16.0+): line [2.3 "label1", 45 "label2"].

See references/xychart.md for config options, axis config, theme variables, and data labels.

Pie Chart

pie showData
    title Market Share
    "Product A" : 40
    "Product B" : 35
    "Product C" : 25

showData renders values after legend. Donut mode (v11.16.0+): set donutHole config (0 to 0.9). Legend position: legendPosition config (top/bottom/left/right/center). Highlight slice: highlightSlice config.

See references/pie.md for config options.

Architecture Diagram

architecture-beta
    group api(cloud)[API Layer]
    service db(database)[Database] in api
    service server(server)[Server] in api
    db:R --> L:server

Groups: group id(icon)[title] in parent. Services: service id(icon)[title] in parent. Edges: serviceId:side -- side:serviceId where side is T|B|L|R. Arrows: --> for directional. Edges from groups: serviceId{group}:B --> T:otherService{group}. Junctions: junction id. Align: align row idA idB or align column idA idB. Icons: cloud, database, disk, internet, server or custom via iconify.design.

See references/architecture.md for edges, groups, junctions, alignment, layout tuning, and icons.

Block Diagram

block-beta
    columns 3
    A B C
    D["Wide"] E F
    A --> D
    B --> E

Columns: columns N. Blocks: id or id["label"]. Shapes: block:rounded, block:circle, block:hexagon, etc. Width: block:width N. Composite: block Parent { block Child }. Edges: -->, ---. Space: space or space:N. Styling: classDef name fill:#f9f then class nodeId name.

See references/block.md for shapes, edges, composite blocks, styling, and layout.

Requirement Diagram

requirementDiagram
    requirement Test Req {
        id: 1
        text: The system shall test
        risk: High
        verifymethod: Test
    }
    element Entity {
        type: Software
        docref: spec.md
    }
    Test Req - satisfies -> Entity

Types: requirement, functionalRequirement, interfaceRequirement, performanceRequirement, physicalRequirement, designConstraint. Risk: Low/Medium/High. VerifyMethod: Analysis/Inspection/Test/Demonstration. Relationships: contains, copies, derives, satisfies, verifies, refines, traces. Direction: direction LR/RL/TB/BT.

See references/requirement.md for types, relationships, styling, and direction.

Treemap

treemap-beta
    "Section 1"
        "Leaf 1.1": 12
        "Leaf 1.2": 8
    "Section 2"
        "Leaf 2.1": 20
        "Leaf 2.2": 25

Nodes: quoted text for sections, "name": value for leaves. Hierarchy via indentation. Styling: classDef name fill:#f9f then "node":::className. Value formatting: valueFormat config (,, $, .1%, etc.).

See references/treemap.md for config options, value formatting, and styling.

Mindmap

mindmap
    Root
        A
            B
            C
        D

Hierarchy via indentation. Shapes: id[square], id(rounded), id((circle)), id)bang(, id)cloud(, id{{hexagon}}. Icons: id::icon(fa:database). Classes: id:::className. Markdown strings supported.

See references/mindmap.md for shapes, icons, classes, and layouts.

Timeline

timeline
    title History of Computing
    section Early Era
        1940s : ENIAC
        1950s : FORTRAN
    section Modern Era
        2000s : Cloud Computing
        2010s : AI Revolution

Time periods: period : event or period : event : event. Sections: section Name. Direction: timeline LR (default) or timeline TD. Multi-color: default on, disableMultiColor to disable.

See references/timeline.md for sections, direction, styling, and themes.

Sankey

sankey-beta
    Source,Target,Value
    Electricity,Heating,40
    Electricity,Lights,15
    Gas,Heating,30

CSV format: 3 columns (source, target, value). Commas in values: wrap in double quotes. Double quotes in values: use "". Config: linkColor (source/target/gradient/hex), nodeAlignment (justify/center/left/right), labelStyle (legacy/outlined), nodeWidth, nodePadding, nodeColors.

See references/sankey.md for CSV syntax, config, and node colors.

Common Gotchas

• end breaks diagrams. In flowcharts and sequence diagrams, end is a keyword. Wrap any node text containing "end" in quotes: A["weekend"].
• Frontmatter must be first. The --- lines must be the very first characters in the diagram. No blank lines before.
• Indentation matters in mindmaps and treemaps. The hierarchy is defined by indentation relative to the previous line, not absolute column position.
• Sequence diagram autonumber must come early. Place autonumber right after sequenceDiagram and before any participants.
• Gantt dateFormat is required. Without it, date parsing fails silently.
• ER cardinality order matters. ||--o{ means "exactly one to zero-or-more" — the left cardinality comes first.
• Sankey values must be numeric. The third CSV column must be a number, not a string.
• Pie values must be positive. Zero or negative values cause errors.
• Quadrant point coordinates are 0–1. Not pixel values, not percentages — a float between 0 and 1.
• Architecture diagram identifiers must be declared before use. You cannot reference a service in an edge before declaring it.

Validation

The bundled scripts/validate.py checks Mermaid syntax for common errors:

uv run scripts/validate.py --input diagram.mmd

Or pipe via stdin:

cat diagram.mmd | uv run scripts/validate.py --stdin

Checks include: valid diagram type keyword, balanced braces/brackets/parentheses, unquoted diagram-breaking words, frontmatter YAML validity, and common syntax pitfalls per diagram type.

Output is structured JSON to stdout, diagnostics to stderr. Exit code 0 = valid, 1 = invalid, 2 = usage error.

Detailed References

Load these when you need full syntax details, edge cases, or examples for a specific diagram type:

• references/flowchart.md — All node shapes (30+), link types, subgraphs, styling, icons, markdown strings
• references/sequence.md — Arrow types, loops, alt/par/critical/break, notes, activations, styling
• references/gantt.md — Date format, axis format, duration units, excludes, milestones, compact mode, today marker
• references/class.md — Visibility, generics, relationships, cardinality, namespaces, annotations, notes
• references/state.md — Composite states, choice, fork, concurrency, notes, direction, classDefs
• references/er.md — Cardinality, identification, attributes, keys, comments, aliases, subgraphs, direction
• references/gitgraph.md — Commit types, tags, cherry-pick, branch ordering, orientation, config, themes
• references/journey.md — Sections, tasks, scores, actors
• references/quadrant.md — Axes, quadrants, points, styling, classes, config, theme variables
• references/xychart.md — Orientation, axes, line/bar plots, legends, data labels, config, theme variables
• references/pie.md — showData, donut mode, legend position, highlight slice, config
• references/architecture.md — Groups, services, edges, junctions, alignment, layout tuning, icons
• references/block.md — Columns, shapes, composite blocks, edges, space blocks, styling
• references/requirement.md — Types, elements, relationships, direction, styling
• references/treemap.md — Node hierarchy, styling, value formatting, config options
• references/mindmap.md — Shapes, icons, classes, markdown strings, layouts
• references/timeline.md — Time periods, events, sections, direction, styling, themes
• references/sankey.md — CSV syntax, link colors, node alignment, label style, node colors

Available Scripts

• scripts/validate.py — Validates Mermaid diagram syntax. Run with uv run scripts/validate.py --input <file> or --stdin.