Mermaid.js Tutorial: Complete Beginner's Guide

Mermaid.js has become the standard for technical documentation, especially in developer communities. It's supported natively by GitHub, GitLab, Notion, and many other platforms, making it easy to embed diagrams directly in your documentation.

Why Learn Mermaid.js?

• Version Control Friendly: Diagrams are text, so they work with Git
• Fast to Create: No drag-and-drop, just type
• Easy to Maintain: Update text, diagram updates automatically
• Widely Supported: GitHub, GitLab, Notion, and more
• Professional Output: Clean, consistent diagrams
• Free and Open Source: MIT licensed

Getting Started: Your First Flowchart

The most common diagram type is the flowchart. Here's a simple example:

flowchart TD
    Start --> Stop

This creates a basic flowchart with two nodes: "Start" and "Stop", connected by an arrow.

Adding Nodes and Connections

flowchart TD
    A[Start] --> B{Is it working?}
    B -->|Yes| C[Great!]
    B -->|No| D[Debug]
    D --> B
    C --> E[End]

Syntax explained:

• flowchart TD - TD means Top Down (vertical flow)
• A[Text] - Square brackets create a rectangle
• B{Text} - Curly braces create a diamond (decision)
• --> - Arrow connecting nodes
• |Label| - Text label on the arrow

Creating Sequence Diagrams

Sequence diagrams show interactions between components:

sequenceDiagram
    participant A as Client
    participant B as Server
    participant C as Database
    
    A->>B: Request Data
    B->>C: Query
    C-->>B: Results
    B-->>A: Response

Key syntax:

• participant X as Name - Define participants
• ->> - Solid arrow (request)
• -->>) - Dashed arrow (response)

Other Popular Diagram Types

Class Diagram

classDiagram
    class User {
      +String name
      +String email
      +login()
      +logout()
    }
    class Order {
      +Int id
      +Date date
      +placeOrder()
    }
    User --> Order : places

Gantt Chart

gantt
    title Project Timeline
    dateFormat YYYY-MM-DD
    section Planning
    Requirements :a1, 2026-01-01, 7d
    Design      :a2, after a1, 5d
    section Development
    Coding      :a3, after a2, 14d
    Testing     :a4, after a3, 7d

Mermaid.js Best Practices

• Use descriptive IDs: Instead of A, B, C, use meaningful names like "User", "API", "DB"
• Keep diagrams focused: One diagram per use case or feature
• Comment your code: Use %% comment for explanations
• Test before committing: Use a live editor to verify syntax
• Use subgraphs: Group related elements with subgraph

Common Mistakes to Avoid

• Forgetting spaces around arrows: A-->B (wrong) vs A --> B (right)
• Using special characters in node IDs without quotes
• Missing closing brackets or braces
• Creating overly complex diagrams (keep them simple!)

AI-Powered Mermaid Creation

Learning Mermaid syntax takes time. AI-powered tools like SmoothMermaid let you describe diagrams in plain English and automatically generate the Mermaid code.

For example, type: "Show a user registration flow with email verification" and get instant Mermaid code:

flowchart TD
    A[User enters email] --> B{Email valid?}
    B -->|Yes| C[Send verification]
    C --> D[User clicks link]
    D --> E[Account activated]
    B -->|No| F[Show error]
    F --> A

Next Steps

Now that you understand the basics:

1. Practice with simple flowcharts
2. Try different diagram types
3. Integrate diagrams into your documentation
4. Use AI tools to speed up creation

Start Creating Mermaid Diagrams

Ready to create professional diagrams without learning complex syntax? Try SmoothMermaid's AI-powered editor—describe your diagram in plain English and watch it appear instantly.