mermaid-author

Files (2)

• SKILL.md
• diagram-types.md · references/

SKILL.md (first lines)

# Mermaid Diagram Authoring

This skill covers correct mermaid.js syntax for all diagram types, with emphasis on the parser pitfalls that cause silent failures or broken renders.

## Rules for all diagram types

These are the most common causes of broken mermaid diagrams.

### 1. Never use literal `\n` in node text or labels

The mermaid parser does not interpret `\n` as a newline in most contexts. It either renders literally or breaks parsing.

**For line breaks, use one of these approaches:**
- `<br/>` tags inside quoted strings. They break lines in flowchart nodes, subgraph titles, and sequence diagram
  messages and notes (checked with mermaid-cli 11.12; older renderers may differ)
- Markdown strings with actual newlines (wrap text in backtick-quotes): `` "`Line 1\nLine 2`" `` where `\n` is an actual newline character

**What breaks:**
```
A["First\nSecond"]     %% BAD - \n renders literally or breaks
A["First<br/>Second"]  %% GOOD - works in flowcharts
```

### 2. The word `end` is reserved

Lowercase `end` in node text, labels, or anywhere the parser scans will be interpreted as a block terminator (closing subgraphs, loops, alt blocks, etc.).

**Workarounds:**
- Capitalize: `End`, `END`, `Backend`
- Wrap in quotes: `A["Send end signal"]`
- Use parentheses/brackets: `A("end")`

### 3. Special characters that break syntax

These characters have syntactic meaning and will break parsing if used raw in text:

| Character | Problem | Solution |
|-----------|---------|----------|
| `(` `)` | Node shape delimiters | Wrap text in double quotes: `A("text(with parens)")` |
| `[` `]` | Node shape delimiters | Use quotes: `A["text[with brackets]"]` |
| `{` `}` | Node shape delimiters | Use quotes: `A{"text"}` or HTML entities |
| `#` | Entity prefix | Use `#35;` (mermaid entity) or wrap in quotes |
| `<` `>` | Arrow/HTML confusion | Use `#lt;` and `#gt;` or quotes |
| `:` | Separator in many diagram types | Wrap the entire text in quotes |
| `"` inside text | Terminates quoted strings | Double them: `A["say ""hello"""]` |
| `@` | Shape modifier (v11.3.0+) | Wrap in quotes if used in text |
| `~` | Generic type delimiter in class diagrams | Wrap in quotes |

**Mermaid entity syntax** (NOT standard HTML entities):
- Use `#35;` not `&#35;` for the `#` character
- Use `#lt;` / `#gt;` for angle brackets
- Use `#quot;` for double quotes

### 4. Node IDs starting with `o` or `x`

If a node ID starts with lowercase `o` or `x` and follows an edge, the parser interprets it as a circle-end (`--o`) or cross-end (`--x`) marker.

```
A --> oNode    %% BAD - parsed as A --o Node (circle edge)
A --> ONode    %% GOOD - capitalize
A --> o_node   %% BAD
A --> O_node   %% GOOD
```

### 5. Comments use `%%`, not `//` or `#`

```
%% This is a comment
A --> B  %% inline comment
```

Never use `%%{ }%%` inside comments, as it triggers directive parsing.

### 6. Whitespace and indentation matter in some diagrams

- **Mindmaps**: Hierarchy is entirely indentation-based. Inconsistent indentation creates wrong parent-child relationships.
- **Block diagrams**: Column layout depends on proper nesting.
- **General**: Avoid tabs; use spaces consistently.

---

## Diagram Type Reference

For detailed syntax of each diagram type, see `references/diagram-types.md`. Below is the quick-start for the most common types.

### Flowchart

```mermaid
flowchart LR
    A[Rectangle] --> B(Rounded)
    B --> C{Decision}
    C -->|Yes| D[Result]
    C -->|No| E[Other]
```

**Directions**: `TB`/`TD` (top-down), `BT`, `LR`, `RL`

**Node shapes** (classic):
- `[text]` rectangle
- `(text)` rounded
- `([text])` stadium
- `((text))` circle
- `{text}` diamond
- `{{text}}` hexagon
- `[/text/]` parallelogram
- `[\text\]` parallelogram alt
- `[/text\]` trapezoid
- `[\text/]` trapezoid alt
- `[(text)]` cylinder
- `(((text)))` double circle
- `[[text]]` subroutine
- `>text]` asymmetric

**Edge types**:
- `-->` arrow
- `---` line (no arrow)
- `-.->` dotted arrow
- `==>` thick arrow
- `~~~` invisible link

From rcedwards/blaude-bode, MIT.

More from rcedwards/blaude-bode