Mermaid Diagram Generation

Generate text-based diagrams using Mermaid syntax. Mermaid diagrams render directly in GitHub, GitLab, Notion, and many markdown viewers.

Quick Start

Minimal flowchart:

flowchart TD
    A[Start] --> B[End]

Output Formats

1. Markdown code block - Embed in .md files:

   ```mermaid
   flowchart TD
       A --> B
   ```
   

2. Standalone file - .mmd or .mermaid extension:

   flowchart TD
       A --> B
   

Workflow

1. Identify diagram type - Match user intent to diagram type
2. Plan structure - List nodes/entities and relationships
3. Generate syntax - Write Mermaid code following type-specific patterns
4. Output - Write to file or embed in markdown

Diagram Types Overview

Flowchart

Direction: TD (top-down), LR (left-right), BT, RL

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

Sequence Diagram

sequenceDiagram
    participant U as User
    participant S as Server
    U->>S: Request
    S-->>U: Response

Class Diagram

classDiagram
    class Animal {
        +String name
        +makeSound()
    }
    class Dog {
        +bark()
    }
    Animal <|-- Dog

Entity Relationship (ER)

erDiagram
    USER ||--o{ ORDER : places
    ORDER ||--|{ LINE_ITEM : contains
    PRODUCT ||--o{ LINE_ITEM : "ordered in"

State Diagram

stateDiagram-v2
    [*] --> Idle
    Idle --> Processing : start
    Processing --> Done : complete
    Done --> [*]

Gantt Chart

gantt
    title Project Timeline
    dateFormat YYYY-MM-DD
    section Phase 1
    Task A :a1, 2024-01-01, 30d
    Task B :after a1, 20d

Pie Chart

pie title Distribution
    "Category A" : 40
    "Category B" : 30
    "Category C" : 30

Mindmap

mindmap
    root((Central Topic))
        Branch A
            Leaf 1
            Leaf 2
        Branch B
            Leaf 3

Timeline

timeline
    title History
    2020 : Event A
    2021 : Event B
    2022 : Event C

Git Graph

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

Node Shapes (Flowchart)

Shape	Syntax	Use For
Rectangle	[text]	Process/action
Rounded	(text)	Start/end
Stadium	([text])	Terminal
Subroutine	[[text]]	Subprocess
Database	[(text)]	Data store
Circle	((text))	Connector
Diamond	{text}	Decision
Hexagon	{{text}}	Preparation
Parallelogram	[/text/]	Input/Output
Trapezoid	[/text\]	Manual operation

Arrow Types

Arrow	Syntax	Meaning
Solid	-->	Flow
Dotted	-.->	Optional/async
Thick	==>	Important
With text	`-->	label
Open	---	Association

Styling

Inline styling

flowchart TD
    A[Start]:::green --> B[End]:::red
    classDef green fill:#90EE90
    classDef red fill:#FFB6C1

Theme configuration

%%{init: {'theme': 'forest'}}%%
flowchart TD
    A --> B

Available themes: default, forest, dark, neutral, base

Critical Rules

1. Indentation - Use consistent 4-space indentation
2. Node IDs - Use short, unique identifiers (A, B, node1)
3. Special characters - Wrap text with special chars in quotes: A["Text with (parens)"]
4. Subgraphs - Close with end keyword
5. No trailing whitespace - Can cause parsing issues

Subgraphs (Flowchart)

flowchart TD
    subgraph Group1[First Group]
        A --> B
    end
    subgraph Group2[Second Group]
        C --> D
    end
    B --> C

When to Use Mermaid

• Documentation in markdown files
• README diagrams (GitHub/GitLab render natively)
• Sequence diagrams for API flows
• Class diagrams for OOP design
• ER diagrams for database schema
• Gantt charts for project planning
• Quick diagrams that don't need precise positioning

References

See references/diagram-types.md for complete examples of each diagram type. See references/syntax-reference.md for detailed syntax and configuration options.