Mermaid Expert Skill | Agent Skills

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

Keep diagrams simple - Complex diagrams are hard to read
Use consistent styling - Same shapes for similar elements
Add labels to connections - Clarify relationships
Break down complex diagrams - Split into multiple simpler ones
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.

Agent Skills: Mermaid Expert

Install this agent skill to your local

Skill Files