Mermaid Diagrams Document Architecture in Markdown Without Clicking Anything

Your architecture diagram was accurate when you drew it. That was three sprints ago. Now it lives in a shared Google Slide nobody updates, and the engineer who built the service it describes has since moved teams. Sound familiar?

Mermaid diagrams flip this problem on its head. Instead of a drag-and-drop canvas that lives outside your codebase, you write diagrams as text — plain Markdown-style syntax that sits in your README, gets version-controlled with your code, and renders wherever Markdown renders. When the architecture changes, you change one text file. The diff tells the whole story.

What Mermaid Is (and Why Diagrams as Code Matter)

Mermaid is an open-source diagramming language that renders diagrams from plain text. You write a flowchart in a fenced code block; a renderer (or a Mermaid-aware viewer) turns it into an SVG diagram. No accounts, no export steps, no “the diagram format isn’t supported on this machine.”

The “diagrams as code” approach earns its keep in a few concrete ways:

• Version control — diagrams live in Git. You can diff them, revert them, and attach them to the same PR as the code they describe.
• No vendor lock-in — plain text is portable. Switch renderer, fork the repo, export to Confluence — the source is always readable.
• Always close to the code — a diagram in the same repo as the service it describes is far more likely to stay accurate than one in a shared slide deck.
• Automation-friendly — you can generate Mermaid syntax from code (database schemas, API specs, CI pipelines) using scripts or LLMs.

Before diving into diagram types, you can preview any Mermaid syntax instantly — no local setup — using the Mermaid Diagram Renderer on iotools.cloud. Paste, see the result, iterate. Use it alongside this guide to run every example live.

Flowcharts: The Workhorse

Flowcharts are the most common Mermaid diagram type, and for good reason — they handle everything from simple decision trees to complex multi-service flows. Here’s the syntax that covers 90% of real use cases:

flowchart TD
    A[User submits form] --> B{Validation passes?}
    B -- Yes --> C[Save to database]
    B -- No --> D[Return error to client]
    C --> E[Send confirmation email]
    E --> F([End])

A few things worth knowing about flowchart syntax:

• 方向: TD (top-down), LR (left-right), BT (bottom-top), RL (right-left)
• Node shapes: [rectangle], (rounded), ([stadium]), {diamond}, ((circle)), [(cylinder)]
• Edge labels: -- label --> 或 -->|label|
• Subgraphs: group related nodes visually

Subgraphs are especially useful for showing service boundaries:

flowchart LR
    subgraph Frontend
        UI[React App]
    end
    subgraph Backend
        API[FastAPI]
        DB[(PostgreSQL)]
    end
    UI --> API
    API --> DB

Sequence Diagrams: Showing API Call Flows

Sequence diagrams are the right tool when you need to show the order of interactions between systems — an API call chain, an auth flow, a webhook sequence. They make timing and responsibility clear in a way a flowchart can’t.

sequenceDiagram
    participant Client
    participant API Gateway
    participant Auth Service
    participant Users DB

    Client->>API Gateway: POST /login {email, password}
    API Gateway->>Auth Service: Validate credentials
    Auth Service->>Users DB: SELECT user WHERE email=?
    Users DB-->>Auth Service: User record
    Auth Service-->>API Gateway: JWT token
    API Gateway-->>Client: 200 OK {token}

Solid arrows (->>) are requests; dashed arrows (-->>) are responses. The participant declarations control the order boxes appear at the top of the diagram. You can also use actor for human participants, activate/deactivate to show processing time, and loop 或 alt blocks for conditional flows.

Entity-Relationship Diagrams: Database Schemas in Documentation

ER diagrams belong in every service’s README that owns a database schema. Mermaid’s ER syntax is clean and covers cardinality out of the box:

erDiagram
    USER {
        int id PK
        string email
        string name
        timestamp created_at
    }
    ORDER {
        int id PK
        int user_id FK
        decimal total
        string status
    }
    ORDER_ITEM {
        int id PK
        int order_id FK
        int product_id FK
        int quantity
    }
    USER ||--o{ ORDER : "places"
    ORDER ||--|{ ORDER_ITEM : "contains"

Cardinality notation: || is exactly one, o| is zero or one, o{ is zero or many, |{ is one or many. The relationship label (“places”, “contains”) goes in quotes at the end.

State Diagrams: Modeling Workflows and State Machines

Any time you have an entity that moves through distinct states — an order, a subscription, a CI job — a state diagram is more precise than a flowchart. Mermaid’s state diagram syntax maps directly to how you’d define a state machine in code:

stateDiagram-v2
    [*] --> Pending
    Pending --> Processing : payment received
    Processing --> Shipped : warehouse picks order
    Shipped --> Delivered : carrier confirms
    Shipped --> Returned : customer initiates return
    Delivered --> [*]
    Returned --> Refunded : refund processed
    Refunded --> [*]

[*] marks the start and end states. Transitions carry the event that triggers them. You can nest states for composite states and use note blocks to annotate transitions with additional context.

Class Diagrams: OOP Structures for Onboarding Docs

Class diagrams are most useful when onboarding engineers to an object-oriented codebase or documenting a domain model. Mermaid covers inheritance, interfaces, composition, and method signatures:

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

Visibility modifiers follow UML convention: + public, - private, # protected. Relationship arrows cover association (-->), inheritance (<|--), composition (*--), and aggregation (o--).

Where Mermaid Renders Natively

The real selling point of Mermaid is its native support across the tools developers already use:

• GitHub — Mermaid fenced code blocks (```mermaid) render in READMEs, issues, pull request descriptions, and wikis as of 2022.
• GitLab — native Mermaid support in Markdown files and wiki pages.
• Notion — paste a Mermaid code block into a code block set to "Mermaid" and it renders inline.
• Visual Studio Code — the Markdown Preview Mermaid Support extension renders diagrams in the built-in preview pane.
• Obsidian — Mermaid renders natively without any plugin.
• Docusaurus, MkDocs, Astro — Mermaid plugins exist for all major static site generators.
• Confluence — via the Mermaid Diagrams for Confluence app.

If you're writing documentation that will land in GitHub or GitLab, Mermaid diagrams work out of the box with zero configuration.

Pitfalls and When to Use Something Else

Mermaid isn't perfect for every situation. A few things to watch for:

• Complex layouts — Mermaid's auto-layout algorithm doesn't always produce clean results for large graphs. If you have 50+ nodes with many crossing edges, you may need to restructure or split diagrams manually.
• Confluence rendering — native Confluence doesn't support Mermaid; you need a paid app. If your team lives in Confluence, budget for this or use draw.io instead.
• Non-standard diagram types — network diagrams, deployment diagrams, and C4 architecture diagrams require workarounds or aren't well-supported.
• Styling control — Mermaid's theming options are limited. For branded diagrams with custom colors and fonts, you'll spend time fighting the renderer.

The main alternatives worth knowing:

• PlantUML — older, more verbose syntax, but richer UML support and better Confluence integration. Requires Java locally or a server-side renderer.
• D2 — newer diagrams-as-code tool with cleaner layout control and better handling of large diagrams. Less ecosystem adoption than Mermaid, but growing fast.
• draw.io / Excalidraw — GUI tools for when you need precise visual control and don't mind the diagram living outside version control.

For most developer documentation — service READMEs, API flows, onboarding guides — Mermaid covers the use case well and the native GitHub support alone makes it worth the learning curve.

Preview Mermaid Without Installing Anything

If you're experimenting with syntax or want to share a diagram with someone who doesn't have a local renderer set up, the Mermaid Diagram Renderer on iotools.cloud gives you a live preview with no sign-up, no installation, and no configuration. Paste your Mermaid code, see the rendered diagram, and copy the output.

It's useful for checking diagram syntax before committing, sharing a rendered version in a Slack message, or prototyping a diagram you'll later paste into a README.

Start With a Flowchart

If you've never written a Mermaid diagram, start with a flowchart. Pick a process in your codebase you've been meaning to document — a request lifecycle, a background job, a deploy pipeline — and write it out in Mermaid syntax in the next 10 minutes. Paste it into your README in a ```mermaid block and push it. GitHub will render it automatically.

That one diagram, version-controlled and living next to the code it describes, is worth more than a slide deck that nobody trusts.

你可能也会喜欢