Mermaid Expert

Expert guidance for Mermaid.js, the powerful JavaScript library for creating diagrams and visualizations using text-based syntax. Mermaid transforms simple text descriptions into professional-looking diagrams that can be embedded in documentation, presentations, and web applications.

Additional Resources

For comprehensive documentation and advanced features, see the Mermaid Source Documentation which includes:

• Flow Charts Guide – Complete flowchart syntax and examples

For integration details and configuration options, refer to the main documentation at docs/snapshot/v11.12.1/.

Core Concepts

Mermaid is a text-to-diagram tool that allows you to create:

• Flowcharts for processes and decision trees
• Sequence diagrams for interactions and timelines
• Class diagrams for software architecture
• State diagrams for finite state machines
• Gantt charts for project management
• Git graphs for version control visualization
• Block diagrams for system layouts

Getting Started

Basic Mermaid syntax structure:

diagramType
    [diagram content]

Simple flowchart example:

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

Installation and Setup

In HTML:

<script src="https://cdn.jsdelivr.net/npm/mermaid/dist/mermaid.min.js"></script>

In Markdown/Documentation: Most modern platforms (GitHub, GitLab, Notion) support Mermaid natively using code blocks with mermaid language identifier.

Node.js/npm:

npm install mermaid

Command Line Interface

For flowchart diagrams only: mmdr (mermaid-rs-renderer)

mmdr is a fast native Rust renderer for flowchart diagrams only. It is ~1000x faster than mermaid-cli and requires no browser or Node.js.

Check if installed:

mmdr --version

If not found, install from: https://github.com/1jehuang/mermaid-rs-renderer

Usage (flowcharts only):

# Pipe to stdout
echo 'flowchart LR; A-->B-->C' | mmdr -e svg

# File to file
mmdr -i diagram.mmd -o output.svg -e svg

For all other diagram types: mermaid-cli

Check if installed:

mmdc --version

If not found, install from: https://github.com/mermaid-js/mermaid-cli

# Convert to SVG
mmdc -i input.mmd -o output.svg

# Convert to PNG with dark theme
mmdc -i input.mmd -o output.png -t dark -b transparent

# Process markdown files
mmdc -i readme.template.md -o readme.md

Flow Charts

Basic Flowchart

flowchart LR
    A[Start] --> B[Process]
    B --> C{Decision}
    C -->|Yes| D[Action 1]
    C -->|No| E[Action 2]
    D --> F[End]
    E --> F

Flowchart Syntax

• flowchart TD – Top Down direction
• flowchart LR – Left to Right direction
• A[Text] – Rectangle node
• A{Text} – Diamond decision node
• A((Text)) – Circle node
• A>Text] – Stadium shape
• A --> B – Arrow connection
• A -->|Label| B – Labeled arrow

Sequence Diagrams

Basic Sequence Diagram

sequenceDiagram
    participant Alice
    participant Bob
    Alice->>Bob: Hello Bob, how are you?
    Bob-->>Alice: I am good thanks!
    Alice->>Bob: See you later!

Sequence Diagram Syntax

• participant Name – Define participant
• A->>B: Message – Synchronous message
• A-->B: Message – Async message (dashed line)
• A-->>B: Message – Return message
• rect rgb(...) – Group messages
• loop / alt / opt – Control structures

Class Diagrams

Basic Class Diagram

classDiagram
    class Animal{
        +String name
        +eat()
    }
    class Duck{
        +quack()
    }
    Animal <|-- Duck

Class Diagram Syntax

• class ClassName{ ... } – Define class
• +Type name – Public member
• -Type name – Private member
• methodName() – Method
• Child <|-- Parent – Inheritance
• A *-- B – Composition
• A o-- B – Aggregation

State Diagrams

Basic State Diagram

stateDiagram-v2
    [*] --> Idle
    Idle --> Processing
    Processing --> Success
    Processing --> Failed
    Success --> [*]
    Failed --> [*]

State Diagram Syntax

• [*] – Start/end state
• A --> B – Transition
• A: event – Triggered transition
• state A { ... } – Composite state
• [*] --> A – Initial state

Gantt Charts

Basic Gantt Chart

gantt
    title Project Timeline
    dateFormat  YYYY-MM-DD
    section Phase 1
    Design      :a1, 2024-01-01, 7d
    section Phase 2
    Development :a2, after a1, 14d
    Testing     :a3, after a2, 7d

Gantt Syntax

• title Text – Chart title
• dateFormat YYYY-MM-DD – Date format
• section Name – Section header
• Task :id, start, duration – Define task
• after taskId – Dependency

Git Graphs

Basic Git Graph

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

Git Graph Syntax

• commit – Create commit
• branch name – Create branch
• checkout name – Switch branch
• merge name – Merge branch
• cherry-pick id – Cherry-pick commit

Block Diagrams

Basic Block Diagram

block-beta
    columns 1
    block:db:1
      database[(Database)]
    end
    block:app:2
      service[Service]
      api[API]
    end
    db -- API

Block Diagram Syntax

• block:name:width – Define block
• node[(Text)] – Rounded node
• node[Text] – Square node
• A -- B – Connection
• columns N – Column layout

Integration and Usage

In Markdown

Most platforms support Mermaid natively:

```mermaid
flowchart LR
    A --> B
```

In HTML

<script src="https://cdn.jsdelivr.net/npm/mermaid/dist/mermaid.min.js"></script>
<div class="mermaid">
flowchart LR
    A --> B
</div>

In JavaScript

import mermaid from 'mermaid';

mermaid.initialize({ startOnLoad: true });

// Render programmatically
const diagram = await mermaid.render('diagram-id', 'flowchart LR\nA-->B');

Best Practices

1. Keep diagrams simple – Complex diagrams are hard to read
2. Use consistent styling – Same shapes for similar elements
3. Add labels to connections – Clarify relationships
4. Break down complex diagrams – Split into multiple simpler ones
5. Test rendering – Different tools may render differently

Troubleshooting

Common Issues:

• Syntax errors: Check for missing semicolons or incorrect syntax
• Rendering issues: Ensure correct Mermaid version
• Platform support: Not all platforms support all diagram types
• Performance: Large diagrams may render slowly

Debug Tips:

• Start with simple diagrams
• Use official syntax validator
• Test on multiple platforms
• Check Mermaid version compatibility

See references/ADVANCED.md for advanced features including styling, theming, and complex diagram patterns.