Mermaid Syntax Reference

Pitfalls and edge cases when generating Mermaid from code graph data.

Contents

• Node ID sanitization
• Label escaping
• Style definitions
• Edge confidence styling
• Common pitfalls

---

Node ID Sanitization

Trailmark node IDs use module:Class.method format. Mermaid node IDs only allow [a-zA-Z0-9_].

Rules applied by diagram.py:

• Replace any non-alphanumeric character (except _) with _
• Prefix with n_ if the result starts with a digit

Examples:

---

Label Escaping

Node labels are wrapped in double quotes to safely include special characters:

    node_id["label with (parens) and: colons"]

If the label itself contains double quotes, replace " with #quot; (Mermaid's HTML entity escape).

---

Style Definitions

Use classDef to define reusable styles and ::: to apply them:

flowchart TB
    A["Low complexity"]:::low
    B["High complexity"]:::high
    classDef low fill:rgba(40,167,69,0.2),stroke:#28a745,color:#28a745
    classDef high fill:rgba(220,53,69,0.2),stroke:#dc3545,color:#dc3545

The script defines three classes for complexity heatmaps:

• low (green): CC < 5
• medium (yellow): CC 5-10
• high (red): CC > 10

And one for data flow:

• entrypoint (blue): marks untrusted input sources

---

Edge Confidence Styling

Arrow syntax varies by edge confidence:

For class diagrams, arrows are different:

• <\\|-- = inherits
• <\\|.. = implements

---

Common Pitfalls

Reserved words as node IDs: end, graph, subgraph, style, classDef, click are reserved. The sanitization function avoids most conflicts since it replaces special characters, but single-word function names matching reserved words can still collide. Workaround: use the full qualified ID which includes the module prefix.

Leading digits: Mermaid node IDs cannot start with a digit. The script prefixes n_ in this case.

Diagram size: Mermaid renderers struggle with >100 nodes. The script warns when this limit is exceeded and suggests using --focus to scope the diagram.

Empty diagrams: When no edges of the required type exist (e.g., no inherits edges in a Go codebase), the script emits a single-node diagram with an explanatory message rather than failing.

Parentheses in labels: Mermaid interprets () as rounded-rectangle node shape. Always use quoted labels (["label"]) to avoid accidental shape changes.