Another Way to Convert Mermaid to Images: Mermaid CLI for Developers

Developers often need a repeatable, scriptable way to convert Mermaid diagrams into standard image formats. While web tools are great for quick conversions, the command-line offers automation, CI/CD integration, and full local control. This article shows how to use @mermaid-js/mermaid-cli to render high-quality PNG, JPG, SVG, and PDF from Mermaid code.

What Is Mermaid CLI?

Mermaid CLI is a command-line interface that takes Mermaid definition files and produces images (SVG/PNG/JPG/PDF) without requiring a browser UI. It’s ideal for batch processing, build pipelines, and reproducible documentation. Learn more on the official repository: https://github.com/mermaid-js/mermaid-cli

How Do You Install Mermaid CLI?

You can install globally, locally, run via npx, use Docker, or call it via a Node.js API depending on your workflow.

Global install (simple and convenient for local usage):
```
npm install -g @mermaid-js/mermaid-cli
```
Local install (avoids global dependencies, great for projects):
```
npm install @mermaid-js/mermaid-cli
```
Then call the binary from node_modules:
```
./node_modules/.bin/mmdc -h
```
Run with npx (no prior install, useful for one-off usage):
```
npx -p @mermaid-js/mermaid-cli mmdc -h
```

Docker/Podman (isolated environment and easy CI integration):

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

# if use podman
podman run --userns keep-id --user ${UID} --rm -v /path/to/diagrams:/data:z ghcr.io/mermaid-js/mermaid-cli/mermaid-cli -i diagram.mmd

Node.js API (programmatic control inside scripts):

import { run } from "@mermaid-js/mermaid-cli"

await run(
  "input.mmd",
  "output.svg",
  // optional options object
)

How Do You Convert Mermaid to an Image?

Use the mmdc command with an input Mermaid file (-i) and an output path (-o).

Note: The following commands assume mmdc is available via PATH (global install) or invoked using npx. If you installed locally, replace mmdc with ./node_modules/.bin/mmdc; for Docker, use the container command entry (e.g., docker run ... minlag/mermaid-cli -i ...).

Convert a Mermaid file to SVG:
```
mmdc -i input.mmd -o output.svg
```

Convert to PNG or PDF (change the extension):

mmdc -i input.mmd -o output.png
mmdc -i input.mmd -o output.pdf

How Do You Control Theme and Background?

Use the -t flag for theme and -b for background.

Dark theme with transparent background:

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

Can You Add Custom CSS or Override Styles?

Yes. You can inline a CSS file via --cssFile or use themeCSS through a config file (--configFile).

Inline custom CSS:

mmdc --input flowchart.mmd --cssFile flowchart.css -o docs/flowchart-styled.svg

Tip: If you want to override Mermaid theme styles globally, prefer adding {"themeCSS": "..."} in a --configFile to ensure consistent results.

How Do You Transform a Markdown File with Mermaid Diagrams?

Point mmdc to a Markdown template and an output file; it will render Mermaid blocks into referenced SVGs.

Transform a Markdown file containing multiple Mermaid diagrams:
```
mmdc -i readme.template.md -o readme.md
```
The CLI finds Mermaid code blocks, generates SVGs, and updates the Markdown to reference the generated images.

How Do You Pipe from stdin?

Use --input - to read Mermaid code from standard input.

Example using a heredoc:

cat << 'EOF' | mmdc --input - -o diagram.svg
graph TD
  A[Client] --> B[Load Balancer]
EOF

Best Practices for Developers

Organize inputs/outputs, standardize options, and integrate into scripts.

Organize files: Use a dedicated diagrams/ directory for sources and an artifacts/ directory for outputs.
Standardize options: Use a shared config file (e.g., theme, background) so CI and local runs match.

Automate with scripts: Add a script to package.json, for example:

{
  "scripts": {
    "build:diagrams": "mmdc -i diagrams/arch.mmd -o artifacts/arch.svg -t dark -b transparent"
  }
}

Use in CI/CD: In GitHub Actions or GitLab, run mmdc via Docker or npx to avoid managing global installs.

When Should You Use the CLI vs. a Web Tool?

Use the CLI for automation and reproducibility; use a web tool for quick previews, interactive editing, and immediate visual feedback.

CLI advantages: repeatability, versioning, scripting, non-interactive builds.
Web tool advantages: instant preview, error visibility, quick iteration and layout tweaks.

Conclusion

If you prefer automation, reproducibility, and integration with developer workflows, Mermaid CLI is the perfect complement to web-based converters. With a few commands, you can turn any Mermaid code into production-ready images and wire it into build pipelines, documentation generators, and CI jobs.

Further reading: Mermaid CLI on GitHub — https://github.com/mermaid-js/mermaid-cli