How to render mermaid diagram output in a browser, a doc, or CI

Knowing how to render mermaid diagram text comes down to three paths, and you pick one per picture. A browser editor draws the source while you type. A Markdown host, such as a repository or an issue tracker, draws a fence when it builds the page. The mermaid CLI, the official command named mmdc, draws a file on disk into an image you can attach anywhere. All three consume the same diagram language. They do not share a preview, a version, or a button. I choose based on who has to see the picture, and how often the source will change.

Rendering means the text becomes a drawing. It does not mean the drawing becomes the source. I keep the .mmd file or the fence, and I treat PNG, SVG, and PDF as outputs I can make again. The day the only copy is a screenshot, you have stopped rendering and started archiving a guess.

The browser editor

The fastest path is a page that parses Mermaid in the browser and shows the picture next to the text. Open the editor and paste a diagram. The preview is live, so a broken arrow shows up while the line is still on screen. There is no account required for that loop. You can write, read, and throw the tab away.

I use this path when I am designing the chart, when a teammate pasted a fence into chat and I want to know if it parses, and when a host is failing and I need to separate "bad syntax" from "old renderer." If the editor draws it and the host does not, the syntax is fine and the host is behind. If the editor does not draw it, I fix the text before I blame GitLab, Notion, or a CI job.

AI sits on this path too. The editor can generate a diagram from a sentence, edit one you have, or fix a parse error. Free accounts include 5 AI uses in total. I spend them after I know which of the three paths is the destination. A generated flowchart that never gets pasted into the file you meant to ship was a demo, not a render of your system.

Export is the bridge from this path to a file. PNG works on every plan. Free PNG is 1× with a watermark. Starter, at $6.99 a month, is watermark-free up to 4×. JPG, SVG, and PDF are Pro-only, at $11.99 a month. The export guide is the longer discussion of which format survives a slide deck or a printer. The Mermaid to SVG tool and the Mermaid to PNG tool are the browser converters when you already have source and you want a file without a tour of the editor. Use them when the destination is an image slot. Use the fence when the destination can render Mermaid itself.

Markdown hosts

A host renders a fence: three backticks, mermaid, the diagram, three backticks. GitHub, GitLab, a wiki, and a docs site each ship some Mermaid build. The build is the limit. A diagram that renders in the editor can fail on the site because the site is on an older library, or because it disables click callbacks and HTML labels. I write plain flowcharts and sequences when the fence has to travel. I keep beta diagram types for hosts I have tested this month.

The preview inside the host is part of rendering, and it is not the same as the saved page. Look at both when the tool offers a preview. Issue trackers are the place this bites, because the comment box shows source until you ask it not to. vscode is the place it bites differently: the built-in preview on a recent install draws the fence, and it updates on save rather than on each key. The vscode mermaid preview settings note is that loop. Do not expect a Markdown host to feel like the live editor. Save, or publish, then look.

Embedding on a site you control is a fourth doorway that still belongs to "the page renders it," and the embed Mermaid in HTML guide is the one that names mermaid.run() and a strict security level. I send people there when the diagram is part of a web app. I keep them on the fence path when the diagram is part of a document. Mixing the two, a fence inside an HTML file that nobody runs Mermaid on, produces a page of source code and a long argument about caching.

Two keywords in one fence fail everywhere I have tried. One diagram, one fence, a sentence between them if the page has two pictures. The host is not being difficult. The fence is one render call.

The CLI, named mmdc

mmdc is the official command-line interface. It reads a text file of Mermaid and writes an output file. I use it in CI, in a docs build, and on a machine where I do not want a browser tab. The package name you will see in registries is @mermaid-js/mermaid-cli. The command you run is mmdc.

The flag list lives in that CLI's README. I am not going to reproduce it. Flags move, and a blog post full of switches becomes a second, worse README. The only form I will put here is input file to output file:

npx -p @mermaid-js/mermaid-cli mmdc -i diagram.mmd -o diagram.svg

-i is the Mermaid source. -o is the file to write. The extension on the output name is how this invocation chooses SVG. A .png output name asks for PNG instead. Anything beyond those two flags, scale, background, theme, config files, is a README topic. Look it up when you need it, on the version you installed, rather than from memory of this paragraph.

npx -p downloads the package if you do not have it and runs mmdc. Pin the version in CI if a surprise upgrade would be a bad afternoon. A floating CLI is how a diagram that passed last week fails in a scheduled build because a parser got stricter. I pin when the image is a release artifact. I float when I am poking at a file on my laptop and I can read the error.

The CLI does not know about MermaidViewer plan limits. A watermark and a 1× cap are editor and converter features. mmdc on your machine writes the file the tool writes. You still have to pick a background that survives the place you will paste the image. Transparent PNGs become black rectangles in more slide tools than I want to count. If you are unsure, write an SVG, or write a PNG and look at it in the destination app before you send the mail. The CLI README's background flag is the knob. I am not pasting it here, on purpose.

Input is a file, not a fence. diagram.mmd contains the diagram keyword and the nodes. It does not contain the surrounding Markdown backticks. If you point mmdc at a .md file, behavior depends on the version and on flags I just refused to list. The reliable habit is a .mmd file with only the diagram, or a README you render with a tool that understands fences. Know which one your script does.

What rendering will not fix

A renderer will not repair a bad branch. If the diamond says the opposite of the code, a crisp SVG is a crisp mistake. I read the picture after it renders. I do not treat a successful parse as a review. The CLI exiting zero means the file was legal Mermaid. It does not mean the refund policy is the one finance approved.

A renderer will not keep two copies in sync. The fence in the repo, the PNG in the slide, and the page in the wiki are three renders only if someone generates the later ones from the first. I write the source path in the slide notes. When the slide is wrong, I know which text to edit. A render step in CI that fails the build on a parse error is worth more than a styling flag. I would rather block a pull request on a broken fence than publish a beautifully themed error.

Version skew survives all three paths. The editor can be newer than mmdc in CI, which can be newer than the wiki. A chart that uses a feature from last month needs a renderer from last month. When I cannot upgrade the host, I render an image with a current CLI or the browser tool and I embed the image, and I say so. Pretending the host rendered it will confuse the next person who edits the fence and sees no change on the page.

Click callbacks and HTML labels are the features I strip before I render for a host. They might work in a local loose mode. They are a bad bet on GitHub, GitLab, and any embed with a strict security level. The picture should still make sense with plain text in the nodes. If it needs a click to be understood, the paragraph under the figure is doing the linking.

Two diagrams, three ways to see them

This flowchart is small enough to render on any of the three paths. In the editor it is a live preview. In a README it is a fence. In CI it is the contents of diagram.mmd passed to mmdc.

flowchart TD
  source[Mermaid text] --> where{"Who must see it?"}
  where -->|Author, right now| editor[Browser editor]
  where -->|Readers of the doc| fence[Markdown host]
  where -->|A file to attach| cli[mmdc on disk]

The diamond is the method on this page. I answer it before I pick a theme. Theme is a polish step on the path you already chose. Polishing a CLI render that nobody attaches is how an evening disappears.

The sequence is the same choice, told as a conversation between you and the tool. I keep it next to the flowchart because people remember one of the two shapes. Give them both, and the pull request has a chance.

sequenceDiagram
  actor Author
  participant Edit as Editor
  participant Host as Markdown host
  participant CLI as mmdc
  Author->>Edit: Draft until it parses
  alt Doc can render Mermaid
    Author->>Host: Commit the fence
    Host-->>Author: Draw on the page
  else Destination wants a file
    Author->>CLI: Input file, output file
    CLI-->>Author: Write the image
  end

The alt is the decision, not a fallback you attempt in order. If the doc can render the fence, committing an image beside it creates a second source. I do that only when a consumer cannot read the fence, and I name the fence as the source in the sentence above the image. The Mermaid format note is about how that text is structured. The code to diagram note and the view diagrams online note sit on the browser side of the same map. Use them when the path is "open a tab." Use mmdc when the path is a build.

Pick the path, then render once

Write the diagram in the browser until the branches are true. Move the text to the place the readers already are, if that place can draw a fence. If it cannot, run mmdc with an input file and an output file, or use the browser converters, and attach the result. Check the picture in the destination, not only in the tool that produced it. Dark slides, narrow issue columns, and printers all have opinions the editor will not volunteer.

Open the editor for the live path, and keep mmdc for the file path. One diagram should have one source. The renders are disposable. That is the part I want in the README's first line, above whichever picture you picked.