Mermaid Diagram Examples: 4 Patterns and How to Validate Them

Mermaid diagram examples are useful when a diagram needs an editable definition that can be reviewed and maintained as text. A release owner can document approval and change-freeze decisions in a flowchart, for example, then check that the source renders in the documentation platform where the team will publish it.

Choose a flowchart for branching process steps, a sequence diagram for messages in time order, an ER diagram for entities and relationships, or a Gantt chart for tasks and timing. The examples below are illustrative. They do not describe a particular organization’s policy, API, database, or project schedule.

This guide focuses on a practical question: what facts should you gather, what should the diagram decide or communicate, and how do you verify it before publication?

What Mermaid diagrams are, and what they are not

Mermaid is an open-source JavaScript diagramming project that turns text-based definitions into rendered diagrams. The definition is the editable source. The rendered diagram is its visual output. These are related but separate artifacts.

Keeping the definition with Markdown or code can make changes easier to review alongside other documentation. Mermaid is not a free-form, drag-and-drop canvas. Authors describe elements and relationships in syntax, while Mermaid determines the rendered layout. If stakeholders need direct manipulation or precise manual placement, a visual diagramming tool may fit better.

Choose the Mermaid diagram type by the question

Select a diagram by the relationship you need to explain, not by the team or software producing it. Mermaid also documents families such as mind maps, class diagrams, and Git graphs. The comparison below concentrates on four common documentation tasks.

Question	Diagram	Gather	Review gate
What decisions route a process?	Flowchart	Steps, decisions, outcomes	Process owner checks every branch
Which system sends each message, and when?	Sequence	Participants, order, responses	System owner checks the contract
Which entities relate, and with what cardinality?	ER diagram	Entities, keys, relationships	Data owner checks the schema
What work happens when, and in what order?	Gantt	Tasks, dates, dependencies	Schedule owner checks the plan

Four Mermaid diagram examples for documentation tasks

For each pattern, gather approved facts, adapt the labels or values, render the source, and have the accountable owner confirm the meaning. The AI role is deliberately limited because the examples depend on authoritative operational facts.

Trigger	AI role	Validation and action	Fallback
Release decision needs documenting	None required for a small decision tree	Release owner checks policy coverage, then publishes the reviewed source	Add an explicit exception path or hold publication
Login message order needs explaining	Format only supplied interactions, if used	API owner checks order, codes, and rejection behavior	Revise from the approved contract or design
Relational schema needs communicating	Do not infer keys or cardinality	Database owner compares entities and relationships with the schema	Correct the model or use a GUI tool for layout
Documentation rollout needs scheduling	Do not invent dates or durations	Project owner reconciles dependencies and calendar assumptions	Label it as planning illustration, not an approved schedule

1. Release approval flowchart

Question: Should a hypothetical production release be scheduled, held, or returned for more information? The decision inputs are approval status, an active change freeze, and the presence of a rollback plan.

flowchart TD
    A[Release request received] --> B{Approval recorded?}
    B -- No --> C[Return for approval]
    B -- Yes --> D{Change freeze active?}
    D -- Yes --> E[Hold until freeze ends]
    D -- No --> F{Rollback plan present?}
    F -- No --> G[Return for rollback plan]
    F -- Yes --> H[Schedule production deployment]

Illustrative input: production environment, approval recorded, no active freeze, and a rollback plan present. Under the depicted rules, the path ends at “Schedule production deployment.” That output is a diagrammed decision, not deployment authorization.

Validation detail: the release owner should test every input combination and decide whether emergency releases, maintenance windows, or additional approvals require separate branches. An omitted exception is a policy defect, not a rendering defect.

2. API authentication sequence diagram

Question: In what order do a client, API, and authentication service exchange messages during a hypothetical login? The branches distinguish successful validation from rejection.

sequenceDiagram
    participant C as Client
    participant A as API
    participant S as Authentication service
    C->>A: Submit credentials
    A->>S: Validate credentials
    alt Credentials valid
        S-->>A: Token issued
        A-->>C: 200 OK with token
    else Credentials invalid
        S-->>A: Rejected
        A-->>C: 401 Unauthorized
    end

Build this from an approved API contract or design, not from assumptions based on participant names. The API owner checks message order, response semantics, token handling, and the rejection path. Include a security reviewer when the diagram documents authentication or authorization behavior.

Failure to catch: the implemented service may return a different error response, issue tokens elsewhere, or add rate limiting. Compare each interaction with the actual contract and update the source rather than treating the example as a specification.

3. Relational data-model ER diagram

Question: How do customers, orders, order items, and products relate in a hypothetical relational schema? Each row represents one record in its respective table. Keys and relationships must be reconciled with the real schema.

erDiagram
    CUSTOMER ||--o{ ORDERS : places
    ORDERS ||--|{ ORDER_ITEM : contains
    PRODUCT ||--o{ ORDER_ITEM : appears_in

    CUSTOMER {
        int customer_id PK
        string email
    }
    ORDERS {
        int order_id PK
        int customer_id FK
    }
    ORDER_ITEM {
        int order_id PK, FK
        int product_id PK, FK
        int quantity
    }
    PRODUCT {
        int product_id PK
        string name
    }

The notation depicts one customer placing zero or more orders, one order containing one or more order items, and one product appearing in zero or more order items. The combined order and product keys illustrate a composite key. Confirm both choices against the approved model.

Failure to catch: if the real schema permits an order with no items, the mandatory order-to-item relationship is wrong. If a separate surrogate key exists for ORDER_ITEM, the key notation is also wrong. Do not infer keys or cardinality from table names alone.

4. Project timeline Gantt chart

Question: What is the order of work for a hypothetical documentation rollout? The dates and durations are illustrative planning values, not a forecast or approved delivery commitment.

gantt
    title Illustrative documentation rollout
    dateFormat YYYY-MM-DD
    section Preparation
    Confirm scope :scope, 2026-11-02, 3d
    Draft content :draft, after scope, 5d
    section Review
    Technical review :review, after draft, 2d

Build the chart from the current project plan, including calendar assumptions, task durations, and dependencies. The project owner checks whether “after scope” and “after draft” match the agreed schedule.

Failure to catch: a dependency can move a task later than a manually entered date suggests. Reconcile dependencies, working-day assumptions, and dates before describing the chart as an approved schedule.

Create, validate, and publish a Mermaid diagram

A successful preview in the Live Editor proves that the definition rendered there. It does not prove that the target publishing surface will render the same definition or that the represented facts are correct.

For maintained documentation, keep the Mermaid definition in version control with its related Markdown or source files. Treat an SVG or PNG as a rendered presentation artifact, not as the editable definition.

Where Mermaid rendering is documented

GitHub documents Mermaid fenced code blocks in supported contexts including Markdown files, Issues, Discussions, pull requests, and wikis. Check the exact location and syntax you intend to publish because support for one surface does not guarantee identical behavior in every feature or environment.

GitLab Flavored Markdown supports Mermaid blocks. GitLab’s documentation style guidance also notes that complex Mermaid layouts can become difficult to understand. Confirm the Mermaid version and supported syntax in the target GitLab environment.

ClickUp’s public Help Center documents Markdown insertion and code blocks, but the reviewed documentation does not confirm that Mermaid fences render as diagrams in ClickUp Docs. Test the actual workspace. If it displays source code, use a verified Mermaid-capable destination or an exported image.

Common rendering and maintenance failures

Mermaid definitions begin with a diagram-type declaration. Misspellings, unsupported syntax, or problematic words can prevent rendering. The official syntax reference notes that words such as end can cause problems in some contexts unless they are quoted. Start with a minimal definition, add elements gradually, and consult the syntax guidance for the selected diagram type.

Rendering depends on the Mermaid version, runtime, configuration, fonts, and host platform. Mermaid’s current documentation is version-sensitive, so avoid broad claims that a diagram will behave identically everywhere. Test the target environment directly and simplify or split a layout when readers cannot follow it.

AI can draft syntax from facts supplied by a human, but it should not invent policy branches, API behavior, keys, cardinality, dates, or dependencies. Render the result, compare it with approved facts, and obtain owner review before adoption.

Mermaid or a visual diagramming tool?

A hybrid approach can keep Mermaid source as the maintained definition and distribute an SVG or PNG to audiences whose platform does not render Mermaid. Choose based on who maintains the source, how much layout control is needed, and where the final diagram must render.

Teams designing broader documentation workflows may also consider ClickUp consulting. This service link does not imply that ClickUp Docs natively renders Mermaid. Verify the target workspace before making that assumption part of a publishing process.