mermaid-cli (mmdc): render Mermaid diagrams to SVG, PNG and PDF from the command line

What mermaid-cli does that the Mermaid library alone does not

Mermaid is a diagramming syntax that normally renders in a browser. The library draws the diagram; a page has to host it, load the JavaScript, and show the result. That is fine when a human is looking at a wiki, and awkward when a build server, a static site generator, or a documentation pipeline needs an image file.

mermaid-cli closes that gap. The README describes it plainly: "It takes a mermaid definition file as input and generates an SVG/PNG/PDF file as output." The package installs a binary named mmdc, and that binary is the whole product surface. Input is a .mmd file (or stdin, or a Markdown file), output is a file on disk.

The audience is narrow and specific. People who keep diagrams in a repository and want them regenerated by a command. People who generate documentation from Markdown and do not want to paste screenshots. People who need a PNG at a fixed theme and background for a slide deck or a PDF report. If your diagrams only ever live inside a hosted Mermaid renderer, you are not the target user.

How mmdc renders a diagram: Puppeteer, Chromium and a headless page

The mechanism is visible in the dependency list. mermaid-cli declares puppeteer as a peer dependency (^25.0.0) and mermaid itself as a regular dependency (^12.2.0). So mmdc is not a pure SVG generator written from scratch. It starts a headless browser, loads a page that runs Mermaid, feeds the diagram definition in, and captures the rendered result.

That explains several things in the repository layout. There is a puppeteer-config.json at the top level, and the Dockerfile copies it to /puppeteer-config.json while setting CHROME_BIN to /usr/bin/chromium-browser and PUPPETEER_SKIP_DOWNLOAD to true. In other words, the container image ships its own Chromium and tells Puppeteer not to fetch one. The Dockerfile also sets the entrypoint to mmdc with -p /puppeteer-config.json, so the container always runs with that browser configuration.

The practical consequence: rendering is a browser operation, and the environment you run it in has to be able to launch one.

Data flow is straightforward. A .mmd file goes in. Mermaid parses it inside the headless page. The page produces SVG. mmdc writes SVG, or rasterizes to PNG, or wraps it into PDF, depending on the output extension and flags. The --cssFile option inlines custom CSS into the diagram through Mermaid's themeCSS config option, which is why the README warns that a hosting site's Content-Security-Policy header may block those inline styles.

Installing mermaid-cli and rendering your first diagram

The README's primary install path is a global npm install. The package requires Node 22.13.0 or newer according to the engines field in package.json, so check that first.

npm install -g @mermaid-js/mermaid-cli

After this, mmdc is on your PATH. A minimal render takes an input file and an output path, and the extension decides the format.

mmdc -i input.mmd -o output.svg

If you would rather not install globally, the README documents a local install and then calling the binary directly, plus npx. Note the npx form needs -p because the package name and the command name differ.

npm install @mermaid-js/mermaid-cli
./node_modules/.bin/mmdc -h

Docker is the other documented route. The image looks for input files in /data, and the README's example mounts your diagram directory there and passes the UID and GID so the written file is owned by you.

docker pull minlag/mermaid-cli
docker run --rm -u `id -u`:`id -g` -v /path/to/diagrams:/data minlag/mermaid-cli -i diagram.mmd

One flag worth trying early is the theme and background combination, since it is the difference between a diagram that disappears on a dark page and one that does not.

mmdc -i input.mmd -o output.png -t dark -b transparent

Finally, mmdc accepts stdin, which makes it usable inside a shell pipeline without a temporary file. The README's heredoc example pipes a graph definition in with --input -.

Markdown rewriting is the feature that changes a docs workflow

Rendering one diagram is useful. Rendering every diagram in a Markdown file is the reason to put mmdc in a build step. The README shows the command and the transformation.

mmdc -i readme.template.md -o readme.md

The tool finds Mermaid code blocks in the input Markdown, produces an SVG file for each one, and replaces the block with an image reference. The README's example includes a diagram that sets accTitle and accDescr under the heading "Mermaid with custom title/desc".

There is a real trade-off here that the README does not discuss. The output Markdown is generated, so the generated file and the template both live in the repository. That is fine for a one-way build, less fine if someone edits the generated file by hand. Treat the template as the source and the output as an artifact, or you will spend time reconciling them.

Where mermaid-cli is the wrong tool

The heaviest constraint is the browser. Because rendering goes through Puppeteer and Chromium, mmdc carries an install and runtime footprint that a pure text-to-SVG converter would not. If your CI image is minimal and you cannot add a browser, this is the wrong choice.

The second constraint is that mmdc is a batch renderer, not an editor. For authoring, a browser-based live preview or an editor extension is the better loop; mmdc is what you run once the diagram is settled.

The third is versioning. The README states that the Node.js API is not covered by semver, because mermaid-cli follows mermaid's versioning. The package.json version is 12.0.0 while the mermaid dependency is ^12.2.0. If you call the API from a Node script rather than shelling out to mmdc, pin your versions and read release notes on upgrade.

Alternatives and how they differ in approach

The obvious alternative is Mermaid itself in the browser. Same diagram syntax, same library underneath, but rendering happens in the page and the output is whatever the page shows. You get live editing and zero install. You do not get a file on disk from a build script, and you cannot regenerate diagrams as part of a release without a human opening a tab. If your diagrams are published through a platform that renders Mermaid natively, the CLI adds nothing.

A different kind of alternative is a diagram tool that is not Mermaid at all, such as a text-based graph language with its own renderer, or an editor extension that bundles Mermaid. The difference is not just the renderer: it is the syntax and the ecosystem. Mermaid's syntax is what makes mermaid-cli useful to people already writing Mermaid in wiki pages and Markdown. Switching tools means rewriting diagrams.

Within the Mermaid ecosystem, the relevant distinction is invocation method rather than product. mmdc as a global binary, mmdc via npx with -p, a local node_modules/.bin/mmdc, the Docker image, and the Node.js run() API all render the same diagrams with different operational costs. The README also notes that the container previously mounted input in /home/mermaidcli and that the old behaviour can be restored with --workdir, which is worth knowing if you are adapting a script written against an older image.

Maintenance, licence and what an upgrade actually costs

The repository is not archived, and the last push was on 2026-11-02. Releases are frequent: 12.2.0 on 2026-11-02, 11.17.1 on 2026-10-28, 12.0.0 on 2026-09-24. That cadence is the main reason to expect upgrade work rather than a one-time install.

The licence is MIT, declared in package.json and present as a LICENSE file at the repository root. MIT is permissive, so the practical question is not whether you may use it but what you inherit. Two things stand out. The package depends on mermaid, which the README says drives mermaid-cli's versioning, so a mermaid upgrade can change rendering output even when mmdc's own version looks like a minor bump. And the Docker image bundles Chromium, so image updates carry browser updates with them. If you pin an image tag, pin a real version rather than a floating tag, as the README's example of pulling minlag/mermaid-cli:8.8.0 illustrates. None of this is legal advice; if your organisation has licence review, the MIT text in LICENSE is the document to hand over.

The concrete upgrade risk is visual. The README notes the project uses Percy.io for visual regression testing, which tells you the maintainers treat rendering changes as something to catch with image diffs. If your diagrams are load-bearing, keep a couple of representative .mmd files and diff the SVG output across a version bump before rolling it out.

Editorial conclusion

Adopt mermaid-cli if diagrams live in version control next to the documents that use them and you want SVG output produced by a command instead of a web editor. Do not adopt it if you need a live preview pane, an interactive editor, or a rendering path that avoids a bundled Chromium; that is a browser-side or editor-side job. Before committing, verify three things: that your Node version satisfies the >=22.13.0 engine field, that you can run mmdc -h after installing, and that your container or CI user matches the UID used in the docker run command so output files are writable.

Frequently asked questions

Official sources

1. Issues
2. License: MIT
3. mermaid-js/mermaid-cli on GitHub
4. README
5. Releases