Mermaid Diagrams in GitHub
GitHub natively renders Mermaid diagrams in markdown files, issues, pull requests, discussions, and wikis. No plugins or extensions needed — just wrap your Mermaid code in a fenced code block with the 'mermaid' language identifier.
Step-by-Step Guide
Add a Mermaid block to any markdown file
Wrap your Mermaid code in triple backticks with 'mermaid' as the language. GitHub renders it as an SVG diagram inline.
```mermaid
flowchart TD
A[Start] --> B{Decision}
B -->|Yes| C[Do something]
B -->|No| D[Do something else]
```Use in README.md
Diagrams in your README render on the repository homepage. Perfect for architecture overviews, data flows, and API documentation.
```mermaid
erDiagram
USER ||--o{ ORDER : places
ORDER ||--|{ LINE_ITEM : contains
USER {
uuid id PK
string email UK
}
ORDER {
uuid id PK
uuid user_id FK
}
```Use in issues and pull requests
Add diagrams to issue descriptions and PR bodies to explain changes visually. Reviewers can see the architecture alongside the code diff.
```mermaid
sequenceDiagram
Client->>API: POST /login
API->>DB: Check credentials
DB-->>API: User found
API-->>Client: JWT token
```Design in our editor, paste into GitHub
Design your diagram in the Mermaid Editor with live preview and theming, then copy the code and paste it into your GitHub markdown wrapped in a mermaid fence. The diagram renders identically.
Tips
- •GitHub renders diagrams with a light background — design with light theme in mind
- •GitHub wikis also support Mermaid — great for project documentation
- •Use the 'Share' button in our editor to generate a link back to the editable diagram
- •GitHub has a max diagram size — very complex diagrams may not render
Design Your Diagram First
Use our editor with live preview, autocomplete, and theming — then copy-paste into GitHub.
Open Editor