Mermaid: Network Diagrams in Code

toolsdiagramsdocumentation

Mermaid lets you create diagrams using plain text. No more wrestling with Visio, Lucidchart, or drag-and-drop editors that produce unmaintainable binary files.

Why Text-Based Diagrams Win

• Version control friendly — diffs show exactly what changed
• Lives with your code — diagrams stay in sync with the system they describe
• No context switching — write diagrams in the same editor as your code
• AI-friendly — LLMs can generate and modify diagrams easily

Network Diagram Example

graph LR
    Internet((Internet)) --> LB[Load Balancer]
    LB --> Web1[Web Server 1]
    LB --> Web2[Web Server 2]
    Web1 --> DB[(Database)]
    Web2 --> DB
    Web1 --> Cache[(Redis)]
    Web2 --> Cache

This renders as a clear left-to-right network topology showing traffic flow from the internet through a load balancer to web servers, with shared database and cache backends.

More Than Just Flowcharts

Mermaid supports:

• Sequence diagrams — API call flows, authentication sequences
• Class diagrams — object relationships
• State diagrams — state machines
• Entity-relationship diagrams — database schemas
• Gantt charts — project timelines
• Git graphs — branch visualization

Where It Works

Mermaid renders natively in:

• GitHub (README, issues, PRs, wikis)
• GitLab
• Notion
• Obsidian
• VS Code (with extensions)
• Most documentation tools (Docusaurus, MkDocs, etc.)

The Mental Shift

Traditional diagramming tools optimize for visual editing. Mermaid optimizes for describing relationships. You think about what connects to what, not where boxes should be positioned.

The layout engine handles placement automatically. Sometimes it’s not perfect, but for documentation purposes, clarity beats pixel-perfect positioning.

Getting Started

Drop this into any GitHub markdown file:

```mermaid
graph TD
    A[Start] --> B{Decision}
    B -->|Yes| C[Do Thing]
    B -->|No| D[Other Thing]
```

That’s it. No setup, no accounts, no exports. Your diagram lives as text, renders as graphics, and stays maintainable forever.