Mermaid Diagrams Quickstart and Cheatsheet for Developers

Mermaid is a text-based diagramming tool for people who would rather write diagrams than drag boxes around a canvas. It uses a Markdown-like syntax to describe flowcharts, sequence diagrams, class diagrams, state machines, timelines, Gantt charts, entity relationship diagrams, and more.

For a technical blog, Mermaid is a very good default. The diagrams live next to the article, they can be reviewed in Git, and they are easy to update when the system changes. Static image diagrams look nice until the first architecture change. Mermaid diagrams are not perfect, but they age much better.

This guide is a practical Mermaid quickstart and cheatsheet for developers, technical writers, and Hugo site owners. It is part of the Documentation Tools in 2026: Markdown, LaTeX, PDF & Printing Workflows hub.

What Is Mermaid?

Mermaid is a diagram-as-code syntax. You write a small text block, and Mermaid renders it as a diagram.

A basic Mermaid diagram looks like this:

this code:

```mermaid
flowchart TD
    A[Write Markdown] --> B[Add Mermaid block]
    B --> C[Render page]
    C --> D[Publish diagram]
```

Is producing diagram:

flowchart TD
    A[Write Markdown] --> B[Add Mermaid block]
    B --> C[Render page]
    C --> D[Publish diagram]

The important idea is simple: the source of the diagram is plain text. That makes it searchable, reviewable, portable, and easy to keep with the documentation it explains.

Why Use Mermaid in a Technical Blog?

Mermaid is useful when your article needs more than prose but less than a full design tool.

Use Mermaid when you want to explain:

• Request and response flows
• Deployment pipelines
• Service dependencies
• State transitions
• Database relationships
• User journeys
• Build steps
• Decision logic
• Project timelines

I would not use Mermaid for every visual. Screenshots, hand-drawn architecture sketches, and polished marketing diagrams still have their place. But for engineering documentation, Mermaid is often the most maintainable option.

Mermaid Quickstart

Basic Markdown Usage

In Markdown, use a fenced code block with mermaid as the language:

```mermaid
flowchart LR
    A[Start] --> B[Process]
    B --> C[Done]
```

Many platforms understand this format directly. mermaid is one of the special language identifiers — alongside diff, geojson, and others — that certain renderers treat as a first-class block type rather than plain syntax highlighting. For a full breakdown of fenced block syntax and supported language identifiers, see the Markdown Code Blocks guide. For Hugo, rendering depends on your theme or site configuration. More on that later.

Test Diagrams Before Publishing

The easiest workflow is:

1. Write the diagram in your Markdown file.
2. Paste it into a Mermaid live editor or local preview.
3. Fix syntax errors.
4. Commit the Markdown source.
5. Check the final rendered page.

This avoids the classic problem where a diagram works in one renderer but breaks in another because of a small syntax detail.

Flowchart Syntax

Flowcharts are the most common Mermaid diagram type. Use them for workflows, algorithms, decision trees, and system steps.

Basic Flowchart

this code:

```mermaid
flowchart TD
    A[User opens website] --> B{Is user logged in?}
    B -->|Yes| C[Show dashboard]
    B -->|No| D[Show login page]
```

Is producing diagram:

flowchart TD
    A[User opens website] --> B{Is user logged in?}
    B -->|Yes| C[Show dashboard]
    B -->|No| D[Show login page]

Flowchart Directions

Mermaid flowcharts support several directions:

TD - top to bottom
TB - top to bottom
BT - bottom to top
LR - left to right
RL - right to left

Example:

this code:

```mermaid
flowchart LR
    Browser --> CDN
    CDN --> WebServer
    WebServer --> Database
```

Is producing diagram:

flowchart LR
    Browser --> CDN
    CDN --> WebServer
    WebServer --> Database

For blog articles, LR is often easier to read for architecture diagrams. For step-by-step processes, TD is usually better.

Common Node Shapes

this code:

```mermaid
flowchart TD
    A[Rectangle]
    B(Rounded rectangle)
    C{Decision}
    D((Circle))
    E[(Database)]
    F[[Subroutine]]
```

Is producing diagram:

flowchart TD
    A[Rectangle]
    B(Rounded rectangle)
    C{Decision}
    D((Circle))
    E[(Database)]
    F[[Subroutine]]

Flowchart Arrows

this code:

```mermaid
flowchart LR
    A --> B
    B --- C
    C -.-> D
    D ==> E
    E -- Label --> F
```

Is producing diagram:

flowchart LR
    A --> B
    B --- C
    C -.-> D
    D ==> E
    E -- Label --> F

Subgraphs

Use subgraphs to group related parts of a system.

this code:

```mermaid
flowchart LR
    subgraph Client
        Browser
    end

    subgraph Backend
        API
        Worker
    end

    subgraph Storage
        DB[(PostgreSQL)]
        Cache[(Redis)]
    end

    Browser --> API
    API --> DB
    API --> Cache
    API --> Worker
```

Is producing diagram:

flowchart LR
    subgraph Client
        Browser
    end

    subgraph Backend
        API
        Worker
    end

    subgraph Storage
        DB[(PostgreSQL)]
        Cache[(Redis)]
    end

    Browser --> API
    API --> DB
    API --> Cache
    API --> Worker

Subgraphs are powerful, but use them carefully. A diagram with six subgraphs and twenty arrows is usually a sign that the article needs two smaller diagrams.

Sequence Diagram Syntax

Sequence diagrams show communication between actors or services over time.

this code:

```mermaid
sequenceDiagram
    participant User
    participant App
    participant API
    participant DB

    User->>App: Click login
    App->>API: POST /login
    API->>DB: Validate credentials
    DB-->>API: User record
    API-->>App: Access token
    App-->>User: Show dashboard
```

Is producing diagram:

sequenceDiagram
    participant User
    participant App
    participant API
    participant DB

    User->>App: Click login
    App->>API: POST /login
    API->>DB: Validate credentials
    DB-->>API: User record
    API-->>App: Access token
    App-->>User: Show dashboard

Common Sequence Arrows

->      solid line without arrow
-->     dotted line without arrow
->>     solid line with arrow
-->>    dotted line with arrow
-x      solid line with cross
--x     dotted line with cross

Activation Bars

Activation bars make it clearer when a participant is doing work.

this code:

```mermaid
sequenceDiagram
    participant Client
    participant Server

    Client->>Server: Request data
    activate Server
    Server-->>Client: Response
    deactivate Server
```

Is producing diagram:

sequenceDiagram
    participant Client
    participant Server

    Client->>Server: Request data
    activate Server
    Server-->>Client: Response
    deactivate Server

Alternatives and Conditions

this code:

```mermaid
sequenceDiagram
    participant User
    participant API
    participant Payment

    User->>API: Submit order

    alt Payment succeeds
        API->>Payment: Charge card
        Payment-->>API: Approved
        API-->>User: Order confirmed
    else Payment fails
        Payment-->>API: Declined
        API-->>User: Show error
    end
```

Is producing diagram:

sequenceDiagram
    participant User
    participant API
    participant Payment

    User->>API: Submit order

    alt Payment succeeds
        API->>Payment: Charge card
        Payment-->>API: Approved
        API-->>User: Order confirmed
    else Payment fails
        Payment-->>API: Declined
        API-->>User: Show error
    end

Sequence diagrams are excellent for API articles. They show not just what components exist, but how they talk to each other.

Class Diagram Syntax

Class diagrams are useful for domain models and object relationships.

this code:

```mermaid
classDiagram
    class User {
        +string id
        +string email
        +login()
        +logout()
    }

    class Order {
        +string id
        +float total
        +submit()
    }

    User "1" --> "*" Order
```

Is producing diagram:

classDiagram
    class User {
        +string id
        +string email
        +login()
        +logout()
    }

    class Order {
        +string id
        +float total
        +submit()
    }

    User "1" --> "*" Order

Class Relationships

<|-- inheritance
*-- composition
o-- aggregation
--> association
-- link
..> dependency
..|> realization

Example:

this code:

```mermaid
classDiagram
    Animal <|-- Dog
    Animal <|-- Cat
    User "1" --> "*" Order
    Order *-- OrderItem
```

Is producing diagram:

classDiagram
    Animal <|-- Dog
    Animal <|-- Cat
    User "1" --> "*" Order
    Order *-- OrderItem

Class diagrams can become noisy fast. In a blog post, prefer a small domain slice over a full application model.

State Diagram Syntax

State diagrams explain how something changes over time.

this code:

```mermaid
stateDiagram-v2
    [*] --> Draft
    Draft --> Review: submit
    Review --> Published: approve
    Review --> Draft: request changes
    Published --> Archived: archive
    Archived --> [*]
```

Is producing diagram:

stateDiagram-v2
    [*] --> Draft
    Draft --> Review: submit
    Review --> Published: approve
    Review --> Draft: request changes
    Published --> Archived: archive
    Archived --> [*]

Use state diagrams for:

• Order lifecycles
• Deployment states
• Authentication flows
• Background job status
• Content publishing workflows

State diagrams are underrated. They often explain business logic better than a long paragraph.

Entity Relationship Diagram Syntax

Entity relationship diagrams are useful for database models.

this code:

```mermaid
erDiagram
    USER ||--o{ ORDER : places
    ORDER ||--|{ ORDER_ITEM : contains
    PRODUCT ||--o{ ORDER_ITEM : appears_in

    USER {
        string id
        string email
    }

    ORDER {
        string id
        datetime created_at
    }

    PRODUCT {
        string id
        string name
    }
```

Is producing diagram:

erDiagram
    USER ||--o{ ORDER : places
    ORDER ||--|{ ORDER_ITEM : contains
    PRODUCT ||--o{ ORDER_ITEM : appears_in

    USER {
        string id
        string email
    }

    ORDER {
        string id
        datetime created_at
    }

    PRODUCT {
        string id
        string name
    }

ER Relationship Markers

||  exactly one
o|  zero or one
}|  one or more
}o  zero or more

ER diagrams are best when they explain relationships, not every column. Keep implementation details in migrations or schema docs.

Gantt Chart Syntax

Gantt charts are useful for project timelines.

this code:

```mermaid
gantt
    title Documentation Migration Plan
    dateFormat  YYYY-MM-DD

    section Planning
    Audit current docs      :a1, 2026-06-01, 5d
    Define structure        :a2, after a1, 3d

    section Writing
    Rewrite guides          :b1, after a2, 10d
    Review and publish      :b2, after b1, 4d
```

Is producing diagram:

gantt
    title Documentation Migration Plan
    dateFormat  YYYY-MM-DD

    section Planning
    Audit current docs      :a1, 2026-06-01, 5d
    Define structure        :a2, after a1, 3d

    section Writing
    Rewrite guides          :b1, after a2, 10d
    Review and publish      :b2, after b1, 4d

Gantt charts are helpful in internal planning posts, but they can age quickly. Use them when the timeline itself is the point.

Timeline Syntax

Timelines are good for release histories, incident writeups, and project summaries.

this code:

```mermaid
timeline
    title API Evolution
    2024 : REST API launched
    2025 : Webhooks added
    2026 : Event streaming introduced
```

Is producing diagram:

timeline
    title API Evolution
    2024 : REST API launched
    2025 : Webhooks added
    2026 : Event streaming introduced

Use a timeline when order matters more than dependency. If what you care about is the sequence of events rather than how they causally connect, a timeline keeps the focus where it belongs and stays easy to read at a glance.

Pie Chart Syntax

Pie charts are supported, but be careful. They are easy to read when there are only a few categories and the values are clearly different.

this code:

```mermaid
pie title Build Time by Step
    "Install dependencies" : 35
    "Run tests" : 45
    "Build assets" : 20
```

Is producing diagram:

pie title Build Time by Step
    "Install dependencies" : 35
    "Run tests" : 45
    "Build assets" : 20

Opinionated advice: if the values are close or there are more than five categories, use a table instead. A well-formatted table communicates precise numbers more honestly than a pie chart where the slices look nearly identical.

Git Graph Syntax

Git graphs can explain branching strategies and release flows.

this code:

```mermaid
gitGraph
    commit
    branch feature
    checkout feature
    commit
    commit
    checkout main
    merge feature
    commit
```

Is producing diagram:

gitGraph
    commit
    branch feature
    checkout feature
    commit
    commit
    checkout main
    merge feature
    commit

This is useful for articles about Git workflows, trunk-based development, release branches, and hotfixes. If you need a quick reference for the underlying branching commands, the GIT Cheatsheet covers the most common ones alongside merge and rebase workflows.

Mermaid Cheatsheet

Diagram Types

flowchart TD
sequenceDiagram
classDiagram
stateDiagram-v2
erDiagram
gantt
timeline
pie
gitGraph
mindmap
journey

Flowchart Basics

flowchart TD
A[Text] --> B[Text]
A -->|Label| B
A -.-> B
A ==> B
A --- B

Flowchart Shapes

A[Rectangle]
A(Rounded)
A{Decision}
A((Circle))
A[(Database)]
A[[Subroutine]]
A>Flag]

Sequence Diagram Basics

sequenceDiagram
participant A
participant B
A->>B: Message
B-->>A: Reply
activate B
deactivate B

Sequence Blocks

alt condition
else other condition
end

opt optional step
end

loop each item
end

par parallel task
and another task
end

Class Diagram Basics

classDiagram
class User
class Order
User --> Order
User "1" --> "*" Order

State Diagram Basics

stateDiagram-v2
[*] --> Idle
Idle --> Running
Running --> Done
Done --> [*]

ER Diagram Basics

erDiagram
USER ||--o{ ORDER : places
ORDER ||--|{ ORDER_ITEM : contains

Comments

Mermaid supports comments with %%.

this code:

```mermaid
flowchart TD
    %% This is a comment
    A --> B
```

Is producing diagram:

flowchart TD
    %% This is a comment
    A --> B

Using Mermaid in Hugo

Hugo content is usually written in Markdown, so Mermaid fits naturally into a Hugo-based technical blog. The exact setup depends on your theme and Markdown rendering configuration.

The common authoring pattern is still the same:

```mermaid
flowchart LR
    Markdown --> Hugo
    Hugo --> HTML
    HTML --> Browser
```

If your Hugo theme already supports Mermaid, this may render without extra work. If it does not, you usually need a render hook, shortcode, partial, or theme configuration that loads Mermaid on pages containing Mermaid diagrams.

A practical Hugo setup should aim for these rules:

• Keep Mermaid source inside normal Markdown articles.
• Load Mermaid only on pages that need it.
• Avoid global JavaScript if most pages do not use diagrams.
• Test diagrams during local preview.
• Keep the diagram source readable in Git.

For a technical blog, fenced code blocks are usually better than custom shortcodes because they are more portable. If you later move content to GitHub, another static site generator, or a documentation platform, standard fenced Mermaid blocks are easier to reuse.

Mermaid Best Practices

Keep Diagrams Small

A diagram should clarify the article, not replace it. If readers need to zoom, the diagram is probably too large.

Good diagrams usually have:

• One idea
• Clear direction
• Short labels
• Few crossing lines
• Consistent naming

Prefer Multiple Small Diagrams

Instead of one huge system diagram, use several focused diagrams:

• Request flow
• Deployment topology
• Data model
• State lifecycle
• Failure path

This is better for readers and better for mobile screens.

Use Stable Names

Use names that match your code, API, or documentation. Do not call the same thing API, Backend, and Server in different diagrams unless those are truly different concepts.

Label Important Arrows

Unlabeled arrows are fine for simple flowcharts. In system diagrams, labels often matter.

this code:

```mermaid
flowchart LR
    Web -->|HTTPS request| API
    API -->|SQL query| DB
    API -->|publish event| Queue
```

Is producing diagram:

flowchart LR
    Web -->|HTTPS request| API
    API -->|SQL query| DB
    API -->|publish event| Queue

Avoid Clever Syntax

Mermaid can do many things. That does not mean every article needs them. Favor syntax that a future maintainer can understand quickly.

Quote Labels When Needed

If a label contains characters that confuse Mermaid, wrap it in quotes.

this code:

```mermaid
flowchart TD
    A["User clicks /checkout"] --> B["POST /api/orders"]
```

Is producing diagram:

flowchart TD
    A["User clicks /checkout"] --> B["POST /api/orders"]

This is a small habit that prevents annoying rendering failures.

Think About Dark Mode

Many Hugo sites support dark mode. Make sure your Mermaid theme or site CSS keeps diagrams readable in both light and dark appearances.

Common Mermaid Mistakes

Mistake 1: Too Much Detail

Bad Mermaid diagrams often try to show every edge case. That makes them technically complete and practically unreadable. The fix is almost always the same: split the diagram into two or three smaller ones, each covering one concern, so readers can follow the logic without having to trace a dozen crossing arrows.

Mistake 2: Long Labels

Long labels create wide boxes and ugly layouts.

Instead of this code:

```mermaid
flowchart TD
    A[The user submits the registration form with their email address and password]
```

Is producing diagram:

flowchart TD
    A[The user submits the registration form with their email address and password]

Prefer this code:

```mermaid
flowchart TD
    A[Submit registration form]
```

Is producing diagram:

flowchart TD
    A[Submit registration form]

Explain details in the paragraph below the diagram.

Mistake 3: Unclear Direction

Pick a direction and stick with it. Most process diagrams should use TD. Most architecture diagrams are easier with LR.

Mistake 4: Treating Mermaid as a Design Tool

Mermaid is not Figma. It is not meant for pixel-perfect diagrams, and trying to force it into that role will only lead to frustration. Its strength is maintainability, not visual perfection — and that trade-off is intentional.

Mermaid SEO Tips for Technical Blogs

Mermaid diagrams can make technical articles more useful, but search engines still need text. Do not rely on diagrams alone.

For SEO-friendly Mermaid articles:

• Use descriptive H2 and H3 headings.
• Explain each diagram in nearby text.
• Include the important keywords in normal prose.
• Keep code examples copyable.
• Add alt-style explanation below complex diagrams.
• Use concise front matter title and description.
• Avoid hiding all meaning inside the rendered SVG.

A Mermaid diagram should support the article. It should not be the only place where important information exists.

Copy-Paste Mermaid Examples

API Request Flow

this code:

```mermaid
sequenceDiagram
    participant Client
    participant API
    participant Auth
    participant DB

    Client->>API: GET /account
    API->>Auth: Validate token
    Auth-->>API: Token valid
    API->>DB: Load account
    DB-->>API: Account data
    API-->>Client: 200 OK
```

Is producing diagram:

sequenceDiagram
    participant Client
    participant API
    participant Auth
    participant DB

    Client->>API: GET /account
    API->>Auth: Validate token
    Auth-->>API: Token valid
    API->>DB: Load account
    DB-->>API: Account data
    API-->>Client: 200 OK

CI Pipeline

this code:

```mermaid
flowchart TD
    A[Push commit] --> B[Install dependencies]
    B --> C[Run lint]
    C --> D[Run tests]
    D --> E[Build site]
    E --> F[Deploy]
```

Is producing diagram:

flowchart TD
    A[Push commit] --> B[Install dependencies]
    B --> C[Run lint]
    C --> D[Run tests]
    D --> E[Build site]
    E --> F[Deploy]

This pattern maps naturally to a real CI configuration. For the step-by-step syntax of GitHub Actions workflows, the GitHub Actions Cheatsheet is a handy companion when you want to turn the diagram above into a working pipeline.

Publishing Workflow

this code:

```mermaid
stateDiagram-v2
    [*] --> Draft
    Draft --> Editing
    Editing --> Review
    Review --> Published
    Review --> Editing
    Published --> [*]
```

Is producing diagram:

stateDiagram-v2
    [*] --> Draft
    Draft --> Editing
    Editing --> Review
    Review --> Published
    Review --> Editing
    Published --> [*]

Simple Data Model

this code:

```mermaid
erDiagram
    AUTHOR ||--o{ POST : writes
    POST ||--o{ COMMENT : receives

    AUTHOR {
        string id
        string name
    }

    POST {
        string id
        string title
        datetime published_at
    }

    COMMENT {
        string id
        string body
    }
```

Is producing diagram:

erDiagram
    AUTHOR ||--o{ POST : writes
    POST ||--o{ COMMENT : receives

    AUTHOR {
        string id
        string name
    }

    POST {
        string id
        string title
        datetime published_at
    }

    COMMENT {
        string id
        string body
    }

When Not to Use Mermaid

Do not use Mermaid when:

• The diagram needs precise visual layout.
• The design must match a brand system exactly.
• The visual is mostly decorative.
• The diagram has too many nodes to read.
• A screenshot would explain the point better.
• The content changes rarely and needs polish more than maintainability.

Mermaid is excellent for living technical documentation. It is less good for presentation-grade artwork. For document-quality diagrams in print or PDF contexts, LaTeX offers packages like TikZ and pgfplots that give you far greater layout control — the LaTeX Cheat Sheet covers diagram inclusion alongside the rest of the LaTeX toolkit.

Final Thoughts

Mermaid is one of the best tools for technical blogging because it respects how developers already work: text files, Markdown, Git, code review, and repeatable builds. For everything around the diagrams — headings, lists, tables, code blocks — the Markdown Cheatsheet is the quick-reference companion to keep alongside this guide.

The best Mermaid diagrams are not the most complex ones. They are the diagrams that make a concept obvious and remain easy to edit six months later.

Use Mermaid for the diagrams that should live with your documentation. Keep them small, keep them readable, and treat them as part of the source code of your article.