Mermaid OnlineTools

Guide · Mermaid in GitHub

How to Add Mermaid Diagrams to a GitHub README

GitHub renders Mermaid natively inside fenced code blocks, so for repos read on github.com that is all you need. Export an image instead when the README travels — npm, PyPI, and most external renderers show the raw code block — or when you want consistent styling instead of GitHub's default theme. Either way, never paste a screenshot.

No signup · No watermark · Local browser rendering · Works with GitHub light and dark mode

Does GitHub render Mermaid natively?

Yes — on github.com only

Fenced code blocks with the mermaid language tag render as diagrams in READMEs, issues, pull requests, discussions, and wikis. The limits: GitHub applies its own styling and adapts it to each viewer's theme, so you cannot control colors or branding; the same Markdown shown anywhere else — the npm or PyPI package page, GitLab mirrors, most static site generators, PDF exports — falls back to a plain code block; and GitHub's bundled Mermaid version can lag behind the newest syntax.

Native block or exported image — the workflow

  1. 1

    Start with a native Mermaid block

    Add a fenced code block with mermaid as the language and commit it. For internal repos and diagrams that change often, this is the lowest-maintenance option — the source is the diagram.

  2. 2

    Check where the README travels

    If the package is published to npm or PyPI, mirrored outside GitHub, or rendered into a docs site or PDF, readers there will see raw Mermaid code instead of a diagram. That is the signal to switch to an exported image.

  3. 3

    Export SVG — do not screenshot

    Paste the same Mermaid code into the converter below and export an SVG, or a 2x PNG as fallback. Screenshots capture the preview at screen resolution and turn blurry the moment they are resized.

  4. 4

    Commit the image next to the source

    Put the exported file in the repo (for example docs/diagram.svg), reference it with a normal image tag, and keep the Mermaid source in a collapsed details block beside it so the diagram stays editable. For dark-mode support, export a dark variant and switch between them with a picture element and prefers-color-scheme.

Export your diagram here

Paste your Mermaid code below, pick a style, and download the image. Everything renders locally in your browser — no signup, no watermark.

Paste or edit Mermaid code
Replace the sample below, or load another example.
Load example
Paste Mermaid code here. Preview and export load locally in your browser.
Live previewSample preview · GitHub README

Write

Preview

Export

Docs Asset

Render & export

Export controls activate after your diagram renders locally.

Flowchart
Mode
Default renderNative MermaidOptimized exportStyled download
Export style
Clean DocsGitHub READMEWarm EditorialWhiteboard SketchTransparent DocsGitHub DarkSlide DarkDeep Ocean
Scale
1x2x4x
Or exact width, e.g. 1200px wide
Output: White · comfortable padding
Size: calculated after render
Filename: mermaid-flowchart-white-2x.svg

Which approach works best on GitHub?

Native block — repos read on GitHub

Zero build step and always in sync with the source. The right default for internal tools and contributors who read the README on github.com.

SVG — READMEs that travel

Committed SVG files render inline in GitHub Markdown, stay sharp at any zoom, and keep file size small. The GitHub README export style matches GitHub's light theme.

PNG at 2x — maximum compatibility

Some external renderers and registries handle SVG inconsistently. A 2x PNG displays everywhere and keeps labels readable when the page scales it down.

Export AI-generated MermaidExport Mermaid from MarkdownMermaid to SVG converterMermaid to PNG converter

FAQ

Questions about this workflow

Does GitHub render Mermaid in issues and pull requests too?+

Yes. Fenced mermaid code blocks render as diagrams in READMEs, issues, pull requests, discussions, and wikis on github.com.

Why does my diagram show on GitHub but not on npm?+

Only github.com runs the Mermaid renderer. The npm and PyPI package pages, GitLab mirrors, and most documentation generators display the fenced block as plain code. Export the diagram as SVG or PNG and reference the image for those readers.

Can I change the colors of GitHub's native Mermaid rendering?+

Not meaningfully. GitHub applies its own styling and adjusts it to each viewer's light or dark theme. If you need brand colors or a consistent look for every reader, export a styled image instead.

How do I make the README diagram work in both light and dark mode?+

With a native block, GitHub adapts automatically. With images, export a light and a dark variant, then use an HTML picture element with a prefers-color-scheme media source — GitHub Markdown supports it — so each viewer gets the matching version.

Why does my Mermaid screenshot look blurry in the README?+

Screenshots are rasterized at your screen's resolution and degrade when GitHub scales them to the page width or when viewers zoom. Export SVG for vector sharpness, or PNG at 2x scale, directly from the renderer.