Mermaid Diagrams in Markdown

Mermaid is a markdown-based diagramming tool that lets you create diagrams using text. Learn to create flowcharts, sequence diagrams, Gantt charts, and more using Mermaid syntax in markdown for technical documentation.

Quick answer: Use fenced code blocks with mermaid language identifier to create diagrams. Example: mermaid\ngraph TD\nA-->B\n renders as a flowchart with boxes A and B connected by arrow.

---

What is Mermaid?

Overview

Mermaid is a JavaScript-based diagramming and charting tool that uses markdown-inspired text definitions. It's:

• Text-based: Write diagrams as markdown code blocks
• Version control friendly: Plain text, diffable
• Easy to learn: Simple, intuitive syntax
• Professional quality: Beautiful, rendered diagrams
• Supported platforms: GitHub, GitLab, Obsidian, and more

Statistics: Mermaid has 80,000+ weekly downloads on npm and is used by 30% of technical documentation projects (2025 developer survey).

Supported Diagram Types

Mermaid Syntax Basics

Diagram Declaration

Elements:

• graph TD: Top-down graph
• A[Start]: Node with text (box shape)
• -->: Arrow connection
• {Decision}: Diamond shape
• |Yes|: Labeled arrow

Node Shapes

Shapes:

• [Text]: Rectangle (default)
• [Text]: Text box
• (Text): Rounded rectangle
• ((Text)): Circle
• ((Text)): Circle
• {Text}: Diamond (decision)
• >Text]: Subroutine
• [Stadium node]: Stadium shape
• (Cylinder node): Cylinder

Connections

Connection types:

• -->: Solid arrow
• -.->: Dotted arrow
• ==>: Bold arrow
• --: Solid line
• -.: Dotted line
• |Label|: Connection label

Flowcharts

Basic Flowchart

Complex Flowchart with Subgraphs

Flowchart Styling

Sequence Diagrams

Basic Sequence Diagram

Complex Sequence with Loops

Sequence with Alt and Opt

Gantt Charts

Basic Gantt Chart

Gantt with Milestones

Class Diagrams

Basic Class Diagram

Complex Class Diagram

Relationships

Relationship types:

• --|>: Inheritance
• -->: Association
• ..>: Dependency
• -->: Realization

State Diagrams

Basic State Diagram

State Diagram with Actions

Pie Charts

Basic Pie Chart

Pie Chart with Sections

Entity Relationship Diagrams

Basic ER Diagram

ER Diagram with Attributes

User Journey Diagram

Basic User Journey

User Journey with Feedback

Git Graphs

Basic Git Graph

Complex Git Graph

Styling and Themes

Custom Styles

Built-in Themes

Available themes:

• default: Light theme
• dark: Dark theme
• forest: Green theme
• neutral: Grey theme
• base: Base theme (customizable)

Best Practices

1. Keep Diagrams Simple

2. Use Consistent Naming

3. Add Comments

4. Test on Multiple Platforms

Common Mermaid Mistakes

Syntax Errors

Over-Complexity

Missing Labels

FAQ

What platforms support Mermaid?

Mermaid is supported on GitHub, GitLab, Obsidian, Notion, Docusaurus, and many markdown editors. Check your platform's documentation for support.

Can I customize Mermaid diagrams?

Yes, Mermaid supports custom themes, styles, and configuration. You can also define custom node shapes and connections.

Is Mermaid free?

Yes, Mermaid is open source under MIT license and free to use in any project.

What's the difference between Mermaid and other diagram tools?

Mermaid is text-based (markdown), while tools like draw.io are GUI-based. Mermaid is better for version control and automation.

Can I export Mermaid diagrams to images?

Yes, you can export Mermaid diagrams to PNG, SVG, or PDF using the Mermaid CLI or online tools.

How do I debug Mermaid diagrams?

Check syntax carefully, use online Mermaid live editor for testing, and verify rendering on your target platform.

Summary

Mermaid Diagram Types:

• Flowcharts: Process flows, decision trees
• Sequence Diagrams: System interactions, API calls
• Gantt Charts: Project timelines, schedules
• Class Diagrams: Software architecture, OOP
• State Diagrams: State machines, workflows
• ER Diagrams: Database design, relationships
• User Journey: UX flows, user paths
• Pie Charts: Data visualization
• Git Graphs: Commit history, branches

Best Practices:

• Keep diagrams simple and clear
• Use consistent naming conventions
• Add comments for clarity
• Test on multiple platforms
• Use appropriate diagram type for use case
• Avoid over-complexity

Supported Platforms:

• GitHub (native)
• GitLab (native)
• Obsidian (native)
• Notion (partial)
• Docusaurus (with plugin)
• VS Code (with extension)

Try Mermaid in Markdown Visualizer — Free editor with Mermaid diagram support and live preview.

Data sources: Mermaid documentation, GitHub and GitLab feature documentation, industry best practices for technical diagrams (2025-2026).