If you've ever needed to explain a process, system, or workflow to someone and a text email just won't cut it diagrams help. But drawing them by hand takes time, and dragging boxes around in a GUI tool gets tedious fast. That's where mermaid diagram code examples come in. Mermaid lets you write plain text that renders into flowcharts, sequence diagrams, Gantt charts, and more. You type simple markup, and a diagram appears. For developers, technical writers, and anyone who works in docs or code, this is a big deal. No image files. No bloated tools. Just code.

What exactly is Mermaid, and how does it work?

Mermaid is a JavaScript-based diagramming and charting tool that uses a markdown-like text syntax to generate diagrams dynamically. You write short text descriptions using keywords like graph, sequenceDiagram, or classDiagram, and Mermaid's renderer turns them into SVG or PNG visuals. It runs in browsers, integrates with GitHub, GitLab, Notion, Obsidian, Confluence, and many other platforms. The official Mermaid documentation covers every supported diagram type.

Think of it as diagram-as-code. Instead of clicking and dragging, you write a few lines of structured text, and a diagram is generated from it. This is similar in spirit to how tools like PlantUML work if you've used PlantUML sequence diagram syntax, the concept will feel familiar.

Why would someone use Mermaid instead of a visual diagram tool?

A few reasons keep coming up in practice:

  • Version control. Diagrams live as text files in your repo. You can diff them, review them in pull requests, and track changes over time.
  • Speed. Once you learn the syntax, writing a flowchart in Mermaid takes a fraction of the time it takes in a drag-and-drop editor.
  • Portability. Mermaid code works everywhere markdown files, wikis, documentation sites, blogs, and even chat platforms that support it.
  • Maintenance. Updating a diagram means editing a few lines of text. No need to open a separate application, find the file, move boxes, re-export, and re-upload.

If you're comparing different approaches to diagramming with code, our breakdown of diagram-as-code tools for developers goes deeper into how Mermaid stacks up against alternatives.

What are the most common Mermaid diagram types?

Mermaid supports many diagram types, but here are the ones you'll run into most often:

  • Flowcharts for decision logic, processes, and workflows
  • Sequence diagrams for interactions between systems or actors over time
  • Class diagrams for object-oriented design and data models
  • Gantt charts for project timelines and scheduling
  • Entity-relationship diagrams for database schema design
  • State diagrams for modeling state transitions
  • Pie charts for simple data visualization

Each type has its own keyword to start the diagram. Let's look at real code examples for each of the most popular ones.

Can you show a basic Mermaid flowchart example?

Flowcharts are the most common use case. Here's a simple one:

graph TD
 A[Start] --> B{Is it working?}
 B -->|Yes| C[Great, ship it]
 B -->|No| D[Debug the code]
 D --> B

This creates a top-down flowchart with a decision diamond and a loop back. The TD means top-down. You can also use LR for left-to-right layout.

Key syntax rules for flowcharts:

  • Use [] for rectangles, {} for diamonds, (()) for circles, and [/ /] for parallelograms.
  • Connect nodes with --> and add labels with |text| between arrows.
  • Node IDs (like A, B, C) are internal references. The text in brackets is what displays.

What does a Mermaid sequence diagram look like?

Sequence diagrams show how different participants exchange messages. They're useful for API flows, authentication steps, and microservice communication.

sequenceDiagram
 participant User
 participant Frontend
 participant API
 participant Database

 User->>Frontend: Clicks "Login"
 Frontend->>API: POST /auth/login
 API->>Database: Query user credentials
 Database-->>API: User record
 API-->>Frontend: JWT token
 Frontend-->>User: Dashboard loaded

Arrows with ->> are solid (synchronous calls), and -->> are dashed (responses). You can add notes, loops, and alt blocks too:

sequenceDiagram
 participant Client
 participant Server

 Client->>Server: Request data
 alt Data found
 Server-->>Client: 200 OK with payload
 else Data not found
 Server-->>Client: 404 Not Found
 end

Developers who work with UML diagram code in Python often use sequence diagrams as a first step before writing implementation code.

How do you make a class diagram in Mermaid?

Class diagrams model the structure of your code classes, their properties, methods, and relationships. Here's an example:

classDiagram
 class Animal {
 +String name
 +int age
 +makeSound() void
 }
 class Dog {
 +fetch() void
 }
 class Cat {
 +purr() void
 }
 Animal <|-- Dog
 Animal <|-- Cat

The + symbol means public, - means private, and # means protected. Inheritance uses <|--, composition uses --, and aggregation uses o--.

What about Gantt charts and ER diagrams?

Gantt charts help with project planning:

gantt
 title Website Redesign Project
 dateFormat YYYY-MM-DD
 section Design
 Wireframes :done, des1, 2024-01-01, 7d
 Mockups :active, des2, 2024-01-08, 10d
 section Development
 Frontend : dev1, after des2, 14d
 Backend : dev2, after des2, 10d
 section Testing
 QA : qa1, after dev1, 7d

Entity-relationship diagrams model database tables and their relationships:

erDiagram
 USER ||--o{ ORDER : places
 ORDER ||--|{ ORDER_ITEM : contains
 PRODUCT ||--o{ ORDER_ITEM : "is part of"

 USER {
 int id PK
 string email
 string name
 }
 ORDER {
 int id PK
 date created_at
 string status
 }
 PRODUCT {
 int id PK
 string name
 float price
 }

The ||--o{ notation describes cardinality one-to-many, one-to-one, and so on. This mirrors how database schemas are designed in practice.

Where can you actually render Mermaid diagrams?

You don't need a special tool to get started. Here are the most common places Mermaid code works:

  • GitHub and GitLab both render Mermaid code blocks in markdown files, issues, and pull requests automatically.
  • VS Code with the Mermaid extension, you get live preview as you type.
  • Notion and Obsidian both support Mermaid blocks natively.
  • Mermaid Live Editor the Mermaid Live Editor lets you write and preview diagrams in the browser, then export as SVG or PNG.
  • Static site generators tools like Docusaurus, MkDocs, and Hugo have plugins for Mermaid rendering.

What common mistakes trip people up with Mermaid syntax?

After working with Mermaid across many projects, here are the issues that come up repeatedly:

  • Forgetting the diagram type keyword. Every diagram must start with its type graph, sequenceDiagram, classDiagram, etc. Without it, nothing renders.
  • Using special characters in labels without quotes. Parentheses, brackets, and pipes in label text will break the parser. Wrap them in double quotes: A["Label with (parentheses)"].
  • Inconsistent indentation. Mermaid doesn't require strict indentation like YAML does, but mixing tabs and spaces inside sequence diagram blocks can cause parsing issues in some renderers.
  • Arrow syntax errors. A common flowchart mistake is writing A -> B instead of A --> B. Mermaid requires double hyphens.
  • Assuming all platforms render the same version. GitHub uses a specific Mermaid version. If you're using newer syntax features, they might not render there yet. Test on the live editor first.
  • Overly complex diagrams. Mermaid handles moderate complexity well, but huge diagrams with 50+ nodes can become unreadable. Break them into smaller linked diagrams instead.

How do you style and customize Mermaid diagrams?

Mermaid supports basic theming and inline styling. You can change colors, fonts, and shapes using the %%{init}%% directive or theme variables:

%%{init: {'theme': 'dark', 'themeVariables': {'primaryColor': '#4CAF50'}}}%%
graph LR
 A[Build] --> B[Test] --> C[Deploy]

Available themes include default, dark, forest, and neutral. For more granular control, you can use CSS classes:

graph TD
 A[Normal]:::highlight --> B[Also Normal]
 classDef highlight fill:#f96,stroke:#333,stroke-width:2px

What's the best way to learn Mermaid syntax quickly?

Start with flowcharts they're the simplest and most visual. Write three or four different flowcharts for real processes you know (a login flow, a CI/CD pipeline, a support ticket process). Then move to sequence diagrams for API interactions you're familiar with.

Keep the Mermaid syntax reference open while you work. After a few hours of practice, the syntax becomes second-enough that you'll start writing diagrams without checking docs.

A quick checklist for your next Mermaid diagram

  1. Start every diagram with the correct type keyword (graph, sequenceDiagram, classDiagram, etc.).
  2. Use the Mermaid Live Editor to test your code before committing it to a repo or docs page.
  3. Quote any label text that contains parentheses, brackets, pipes, or special characters.
  4. Keep diagrams focused if a diagram has more than 20-25 nodes, consider splitting it.
  5. Use subgraph blocks to group related nodes in complex flowcharts.
  6. Pick a consistent theme across your documentation for a professional look.
  7. Test rendering on your target platform (GitHub, Notion, your docs site) since Mermaid versions differ.

Mermaid makes diagramming feel like writing code fast, versionable, and maintainable. Start with one diagram type, use real examples from your work, and expand from there. The syntax is small enough to learn in an afternoon, and the payoff shows up every time you need to explain how something works.