How to Use Mermaid Diagrams in GitHub Markdown

GitHub renders Mermaid natively. Any fenced code block marked mermaid in a Markdown file, issue, pull request, discussion or wiki page is displayed as a diagram — no images to upload and nothing to keep in sync.

The basic syntax

```mermaid
flowchart LR
    Dev --> PR[Pull request] --> Review --> Merge
```

That's it. When you view the file on GitHub, the block is replaced with the rendered diagram, and readers can pan, zoom or view the source.

A faster workflow

1. Draft the diagram in the MermaidViewer editor with instant preview and error messages.
2. Click Copy → Markdown to get the code already wrapped in a ```mermaid block.
3. Paste into your README and commit.

Previewing outside GitHub saves you from commit-and-check loops when there's a syntax error.

Dark mode

GitHub automatically applies a dark Mermaid theme for readers using dark mode. Avoid hard-coding light background colors in classDef styles, or text may become unreadable in dark mode. Prefer theme-neutral styles or test both modes in the editor using the light/dark toggle.

Limitations to know

• GitHub may run a slightly older Mermaid version than the latest release, so the newest beta diagram types can fail to render.
• Interactive features like click callbacks and tooltips are disabled for security.
• Very large diagrams can time out — split them into smaller ones.

GitLab, Bitbucket and others

GitLab supports the same ```mermaid blocks. Bitbucket Cloud does not render Mermaid natively; export an SVG or PNG from MermaidViewer and commit the image, or link to a share URL.