Mermaid Designer

Decision Rules

• Showing a process? → flowchart
• Showing interactions between systems/actors? → sequenceDiagram
• Showing data models? → erDiagram
• Showing states and transitions? → stateDiagram-v2
• Showing architecture at multiple levels? → Start with C4Context, drill into C4Container
• Showing a timeline or roadmap? → timeline or gantt
• Comparing options on two axes? → quadrantChart
• Showing hierarchy or taxonomy? → mindmap
• Showing infrastructure/cloud? → architecture

Syntax Rules

General

• Use frontmatter (---) for configuration, not init directives (deprecated since v10.5)
• Use %% for comments — never use {} inside comments
• Node IDs: alphanumeric, underscores, dashes only — no spaces or special characters
• Separate node ID from display label: nodeId["Display Label with Spaces"]
• Wrap text with <br/> for multi-line labels
• Keep labels short — move details to surrounding text
• Use consistent indentation (2 spaces)

Reserved Words

The word end is reserved. Never use it as a bare node ID:

%% BAD: end --> process
%% GOOD: end_node["end"] --> process

Special Characters

• Avoid #, ., () in node IDs — use underscores instead
• Use quotes for labels with special characters: id["Label with #special chars"]
• For literal # in labels use entity codes: #35;

Diagram-Type-Specific Gotchas

Gantt:

• Task names must NOT contain :, &, +, or () — these break the parser
• Use and instead of &, spell out instead of using special chars
• Section names must NOT contain : — use plain text only
• Parenthetical notation like (9h) in task names causes parse failures — use 9h directly

Pie:

• Entries with value 0 produce invisible/empty slices — omit zero-value entries entirely
• Keep label text short — long labels overflow the chart

Mindmap:

• <br/> HTML tags are NOT reliably supported in mindmap node text — use short single-line labels
• The root node uses root((Label)) syntax — keep it concise

Sequence Diagram:

• <br/> in participant aliases works but can cause layout issues with long text
• Keep participant names short; use the as alias for display names

Flowchart Direction

• TB (top-bottom): hierarchies, org charts, dependency trees
• LR (left-right): processes, pipelines, data flows
• BT (bottom-up): build-up processes, layer stacks
• RL (right-left): rarely needed — reverse flows

Edge Types

A --> B          %% Solid arrow
A --- B          %% Open link (no arrow)
A -.-> B         %% Dotted arrow (optional, secondary)
A ==> B          %% Thick arrow (emphasis, primary)
A -->|label| B   %% Arrow with label

Subgraphs

Use subgraphs to group related nodes:

subgraph GroupName["Display Title"]
  A --> B
end

• Subgraphs inherit parent direction when they have external links
• Use invisible links (~~~) to encourage positioning without visual lines

Node Shapes Reference

[Rectangle]           %% Default, most common
(Rounded)             %% Softer visual, secondary
([Stadium])           %% Start/end points
[[Subroutine]]        %% External processes
[(Database)]          %% Data stores
((Circle))            %% Connectors, events
{Diamond}             %% Decisions
{{Hexagon}}           %% Preparation steps
[/Parallelogram/]     %% Input/output

Styling

Theme Selection

Custom Colors (requires theme: base)

---