How to Add Mermaid Diagrams to GitHub READMEs

GitHub renders Mermaid diagrams natively in Markdown files. No plugins, no image hosting, no build step — just write Mermaid syntax inside a code fence and GitHub turns it into a rendered diagram. This guide covers everything you need to embed diagrams in your READMEs.

Basic Syntax

Wrap your Mermaid code in a fenced code block with mermaid as the language identifier:

```mermaid
flowchart LR
    A[Clone repo] --> B[Install deps]
    B --> C[Run tests]
    C --> D[Submit PR]
```

GitHub renders this as an SVG diagram inline in the Markdown. It works in README.md, pull request descriptions, issue comments, wiki pages, and any .md file in a repository.

Supported Diagram Types

GitHub supports all standard Mermaid diagram types:

• Flowcharts (flowchart / graph)
• Sequence diagrams (sequenceDiagram)
• Class diagrams (classDiagram)
• State diagrams (stateDiagram-v2)
• ER diagrams (erDiagram)
• Gantt charts (gantt)
• Pie charts (pie)
• Mindmaps (mindmap)

For syntax examples of each type, see the Mermaid Syntax Cheat Sheet.

Practical Examples for READMEs

Architecture Overview

```mermaid
flowchart TD
    subgraph Client
        React[React App]
    end
    subgraph API Layer
        Vercel[Vercel Functions]
    end
    subgraph Services
        Supabase[(Supabase DB)]
        R2[Cloudflare R2]
        OpenAI[OpenAI API]
    end
    React --> Vercel
    Vercel --> Supabase
    Vercel --> R2
    Vercel --> OpenAI
```

This is one of the most valuable uses — a visual architecture diagram right at the top of your README that stays in sync with your code because it lives in the same repo.

Git Workflow

```mermaid
gitGraph
    commit id: "init"
    branch feature
    checkout feature
    commit id: "add login"
    commit id: "add tests"
    checkout main
    merge feature id: "merge feature"
    commit id: "release v1.0"
```

API Request Flow

```mermaid
sequenceDiagram
    participant User
    participant Frontend
    participant API
    participant DB

    User->>Frontend: Upload image
    Frontend->>API: POST /api/process-diagram
    API->>API: Validate & resize image
    API-->>Frontend: Mermaid code + diagram type
    Frontend-->>User: Rendered diagram
```

Common Pitfalls

1. Maximum Node Count

GitHub limits Mermaid diagrams to around 50-100 nodes (the exact limit varies). Very large diagrams will fail to render with a generic error. If your diagram is complex, split it into multiple smaller diagrams organized by subsystem.

2. Special Characters in Labels

Certain characters break Mermaid parsing inside GitHub code fences:

• Parentheses in labels — use quotes: A["Method(arg)"]
• HTML entities — GitHub's Markdown processor may interfere with & or <
• Emojis — generally work, but may cause alignment issues

3. Diagram Not Rendering

If your diagram shows as raw text instead of a rendered image:

• Check that the language identifier is exactly mermaid (lowercase, no space)
• Validate your syntax — a single typo prevents the entire diagram from rendering
• Check for invisible characters (copy-paste from some editors introduces zero-width spaces)
• Try in a fresh Markdown file to isolate the issue

4. Dark Mode Compatibility

GitHub automatically adjusts Mermaid diagram colors for light and dark themes. However, if you use custom styling (style directives), test in both modes. Avoid hardcoding colors that become invisible in one theme.

When to Use PNG Instead

GitHub's native Mermaid rendering covers most cases, but sometimes you need a PNG image:

• npm READMEs — npmjs.com doesn't render Mermaid code fences
• External documentation — Confluence, Google Docs, and many wikis need images
• Presentations — slides typically need static images
• Very large diagrams — that exceed GitHub's rendering limits

For these cases, use the Mermaid to PNG tool to export your diagram as an image, then reference it with a standard Markdown image tag.

Tips for Clean README Diagrams

• Keep diagrams small and focused — one concept per diagram
• Use LR direction for wide screens (README context), TD for narrow
• Label clearly — diagram readers shouldn't need to read surrounding text to understand it
• Place diagrams near the top — architecture diagrams in particular help new contributors orient quickly
• Add a text caption above — a one-line description helps accessibility and context

Try It Yourself

Already have architecture diagrams as images? Convert them to editable Mermaid code you can paste directly into your README. Try ImageToMermaid free.