Skip to content
MermaidViewer

Mermaid in GitHub

Use mermaid in GitHub READMEs, issues, pull requests and wikis. Fence syntax, dark mode, and the limits of GitHub's renderer.

By MermaidViewer editorsPublished Updated

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

markdown
```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.

README, issues, and the wiki

The fence is the same in a file, a comment, and a wiki page, so the useful part of mermaid in github is where the source lives and how links behave around it.

A diagram in README.md, or in any other Markdown file in the repository, is a normal blob. It has history, it shows up in the diff, and the rendered view on the repository home is whatever is on the default branch. Edit the text, commit, and the picture moves with the code it describes. That is the right home for a diagram that should stay true next month.

A diagram in an issue or a pull request lives in the conversation. The fence is identical, and GitHub's renderer is the same build, so a syntax error looks the same as it does on the README. The difference is lifetime. Closing the issue doesn't update a file. Editing the comment later doesn't show up in git log for the code. Use an issue diagram when you are proposing a flow, sketching a bug, or giving a reviewer a picture of the change. When the team agrees, copy the text into a file in the repo. Otherwise the agreed design sits in a comment nobody opens.

The wiki is a separate Git repository. GitHub renders the same mermaid fence there, and the page still isn't the code repo. A relative link that is correct beside README.md does not point at the code when you paste it into a wiki page. Link from the wiki to a file with a full https://github.com/.../blob/... URL. Link from one wiki page to another with the wiki's own page links. Treat the wiki as a place for a narrative that can drift, and treat the repo file as the source of truth when the diagram describes the system you ship.

Discussions use the fence too. They behave like issues: good for a thread, poor as the only copy.

GitHub turns off click callbacks inside the rendered SVG. A click line in the diagram text won't navigate. Put the links in the Markdown around the fence, where GitHub's normal link rules apply.

In a file in the repo, a relative link is resolved from that file's directory. A README at the repository root can point at [the auth notes](docs/auth.md) and [the deploy chart](docs/deploy.md). A diagram that lives in docs/deploy.md should use [the README](../README.md) and [the runbook](runbook.md). These links keep working for someone who cloned the repo and opened the file, which an absolute URL to github.com does not always do.

Write the link in the paragraph above the diagram or in a short list under it. "This chart is the charge path. Details are in the API doc." Readers see the picture and a way forward. They don't have to know that the SVG itself is inert.

In an issue, a pull request body, or a wiki page, prefer a full URL to a file on GitHub. A relative path that is correct next to the README is easy to mis-resolve from a comment, because the comment is not that directory, and the wiki is not that repository. Paste the blob link you get from the address bar, including the branch or the commit if the review is about a specific revision. A link to the default branch will move on after the next merge, which is what you want for a living doc and the wrong thing for a review of an old pull request.

Image links follow the same split. If you commit an SVG fallback next to the README, [the deploy diagram](docs/images/deploy.svg) from a file in docs/ is images/deploy.svg. From an issue, use the raw URL GitHub gives you for that file. Alt text still matters: ![Deploy pipeline from commit to canary](docs/images/deploy.svg). The words in the alt text are what a screen reader gets when the SVG is loaded as an image.

Don't point a relative link at a heading inside the SVG. Point it at a heading in the Markdown. If the diagram illustrates "Rollback", add a ## Rollback section under the fence and link to that.

Reviewing a diagram in a pull request

Review the text in the diff. Mermaid's layout owns spacing, rank, and where a line bends. A review comment that asks to "move the database box left" asks the author to fight the renderer. A comment that asks to rename DB to the real cluster name, or to add the failure edge the code actually has, is a review.

Read the pull request in this order.

  1. Does the fence say mermaid, lowercase, and does the preview render? If the preview shows the raw code, the syntax error is the first comment. Paste the block into the editor if GitHub's message is vague. The syntax guide covers the usual line-level causes.
  2. Do the ids and labels match the code in the same pull request? A box named Billing while the service was renamed to Charges is a defect, the same as a stale comment.
  3. Is the unhappy path there? Happy-path diagrams get approved too quickly. Ask what happens on timeout, decline, or a failed health check if the code handles those.
  4. Is this one scenario? A pull request that redraws the entire platform in one block is hard to review and easy to get wrong. Ask for a split, with a sentence between the fences.
  5. If the change is behavior, ask the author to paste the updated diagram in the pull request body as well as in the file. Reviewers see it without opening the diff. The file remains the copy that ships.

Suggest a link under the diagram to the module it describes, using a relative link as above. The next reader of the README shouldn't have to guess which directory the boxes came from.

Leave style nits alone unless contrast is broken. Dark mode is already covered above on this page. A classDef with a light fill and no text color is worth a comment because the words disappear for half your readers. A theme name is not.

When GitHub's Mermaid build is behind

GitHub updates its Mermaid version on its own schedule. A keyword that works in the editor today, especially a newer type such as architecture, radar, treemap, or kanban, can render as an error on GitHub while the rest of the README is fine. The fence is not the problem. The build is.

Don't wait on that bump to explain a design. Export an SVG and commit it next to the source.

  1. Open the diagram in the editor, or use the Mermaid to SVG converter.
  2. Download the SVG. Prefer SVG over PNG when the README is viewed on screens of different sizes. Use the PNG converter if a consumer of the repo can't handle SVG.
  3. Commit both files, for example docs/deploy.mmd and docs/images/deploy.svg. The .mmd file is what you edit next time. The SVG is what GitHub shows until its renderer catches up.
  4. In the README, keep the mermaid fence if you want GitHub to try, and add the image under it for readers who hit the error. Or replace the fence with the image until the keyword is safe on GitHub. Say in a sentence which one is current so people don't "fix" a duplicate.

Regenerate the SVG when the text changes. A stale SVG beside a newer fence is worse than no image, because the two pictures disagree. If this happens often, render in CI with npx -p @mermaid-js/mermaid-cli mmdc and fail the job when the committed SVG doesn't match. The export guide shows the command, including background and scale for the PNG case.

A full URL to a published MermaidViewer diagram is a reasonable link from the README ("edit this chart here"). It is a poor replacement for the text in the repo. The repo should still contain the source your teammates can change without an account on another site.

A README you can adapt

Here is a short README for a checkout service. The diagram in the middle is the one rendered below. On GitHub, put that diagram in a mermaid fence: a line of three backticks plus the word mermaid, the diagram, then a line of three backticks. This page can't show those backtick lines inside a code sample without ending the sample, so the sample uses words where the fence goes.

text
# Checkout

Charges a card and writes a ledger row. The chart below is the happy path
and the decline. On-call notes live in the runbook.

Open a mermaid fence (three backticks and the word mermaid):
flowchart LR
    Client[Checkout UI] --> API[Shop API]
    API --> Pay[Card processor]
    Pay -->|Approved| Ledger[(Ledger)]
    Pay -->|Declined| Client
    Ledger --> API
    API --> Client
Close the fence with three backticks.

## Related

- [API reference](docs/api.md)
- [On-call runbook](docs/runbook.md)
- [Deploy pipeline](docs/deploy.md)

If GitHub cannot render the fence, use the committed image:

![Checkout charge path](docs/images/checkout.svg)

The same diagram, rendered:

Mermaid diagram
mermaid
flowchart LR
    Client[Checkout UI] --> API[Shop API]
    API --> Pay[Card processor]
    Pay -->|Approved| Ledger[(Ledger)]
    Pay -->|Declined| Client
    Ledger --> API
    API --> Client
Open in the live editor

Adapt the labels to your service names before you commit. Add a second fence for the refund path rather than growing this one into a map of the company. Point each fence at the doc that justifies it. If the pull request that introduces the README also adds the handler, the reviewer should be able to match Pay and Ledger to packages in that diff without asking you to present the picture in a meeting.

After the pull request merges

Open the file on GitHub, not only in the editor. The hosted renderer can be a Mermaid version behind the one you used locally, and a diagram that parsed here can show a code block there. If that happens, simplify the newest syntax first: drop @{ shape } and HTML labels before you blame the fence. The syntax errors guide is the checklist for the red line.

Frequently asked questions

Why isn't my Mermaid diagram rendering on GitHub?

Check that the code block is fenced with ```mermaid (lowercase), that the syntax is valid (paste it into MermaidViewer to see the exact error), and that the diagram type is supported by GitHub's Mermaid version.

Can I use Mermaid in GitHub issues and pull requests?

Yes. Mermaid code blocks render in issues, pull requests, discussions, wikis and Markdown files.