Render Mermaid in the Terminal: Convert .mmd and Markdown to SVG

If a build script needs a diagram image, use Mermaid's command-line tool, mmdc. It converts a standalone .mmd diagram to SVG, PNG, or PDF. It can also find Mermaid code blocks in a Markdown file and write a new Markdown file that references generated SVG images. This is a conversion workflow; if you only want to read a README in the terminal, see terminal Markdown viewers.

Install the Official Mermaid CLI

With Node.js and npm available, install the maintained CLI:

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

You can also use a project-local install or the CLI's Docker option when global packages are not appropriate. See the Mermaid CLI installation guide for those routes.

Convert a Standalone .mmd File

Save this as flow.mmd—a Mermaid file contains the diagram source, without a Markdown fence:

flowchart LR
    Draft[Draft] --> Review[Review]
    Review --> Publish[Publish]

Then render it:

mmdc -i flow.mmd -o flow.svg

Choose .png or .pdf as the output extension when you need that format. SVG is a useful default for documentation because it stays sharp when resized. For a dark theme and transparent background in a PNG, the CLI supports:

mmdc -i flow.mmd -o flow.png -t dark -b transparent

If you received a .mmd file and first need to inspect or edit it, start with how to open a .mmd file.

Render Mermaid Blocks Embedded in Markdown

Suppose readme.template.md contains ordinary prose followed by a fenced mermaid block. Run:

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

The CLI writes diagram SVG files and replaces the Mermaid blocks in the output Markdown with image references. Keep the template as the source of truth; do not overwrite it if you still want editable Mermaid code. Commit or publish the generated images alongside the output Markdown so its relative image links resolve.

Input	Command output	Use it for
flow.mmd	flow.svg, flow.png, or flow.pdf	One diagram asset
readme.template.md	readme.md plus diagram SVGs	README or static documentation that cannot render Mermaid itself

For a one-off document that already has Mermaid support, no conversion is needed: open the Markdown in mdview.io and read the diagrams in place. For automated checks of a whole document's Markdown and PDF output, see Markdown render verification from the CLI.

When the Command Fails

First check that the input exists and that mmdc is on your PATH. Next render a three-node flowchart like flow.mmd above. If that works but your real file does not, the problem is usually in the diagram source or a feature unsupported by the installed Mermaid version. Keep the smallest failing diagram and check the Mermaid syntax error guide before adding the rest back.

The complete command options and Markdown conversion example are in the official Mermaid CLI README.