mermaid-cli: diagrams as a compile target, from mmd files to SVG

Diagrams as a compile target

The premise is one sentence, a command line interface for mermaid that takes a mermaid definition file as input and generates an SVG, PNG or PDF file as output, which reframes diagramming as compilation, source in, artifact out, with everything that implies for build systems and version control. The basic invocation is mmdc -i input.mmd -o output.svg, and there is basic support for converting mermaid code blocks embedded within Markdown files on top. The executable name mmdc, shorter than the package, is the handle everything else builds on, mmdc -h lists the full option surface. The package installs globally through npm install -g @mermaid-js/mermaid-cli, and the project sits in the mermaid-js organization beside the library it wraps, MIT licensed and maintained by Tyler Long. The two flag shapes already shown matter more than they seem, npm installs the package but the command is mmdc, and remembering that one translation, package name in, short command out, is most of what the first five minutes with the tool require:

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

mmdc -i input.mmd -o output.svg

Themes, backgrounds, sizes and injected CSS

The rendering flags cover the output decisions people actually make. A dark theme with a transparent background is one command, mmdc with -t dark and -b transparent for a PNG that sits on any page. The --size flag attempts a target size by setting a max width on the SVG, choosing max height for narrow diagrams and max width for wide ones, with the documented example producing a 4000 pixel tall PNG, and the honest caveat that it may not work with all diagram types and may need useMaxWidth true in the diagram config. The --cssFile option inlines custom CSS passed through to Mermaid's themeCSS, and the repository ships an animated flowchart example, a CSS file whose animations end up inside the SVG, along with the warning that inline CSS may be blocked by the hosting site's Content-Security-Policy header.

Icon packs from npm or from a URL

Custom icon packs are supported two ways, matching how teams consume assets. Icon packs installed through npm, such as at iconify-json slash logos, are used via the --iconPacks option naming the package. Icon packs accessible by URI work through --iconPacksAndUrls, accepting either remote URLs or local file:// URIs, with the documented example pulling the logos pack from jsDelivr by combining the pack name and the CDN address of its icons.json. The two paths cover both the locked down build, where icons are npm dependencies pinned in a lockfile, and the lightweight one, where a CDN reference avoids installation entirely, and both feed Mermaid's icon configuration rather than being a CLI side channel.

Markdown in, markdown out

The markdown transformation is the feature documentation pipelines keep. Running mmdc -i readme.template.md -o readme.md transforms the markdown file itself, mermaid-cli finds the mermaid code blocks, creates SVG files from them, and refers to those files in the markdown output, so a template with inline diagrams becomes a published readme with rendered images referenced by link. The example shows the full round trip, blocks containing graph and sequenceDiagram definitions, and a third using accTitle and accDescr for accessibility metadata, all replaced by image references in the result. Combined with stdin piping, a heredoc piped to mmdc --input - renders a diagram that never existed as a file, covering both the repository scale workflow and the one off in a shell. The accTitle and accDescr example is quietly important for the same pipelines, since generated SVGs that carry accessibility metadata inside the source diagram keep that metadata through compilation, rather than losing it the way hand exported images usually do.

Puppeteer is the engine underneath

The reason a diagram CLI carries a browser dependency is architectural, Mermaid renders in a web environment, so mermaid-cli drives it through Puppeteer, declared as a peer dependency at version 25, with a headless Chromium doing the actual layout and rasterization. The package metadata shows what accompanies that choice, katex for mathematical typesetting, variable and fixed fonts from fontsource, FontAwesome, and the mermaid and mermaid-zenuml packages as the rendering core, with an optional tidy tree layout package. The engines field requires Node 22.13 or newer, and the build pipeline compiles TypeScript and bundles an HTML host with Vite, the modern equivalent of the page Puppeteer loads to run Mermaid before capturing its output.

Docker and Podman, with SELinux explained

Container images avoid installing any of that locally, published both as minlag/mermaid-cli on Docker Hub and ghcr.io/mermaid-js/mermaid-cli/mermaid-cli on GitHub's registry, with version tags available. The container looks for input files in /data, so the docker invocation mounts a diagrams directory there and runs with the caller's uid and gid to avoid root owned outputs. The Podman variant is documented with its differences explained rather than just shown, --userns keep-id keeps the user's UID instead of mapping to a subuid, and the :z suffix on the volume relabels files with container_file_t so SELinux lets the container read them, two sentences of container security education embedded in a usage example. An older layout that mounted files in /home/mermaidcli can be restored with --workdir. Running the image with the caller's own IDs is the detail that makes CI adoption pleasant, output files owned by root are the classic containerized build tool failure, and avoiding it costs two flags documented on the same line as the command.

Four install paths and a name mismatch

Beyond global install, three alternatives exist for specific pain points. Local installation, npm install followed by ./node_modules/.bin/mmdc, answers the long standing issues some people have installing the tool globally, referenced to a real GitHub issue. Running through npx needs the -p flag because the package name differs from the command it installs, the at-mermaid-js slash mermaid-cli package versus the mmdc binary, a small trap the documentation calls out. And a Node API exposes run as an import, taking input path, output path and optional options, with the warning in bold that the Node API is not covered by semver since mermaid-cli follows mermaid's versioning, so programmatic consumers pin versions and read changelogs rather than trusting semver ranges.

Golden tests and a version that follows mermaid

Quality infrastructure is visible in the repository layout, test-positive and test-negative directories of input cases, a run-tests script executing them through the CLI, a src-test suite under Jest, and Percy visual testing catching rendering regressions in the output images, the right test type for a tool whose product is pictures. GitVersion configuration derives versions from history, and the Dockerfile builds on node 22 Alpine with the system chromium as CHROME_BIN and Puppeteer's own download skipped, installing the CLI at a build-time version and running as an unprivileged user with the puppeteer config baked in. The release line tells the versioning story, 11.16.0 in June 2026, 11.17.0 in September, then 12.0.0 on 2026-09-24 tracking Mermaid 12, with the last push 2026-09-25.

Editorial conclusion

Use mermaid-cli wherever diagrams should be build artifacts, documentation pipelines, CI checks that render every diagram in a repo, batch conversions of legacy files, since one mmdc invocation turns text into an image reproducibly. Prefer Mermaid's in browser rendering when interactivity matters, the CLI output is static by construction. Before adopting, note the Node 22.13 requirement, treat the Node API as unstable since it is explicitly not covered by semver, pick the Docker or Podman route when a browser dependency on the host is unwanted, and pin versions deliberately, the CLI follows Mermaid's versioning so major jumps track rendering changes, as the 11.x to 12.0.0 step shows.

Frequently asked questions

Official sources

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