Mermaid Diagrams

Mermaid Diagrams

Create professional software diagrams using Mermaid's text-based syntax. Diagrams are version-controllable, easy to update, and render automatically in GitHub, GitLab, Notion, and most markdown viewers.

Quick Workflow

1. Select diagram type using decision matrix below
2. Start with core elements - entities, actors, or components
3. Add relationships - connections, flows, interactions
4. Validate - check syntax, completeness, clarity
5. Style (optional) - apply themes or custom styling

Diagram Type Selection

Use this decision matrix to choose the right diagram type:

Core Syntax Pattern

All Mermaid diagrams follow this pattern:

diagramType
  definition content

Key principles:

• First line declares diagram type (e.g., classDiagram, sequenceDiagram, flowchart)
• Use %% for comments
• Line breaks improve readability but aren't required
• Unknown words break diagrams; parameters fail silently

Quick Examples

Flowchart

flowchart TD
    Start([Start]) --> Process[Process Data]
    Process --> Decision{Valid?}
    Decision -->|Yes| Success[Success]
    Decision -->|No| Error[Error]

Sequence Diagram

sequenceDiagram
    participant User
    participant API
    User->>API: Request
    API-->>User: Response

ERD

erDiagram
    USER ||--o{ ORDER : places
    USER {
        int id PK
        string email UK
    }

Class Diagram

classDiagram
    Title -- Genre
    Title *-- Season
    class Title {
        +string name
        +play()
    }

Validation Checklist

Before finalizing a diagram, verify:

• Diagram type matches content and purpose
• All entities/components/actors identified
• Relationships/connections are accurate
• Syntax is valid (test in Mermaid Live)
• Labels are clear and descriptive
• Flow direction is logical
• All paths/outcomes are covered (for flowcharts)
• Start and end states defined (where applicable)

Common Patterns

See workflows.md for step-by-step workflows and examples.md for common patterns including:

• API request flows
• Authentication sequences
• Error handling flows
• Database schema design
• Architecture documentation

Styling and Theming

Apply themes and custom styling. See advanced-features.md for:

• Built-in themes (default, forest, dark, neutral, base)
• Custom color schemes
• Node styling
• Layout options

Detailed References

For comprehensive syntax and advanced features:

• flowcharts.md - Node shapes, decision logic, subgraphs
• sequence-diagrams.md - Actors, messages, activations, alt/loop blocks
• erd-diagrams.md - Entities, relationships, cardinality, keys
• class-diagrams.md - Relationships, multiplicity, methods/properties
• c4-diagrams.md - Context, container, component levels
• state-diagrams.md - States, transitions, lifecycle
• gantt-charts.md - Tasks, dependencies, timelines
• git-graphs.md - Branches, commits, merges
• charts.md - Pie charts, bar charts, data visualization
• advanced-features.md - Themes, styling, configuration

Best Practices

1. Start simple - Begin with core elements, add complexity incrementally
2. One diagram, one concept - Keep focused; split large views into multiple diagrams
3. Use meaningful names - Clear labels make diagrams self-documenting
4. Comment liberally - Use %% to explain non-obvious relationships
5. Version control - Store .mmd files with code, update as system evolves
6. Validate syntax - Test in Mermaid Live before committing
7. Keep readable - Don't overcrowd; split if needed (max ~20 nodes recommended)

Export and Rendering

Native support:

• GitHub/GitLab - Automatic rendering in .md files
• VS Code - With Markdown Mermaid extension
• Notion, Obsidian, Confluence - Built-in support

Export options:

• Mermaid Live Editor - Online editor with PNG/SVG export
• Mermaid CLI - npm install -g @mermaid-js/mermaid-cli then mmdc -i input.mmd -o output.png