How to Add Mermaid Diagrams to a GitHub README

GitHub renders Mermaid diagrams natively inside fenced code blocks. There's no build step, no image to commit, and no external service to configure. You write a few lines of text, fence them with ```mermaid, and GitHub turns them into an SVG when the page loads.

This guide covers the exact syntax, the places it works (and the few where it doesn't), and how to handle dark mode and platforms without native support.

The minimum example

Open any README.md and paste this. Commit, view on github.com, and you'll see a rendered flowchart.

```mermaid
flowchart LR
    A[User] --> B[App]
    B --> C[(Database)]
    B --> D{Cache hit?}
    D -- Yes --> E[Return cached]
    D -- No --> C
```

The triple backticks open and close the block, the word mermaid tells GitHub which renderer to use, and everything between is Mermaid source. That's the whole integration.

Where it works on GitHub

Native Mermaid rendering is enabled across the entire GitHub product:

• READMEs in any repo, public or private.
• Issues and pull requests — including comments and the description body.
• Markdown files (.md, .mdx) rendered through the GitHub web UI.
• Wikis and discussions.
• Gists.

It does not render in raw views (raw.githubusercontent.com), in mirrors that strip GitHub's renderer, or on social-media previews. For those, use a pre-rendered image — covered below.

Dark mode handling

Mermaid on GitHub auto-detects the reader's theme via prefers-color-scheme. The same diagram block produces a light SVG in light mode and a dark SVG in dark mode without any source changes.

If you want explicit control, use Mermaid's %%{init}%% directive at the top of the block:

%%{init: {'theme':'dark'}}%%
flowchart LR
    A[User] --> B[App]
    B --> C[(Database)]

Available theme values: default, dark, forest, neutral, base. For finer control (specific colors, fonts), see the Mermaid theming docs .

Common gotchas

The fence language must be exact

GitHub only renders blocks fenced with the literal word mermaid (lowercase). Variants like Mermaid, mmd, or diagram all fall through to plain text.

Special characters in labels

Parentheses, brackets, and quotes inside node labels need escaping or quoting:

flowchart TD
    A["Step 1 (init)"] --> B["Step 2: validate"]
    B --> C["Done!"]

Diagrams that span the page

GitHub renders Mermaid inside the standard markdown column width. Wide diagrams overflow with a horizontal scrollbar. Two ways to fix:

• Switch flowchart direction from LR (left-right) to TD (top-down) — usually narrower.
• Group nodes into subgraph blocks. Subgraphs wrap when space is tight.

Pre-rendered fallback for non-GitHub places

Mermaid only renders where a Mermaid renderer is available. For places that don't have one — Bitbucket, social-media link previews, plain markdown viewers, PDFs, slides — pre-render to SVG or PNG and embed as an image.

The fastest way:

1. Paste your Mermaid into MermanDraw.
2. Pick a theme (Clean works on most backgrounds).
3. Click Export → SVG or Export → PNG.
4. Commit the file and reference it with normal markdown image syntax.

![Architecture diagram](./docs/architecture.svg)

SVG keeps the diagram crisp at any zoom; PNG is safer for places that don't accept SVG (some chat apps, older readers).

One more example: a sequence diagram for an API flow

Sequence diagrams document API calls better than prose. Drop this in any PR description and reviewers see exactly which services talk to which.

sequenceDiagram
    participant C as Client
    participant API as API Gateway
    participant S as Service
    participant DB as Database
    C->>API: POST /orders
    API->>S: validate(order)
    S->>DB: SELECT inventory
    DB-->>S: stock count
    S-->>API: 200 OK
    API-->>C: { id, status }

FAQ

Related

• Mermaid Cheatsheet — every diagram type with a copy-paste example.
• How to generate Mermaid diagrams with ChatGPT and Claude