mermaid-syntax

Files (1)

• SKILL.md

SKILL.md (first lines)

# Mermaid Syntax Reference

## Syntax Compatibility Rules

These 5 rules prevent parser errors across common rendering tools (GitHub, Obsidian, VS Code extensions):

1. **Subgraphs**: use `subgraph "Title"` — NOT `subgraph ID["Title"]` (named subgraphs require mermaid ≥10.3)
2. **Diamond nodes**: always give an explicit ID — `DECISION{"text"}` — NOT anonymous `{"text"}` after `-->`
3. **Line breaks**: `\n` works inside `["text"]`; avoid `\n` inside `{"text"}` — keep diamond labels single-line
4. **Sequence notes**: plain text only — no `<br/>`, `<br>`, or other HTML tags
5. **Special characters**: replace `&` with `and` to avoid HTML entity issues

## Core Syntax

Every diagram starts with a type declaration on the first line:

```mermaid
flowchart LR
sequenceDiagram
classDiagram
erDiagram
stateDiagram-v2
gitGraph
gantt
pie
```

Use `%%` for comments. Indentation improves readability but isn't required.

## Flowchart

### Node shapes

| Syntax | Shape |
|---|---|
| `A[text]` | Rectangle |
| `A(text)` | Rounded rectangle |
| `A([text])` | Stadium / pill |
| `A[[text]]` | Subroutine |
| `A[(text)]` | Database / cylinder |
| `A((text))` | Circle |
| `A{text}` | Rhombus / decision |
| `A{{text}}` | Hexagon |
| `A>text]` | Asymmetric / flag |
| `A[/text/]` | Parallelogram |
| `A[\text\]` | Parallelogram (reverse) |
| `A[/text\]` | Trapezoid |

### Edges

| Syntax | Type |
|---|---|
| `A --> B` | Arrow |
| `A --- B` | Link (no arrow) |
| `A -.-> B` | Dotted arrow |
| `A ==> B` | Thick arrow |
| `A -->\|label\| B` | Labeled arrow (preferred) |
| `A -- label --> B` | Labeled arrow (alt) |

### Subgraphs

Always use quoted titles:

```mermaid
flowchart LR
    subgraph "Group Name"
        A --> B
    end
```

### Example

```mermaid
flowchart TD
    Start([Start]) --> Auth{Authenticated?}
    Auth -->|Yes| Dashboard[Show dashboard]
    Auth -->|No| Login[Show login form]
    Login --> Auth
```

## Sequence Diagram

### Participants

```mermaid
sequenceDiagram
    participant A
    participant B as "Display Name"
    actor User
```

### Messages

| Syntax | Type |
|---|---|
| `->>` | Synchronous call |
| `-->>` | Synchronous response |
| `-)` | Asynchronous call |
| `--)` | Asynchronous response |
| `-x` | Delete / loss |

### Structure blocks

```mermaid
sequenceDiagram
    participant A
    participant B

    alt Condition
        A->>B: branch
    else Other
        A->>B: other branch
    end

    opt Optional
        A->>B: optional
    end

    loop Every N seconds

From hugobatista/agent-skills, MIT.

More from hugobatista/agent-skills