Render Mermaid diagrams to static SVG for offline HTML documents

Why client-side Mermaid fails offline

A Mermaid code block is text until the Mermaid library runs and replaces it with SVG. In an exported HTML file that usually means a script tag pointing at a CDN. With no network, or with JavaScript disabled as it is by default in gitHtml, the reader sees the raw graph definition instead of a diagram.

Pre-rendering moves that work to the author's machine. The output is plain SVG, which browsers draw natively and which can live inside the HTML file itself.

Install and render

The CLI is the npm package @mermaid-js/mermaid-cli and runs a headless Chromium through Puppeteer, so the first install downloads a browser. Current releases require a recent Node.js; check the project README for the supported version. You can also run it through npx without a global install.

npm install --save-dev @mermaid-js/mermaid-cli

# One diagram to SVG with a transparent background
npx mmdc -i docs/diagrams/checkout-flow.mmd -o docs/diagrams/checkout-flow.svg -b transparent

# Dark theme variant
npx mmdc -i docs/diagrams/checkout-flow.mmd -o docs/diagrams/checkout-flow-dark.svg -t dark

# Markdown in, Markdown out: diagrams become SVG files referenced as images
npx mmdc -i docs/design.template.md -o docs/design.md

Put the SVG into the document

For a single portable file, paste the SVG markup directly into the HTML, or embed it as a data URI in an img element. Inline SVG scales with the page and keeps text crisp when zoomed; wrap it in a container with overflow-x: auto so wide flowcharts scroll instead of shrinking to unreadable size. Referencing a separate .svg file works too, but only when that file travels with the document and the relative path resolves.

Keep the .mmd source in the repository next to the SVG so the diagram can be edited and regenerated rather than redrawn.

1. Store the diagram source as a .mmd file under version control.
2. Render to SVG with mmdc and commit the output alongside it.
3. Inline the SVG in the HTML inside a horizontally scrollable figure.
4. Add a figcaption or paragraph that states what the diagram shows in words.
5. Open the HTML offline with JavaScript disabled and confirm the diagram renders.

Keep diagrams accessible and current

A flowchart is not a substitute for prose. Write two or three sentences that walk through the main path and the important exceptions, so screen reader users and anyone on a narrow screen get the same information. When the process changes, edit the .mmd file, re-render, and commit both in one change; a stale diagram is worse than none.

Read next

• Prepare diagrams that remain useful offline
• Include diagrams without a runtime rendering dependency
• Describe architecture diagrams as relationships, not shapes
• Use inline CSS for a dependable portable reading copy

All offline reading guides →