Mermaid: Code‑Based Diagramming, the Ultimate Solution for Technical Docs in the AI Era

Mermaid implements the "Diagrams as Code" paradigm: diagram definitions are plain‑text blocks embedded in Markdown, enabling version‑control diffs.

Key advantages

Git‑friendly – source is text, so git diff shows exact changes.

AI‑native – large language models (Claude, GPT‑4, Cursor) can output Mermaid syntax from natural‑language prompts.

Zero tool switching – diagrams render directly in VS Code, Obsidian, GitHub, GitLab, Notion, etc.

As of June 2026 Mermaid has >88 000 GitHub stars, 6.4 M weekly npm downloads and native integration in GitHub, GitLab, Notion, Obsidian, and VS Code. Version v11.15 supports more than 20 chart types.

Core syntax overview

Flowchart (process diagram)

flowchart LR
    A[Rectangle] --> B(Rounded)
    B --> C{Decision}
    C --> D[(Database)]
    C --> E[[Subroutine]]
    C --> F([Stadium])
    subgraph Frontend Layer
        A
        B
    end
    subgraph Data Layer
        D
    end

State diagram

stateDiagram-v2
    [*] --> Pending
    Pending --> Paid : payment success
    Pending --> Cancelled : timeout / user cancel
    Paid --> Shipped : warehouse dispatch
    Shipped --> Completed : user receipt
    Shipped --> Return : return request
    Return --> Refunded : refund processed
    Completed --> [*]
    Cancelled --> [*]
    Refunded --> [*]

Sequence diagram

sequenceDiagram
    participant U as User
    participant F as Frontend
    participant A as API Gateway
    participant S as Auth Service
    participant D as Database
    U->>F: enter credentials
    F->>A: POST /api/login
    A->>S: forward auth request
    S->>D: SELECT user WHERE email=?
    D-->>S: return record
    S-->>A: JWT token
    A-->>F: 200 OK + token
    F-->>U: redirect home
    alt token expired
        F->>A: POST /api/refresh
        A-->>F: new token
    else verification failed
        A-->>F: 401 Unauthorized
    end

Other chart families include class diagrams, ER diagrams, XY charts (line, bar, pie, Sankey, radar, treemap), Gantt, Timeline, GitGraph, Kanban, Block diagram, Architecture diagram, Quadrant chart, and Mindmap. Each family provides a concise cheat sheet for node shapes, arrow styles, relationship symbols, layout directives, and version‑specific flags (e.g., innerHole for ring charts).

Installation & environment

VS Code – install the "Mermaid" extension and preview .md files with Ctrl+Shift+V.

Obsidian – native support; write a ```mermaid block.

GitHub – any Markdown region (README, Issue, PR, Wiki) renders Mermaid automatically.

Online Playground – use mermaid.live to edit and export SVG/PNG/PDF.

AI‑driven diagram generation

Because diagrams are text, an LLM can generate a complete flowchart definition from a natural‑language description. The article demonstrates a full micro‑service e‑commerce architecture generated this way and pasted into a document for instant rendering.

Common pitfalls & optimizations

Chinese characters not displayed – add an init block to set fontFamily to a font that includes CJK glyphs.

Complex layout spaghetti – switch direction ( flowchart LR), install the @mermaid-js/layout-elk plugin, or split the diagram with subgraph sections.

Dark‑mode readability – set theme: 'dark' or use the neutral base theme.

ER diagram field‑type conflicts – avoid the u (unique) token in versions < v11.13; upgrade to resolve.

CI/CD integration & advanced use cases

Install the CLI package @mermaid-js/mermaid-cli (npm) to convert .mmd files to SVG in build scripts:

npm install -g @mermaid-js/mermaid-cli
mmdc -i diagram.mmd -o diagram.svg -t dark

Combine with LangGraph: use a State Diagram to model agent workflows, where each node represents an LLM or tool and edges encode trigger conditions. Mermaid is currently the only tool that renders such agent graphs directly from repository files.

Mermaid lets engineers keep documentation and diagrams together in a single source file, provides exact version control, works seamlessly with AI assistants, and covers a comprehensive set of diagram types.