← All Articles

How to Use Mermaid Diagrams in GitHub README Files

Add diagrams to your GitHub README with native Mermaid support. Learn syntax, tips for rendering, common issues, and best practices for documentation.

GitHub Supports Mermaid Natively

Since February 2022, GitHub renders Mermaid diagrams directly in Markdown files. No plugins, no extensions, no build steps — just wrap your Mermaid code in a mermaid code fence and GitHub does the rest.

This is a game-changer for documentation. Instead of maintaining separate image files that go stale, your diagrams live as text in your repo and render automatically.

Basic Usage

Add a Mermaid diagram to any Markdown file (.md) by using a code fence with the mermaid language identifier:

graph LR

A[User] --> B[Frontend]

B --> C[API]

C --> D[(Database)]

GitHub will render this as an interactive SVG diagram instead of showing the raw text.

Where It Works

Mermaid rendering works in:

  • README.md and all Markdown files
  • Issues and Pull Requests (description and comments)
  • Discussions
  • Wikis
  • Gist files (with .md extension)

Common Diagram Types for READMEs

Architecture Overview

Every project should have an architecture diagram. Here's a typical web app:

graph TB

subgraph Client

React[React SPA]

end

subgraph Server

API[Express API]

Auth[Auth Middleware]

Cache[Redis Cache]

end

subgraph Data

DB[(PostgreSQL)]

S3[S3 Storage]

end

React -->|HTTPS| API

API --> Auth

API --> Cache

API --> DB

API --> S3

Contribution Workflow

Help contributors understand your process:

graph TD

Fork([Fork the repo]) --> Clone[Clone locally]

Clone --> Branch[Create feature branch]

Branch --> Code[Make changes]

Code --> Test[Run tests]

Test --> Commit[Commit changes]

Commit --> Push[Push to fork]

Push --> PR[Open Pull Request]

PR --> Review{Code review}

Review -->|Approved| Merge[Merge to main]

Review -->|Changes requested| Code

API Flow Documentation

Document your API interactions:

sequenceDiagram

participant Client

participant Gateway as API Gateway

participant Auth as Auth Service

participant User as User Service

Client->>Gateway: POST /api/login

Gateway->>Auth: Validate credentials

Auth->>User: Get user profile

User-->>Auth: User data

Auth-->>Gateway: JWT token

Gateway-->>Client: 200 OK + token

Database Schema

Document your data model:

erDiagram

USER ||--o{ POST : creates

USER ||--o{ COMMENT : writes

POST ||--o{ COMMENT : has

POST ||--o{ TAG : tagged_with

USER {

int id PK

string username

string email

datetime created_at

}

POST {

int id PK

string title

text content

int author_id FK

datetime published_at

}

Project Roadmap

Show your planned timeline:

gantt

title Project Roadmap 2025

dateFormat YYYY-MM-DD

axisFormat %b

section v1.0

Core features :done, 2025-01-01, 2025-03-01

Beta release :milestone, 2025-03-01, 0d

section v1.1

User feedback :active, 2025-03-01, 2025-04-01

Bug fixes :2025-04-01, 2025-04-15

v1.1 release :milestone, 2025-04-15, 0d

section v2.0

New features :2025-05-01, 2025-08-01

v2.0 release :milestone, 2025-08-01, 0d

Best Practices for GitHub READMEs

1. Keep Diagrams Simple

GitHub's Mermaid renderer handles most features, but very complex diagrams with 50+ nodes can be slow to render or hard to read on small screens. Split complex systems into multiple focused diagrams.

2. Test Before Pushing

Use a live editor to verify your diagram renders correctly before committing. GitHub's renderer occasionally has quirks with newer Mermaid features since it may not run the latest version.

3. Provide Alt Text for Accessibility

Unfortunately, GitHub doesn't support alt text for Mermaid diagrams directly. Consider adding a text description below complex diagrams:

graph LR

A --> B --> C


*The diagram shows data flowing from component A through B to C.*

4. Use Consistent Direction

Pick a direction (TD or LR) and stick with it throughout your README. Mixing directions is visually jarring.

5. Place Diagrams Strategically

  • Top of README: Architecture overview
  • After setup instructions: How the system works
  • In CONTRIBUTING.md: Contribution workflow
  • In docs/ folder: Detailed technical docs

6. Fallback for Non-GitHub Platforms

If your README might be viewed outside GitHub (npm, PyPI, etc.), platforms that don't support Mermaid will show the raw code. This is acceptable — the text is still human-readable.

Alternatively, render to an image and include both:

<!-- Rendered diagram (for platforms without Mermaid support) -->
![Architecture](./docs/architecture.png)

<!-- Mermaid source (for GitHub and supporting platforms) -->
<details>
<summary>Diagram source</summary>

graph TD

A --> B


</details>

Common Issues and Fixes

Diagram Shows as Raw Text

Cause: The code fence language must be exactly mermaid (lowercase). Mermaid or MERMAID won't work.

Syntax Errors

Cause: A typo in the Mermaid syntax. GitHub shows a red error message instead of the diagram.

Fix: Test in a live editor first, then copy the working code.

Special Characters Breaking the Diagram

Cause: Characters like <, >, &, or quotes can interfere with rendering.

Fix: Wrap labels in double quotes: A["Label with (special) chars"]

Diagram Too Wide or Cramped

Cause: GitHub's rendering area is fixed-width.

Fix: Use TD (top-down) direction for wide diagrams, or split into smaller diagrams.

Old Mermaid Features Not Working

Cause: GitHub may run an older version of Mermaid than the latest release.

Fix: Stick to well-established features. Check the Mermaid changelog if something doesn't render.

Advanced: Mermaid in GitHub Actions

You can automatically render Mermaid diagrams to images in CI:

name: Render Diagrams
on: [push]
jobs:
  render:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Render Mermaid
        uses: mermaid-js/mermaid-cli-action@v1
        with:
          input: docs/diagrams/
          output: docs/images/

This generates PNG/SVG files from your .mmd files, useful for platforms that don't support Mermaid natively.

Real README Example

Here's how a well-structured README uses diagrams:

# My Awesome API

A RESTful API for managing tasks.

## Architecture

graph TB

Client[Client Apps] --> LB[Load Balancer]

LB --> API1[API Server 1]

LB --> API2[API Server 2]

API1 & API2 --> DB[(PostgreSQL)]

API1 & API2 --> Cache[(Redis)]


## Getting Started
...

## API Endpoints

### Authentication Flow

sequenceDiagram

Client->>API: POST /auth/login

API-->>Client: JWT Token

Client->>API: GET /tasks (Bearer token)

API-->>Client: Task list

Conclusion

Mermaid in GitHub READMEs is one of the most impactful documentation improvements you can make. Diagrams that live as code stay current, are version-controlled, and render beautifully without any extra tooling. Start with an architecture diagram in your main README, then expand to contribution guides, API docs, and database schemas.

Try it now in our free Mermaid Live Editor →

Try it now in our free Mermaid Live Editor →
← All Articles