Mermaid Complete Beginner's Guide: Draw Professional Diagrams with Code

In technical documentation, project management, and team communication, diagrams are indispensable tools for expressing ideas. However, traditional drag-and-drop drawing tools are often inefficient and costly to maintain. Mermaid completely changes this landscape by letting you create professional-grade diagrams with simple text code.

This guide will take you from zero to hero, covering Mermaid's core concepts, basic syntax, and practical tips so you can draw beautiful flowcharts, sequence diagrams, Gantt charts, and more within minutes.

What Is Mermaid?

Mermaid is a JavaScript-based diagramming tool built on the philosophy of "Diagram as Code." Unlike traditional drag-and-drop tools like Visio or ProcessOn, Mermaid lets you define diagram structures using Markdown-like text syntax, which a rendering engine then converts into visual graphics automatically.

This approach brings numerous significant advantages:

• Version-control friendly: Diagram code can be managed in Git just like source code, with a complete history of every change.
• Rapid iteration: Editing text is far faster than dragging shapes, especially for large diagrams.
• Team collaboration: Developers can view and edit diagrams directly in the code repository without extra design software.
• Automation: Combine with scripts and CI/CD pipelines to auto-generate and update documentation diagrams.
• Cross-platform compatibility: Mermaid syntax is natively supported by GitHub, GitLab, Notion, and many other platforms.

What Diagram Types Does Mermaid Support?

Mermaid currently supports over 15 diagram types, covering the vast majority of technical scenarios:

For beginners, we recommend starting with Flowcharts because the syntax is the most intuitive and the use cases are the broadest.

How to Write Your First Mermaid Flowchart?

Flowcharts are the most commonly used diagram type in Mermaid. The basic syntax is very simple, defining processes primarily through nodes and connections.

Basic Syntax Structure

Every Mermaid flowchart starts with the graph keyword followed by a direction specifier:

graph TD
    A[Start] --> B[Process]
    B --> C[End]

The direction specifier determines the overall layout of the diagram:

• TB or TD: Top to Bottom / Top Down
• BT: Bottom to Top
• LR: Left to Right
• RL: Right to Left

Node Shapes

Mermaid provides a rich variety of node shapes, defined by different bracket symbols:

graph LR
    A[Rectangle] --> B(Rounded Rectangle)
    B --> C{Diamond}
    C --> D((Circle))
    D --> E>Flag Shape]

Quick reference for common node shapes:

Link Styles

Links not only show flow direction but can also express specific meanings through different styles:

graph TD
    A --> B
    A -.-> C
    A ==> D
    A -- Label --> E

A Complete Business Logic Example

Let's demonstrate a complete flowchart with a user login process:

graph TD
    A([Start]) --> B{User Logged In?}
    B -->|Yes| C[Redirect to Home]
    B -->|No| D[Show Login Form]
    D --> E{Validation Success?}
    E -->|Yes| F[Create Session]
    E -->|No| G[Show Error Message]
    G --> D
    F --> C
    C --> H([End])

This example demonstrates decision nodes, loopback, and label annotations commonly found in flowcharts.

Advanced Tips: Subgraphs and Styling

When processes become complex, you can use subgraphs to group related nodes, making the structure clearer.

Grouping with Subgraphs

graph TB
    subgraph Authentication Module
        A[Enter Username] --> B{Validate Format}
        B -->|Valid| C[Query Database]
        B -->|Invalid| D[Prompt Error]
    end
    
    subgraph Session Management
        C --> E[Generate Token]
        E --> F[Set Cookie]
    end
    
    D --> A
    F --> G[Return to Home]

Custom Node Styles

You can add colors and styles to nodes to highlight important steps or differentiate node types:

graph LR
    A[Normal Step] --> B[Critical Step]
    B --> C[Success End]
    B --> D[Failure Handling]
    
    style B fill:#f9f,stroke:#333,stroke-width:2px
    style C fill:#9f9,stroke:#333
    style D fill:#f99,stroke:#333

Style property reference:

• fill: Fill color (supports hex, RGB, color names)
• stroke: Border color
• stroke-width: Border thickness
• stroke-dasharray: Dashed border

Where Can You Use Mermaid?

Mermaid's power lies in its wide compatibility. The following platforms natively support Mermaid rendering:

• GitHub / GitLab: Write Mermaid code blocks directly in Markdown files to render diagrams
• Notion: Add a Code block and select the Mermaid language
• Obsidian: Install the Mermaid plugin for direct preview
• Markdown Editors: Typora, MarkText, and others support Mermaid rendering
• Documentation Sites: MkDocs, Docusaurus, VuePress, and more can integrate via plugins

If your target platform doesn't support Mermaid, you can use tools like Mermaid2Img to convert Mermaid code into PNG, SVG, or PDF images and insert them into any image-supporting platform.

Learning Tips and Resources

The best way to master Mermaid is learning by doing. Here are some practical tips:

1. Start with flowcharts: Flowchart syntax is the most intuitive and widely applicable—master this one first.
2. Leverage official docs: The Mermaid official documentation (mermaid.js.org) is very comprehensive; refer to it whenever you're unsure about syntax.
3. Use an online editor: The Mermaid Live Editor (mermaid.live) is useful for practicing syntax. When you also need PNG, SVG, PDF, or JPG downloads, use the Mermaid2Img online Mermaid editor or the focused Mermaid live editor export workspace.
4. Build a personal template library: Collect and organize commonly used diagram templates to significantly boost future productivity.
5. Focus on readability: The core value of a diagram is clearly conveying information—avoid overcomplication.

Summary

Mermaid's "Diagram as Code" philosophy transforms diagram creation from GUI-based operations into text-based coding, greatly improving drawing efficiency and collaboration for technical professionals. Whether you're a developer, product manager, or technical writer, mastering Mermaid will make your documentation and communication more professional and efficient.

Starting from the flowchart basics introduced in this article, you can gradually explore sequence diagrams, class diagrams, Gantt charts, and more. Remember, a good diagram isn't about fancy visual effects but about whether it conveys information clearly and accurately. Start your Mermaid journey today!

Want to quickly export your Mermaid diagrams as high-quality images? Try Mermaid2Img, a free Mermaid online editor supporting PNG, SVG, PDF, and more. All processing happens in your browser, protecting your code privacy.