@mermaid-js/mermaid-cli

What is @mermaid-js/mermaid-cli?

@mermaid-js/mermaid-cli is a command-line interface tool for generating diagrams and flowcharts from Mermaid code. It allows users to convert Mermaid syntax into various graphical formats such as SVG, PNG, and PDF, making it useful for documentation, presentations, and visualizations.

What are @mermaid-js/mermaid-cli's main functionalities?

Generate SVG from Mermaid code

This command takes a Mermaid definition file (input.mmd) and generates an SVG file (output.svg) from it. SVG is a widely used vector graphic format that can be easily embedded in web pages.

npx mmdc -i input.mmd -o output.svg

Generate PNG from Mermaid code

This command converts a Mermaid definition file (input.mmd) into a PNG image (output.png). PNG is a popular raster graphic format suitable for various applications.

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

Generate PDF from Mermaid code

This command converts a Mermaid definition file (input.mmd) into a PDF document (output.pdf). PDF is a versatile document format that is widely used for sharing and printing.

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

Specify theme for the diagram

This command generates an SVG file (output.svg) from a Mermaid definition file (input.mmd) and applies the 'forest' theme to the diagram. Themes can be used to customize the appearance of the diagrams.

npx mmdc -i input.mmd -o output.svg -t forest

Watch mode for live updates

This command enables watch mode, which monitors the input Mermaid file (input.mmd) for changes and automatically regenerates the output SVG file (output.svg) whenever the input file is modified. This is useful for live editing and previewing.

npx mmdc -i input.mmd -o output.svg -w

Other packages similar to @mermaid-js/mermaid-cli

plantuml

PlantUML is a tool that allows users to create UML diagrams from plain text descriptions. It supports a wide range of diagram types, including sequence diagrams, use case diagrams, and class diagrams. Compared to @mermaid-js/mermaid-cli, PlantUML focuses more on UML standards and offers extensive customization options.

graphviz

Graphviz is an open-source graph visualization software that takes descriptions of graphs in a simple text language and generates diagrams in various formats. It is highly customizable and supports complex graph layouts. While @mermaid-js/mermaid-cli is more user-friendly and focused on simplicity, Graphviz offers more advanced features for detailed graph visualization.

README

mermaid-cli

This is a command-line interface (CLI) for mermaid. It takes a mermaid definition file as input and generates an svg/png/pdf file as output.

Installation

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

Usage

Convert Mermaid mmd Diagram File To SVG

mmdc -i input.mmd -o output.svg

Note

See Alternative installations if you don't want to install the package globally.

Locate how to call the mmdc executable for your preferred method i.e. Docker, Yarn, NPM, local install, etc.

Examples

Create A PNG With A Dark Theme And Transparent Background

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

Animating an SVG file with custom CSS

The --cssFile option can be used to inline some custom CSS.

Please see ./test-positive/flowchart1.css for an example of a CSS file that has animations.

Warning: If you want to override mermaid's themeCSS, we recommend instead adding {"themeCSS": "..."}) to your mermaid --configFile. You may also need to use !important to override mermiad's themeCSS.

Warning: Inline CSS files may be blocked by your browser, depending on the HTTP Content-Security-Policy header of the website that hosts your SVG.

mmdc --input test-positive/flowchart1.mmd --cssFile test-positive/flowchart1.css -o docs/animated-flowchart.svg

Example output: docs/animated-flowchart.svg

Transform a markdown file with mermaid diagrams

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

This command transforms a markdown file itself. The mermaid-cli will find the mermaid diagrams, create SVG files from them and refer to those in the markdown output.

This:

### Some markdown
```mermaid
graph
   [....]
```

### Some more markdown
```mermaid
sequenceDiagram
   [....]
```

### Mermaid with custom title/desc
```mermaid
graph
   accTitle: My title here
   accDescr: My description here
   A-->B
```

Becomes:

### Some markdown
![diagram](./readme-1.svg)

### Some more markdown
![diagram](./readme-2.svg)

### Mermaid with custom title/desc
![My description here](./readme-3.svg "My title here")

Piping from stdin

You can easily pipe input from stdin. This example shows how to use a heredoc to send a diagram as stdin to mermaid-cli (mmdc).

cat << EOF  | mmdc --input -
    graph TD
    A[Client] --> B[Load Balancer]
EOF

See All Available Options

mmdc -h

Alternative installations

Use Docker/Podman:

docker pull minlag/mermaid-cli

or pull from Github Container Registry

docker pull ghcr.io/mermaid-js/mermaid-cli/mermaid-cli

or e.g. version 8.8.0

docker pull minlag/mermaid-cli:8.8.0

The container looks for input files in /data. So for example, if you have a diagram defined on your system in /path/to/diagrams/diagram.mmd, you can use the container to generate an SVG file as follows:

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

Or, if using Podman, instead do:

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

The key differences in the podman command versus the docker command are:

• The addition of the --userns keep-id argument. This allows the container to keep the same UID as the current user's UID in the container namespace instead of mapping to a subuid. Docs can be found here
• The addition of :z to the end of the volume mapping. This instructs podman to relabel the files in the volume with the SELinux label container_file_t, which allows processes in the container to access the files. See the "Labeling Volume Mounts" section here for more info.

In previous version, the input files were mounted in /home/mermaidcli. You can restore this behaviour with the --workdir option:

docker run [...] --workdir=/home/mermaidcli minlag/mermaid-cli [...]

Use Node.JS API

It's possible to call mermaid-cli via a Node.JS API. Please be aware that the NodeJS API is not covered by semver, as mermaid-cli follows mermaid's versioning.

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

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

Install locally

Some people are having issues installing this tool globally. Installing it locally is an alternative solution:

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

Or use NPM:

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

Run with npx

npx is installed by default with NPM. It downloads and runs commands at the same time. To use Mermaid CLI with npx, you need to use the -p flag because the package name is different than the command it installs (mmdc). npx -p @mermaid-js/mermaid-cli mmdc -h

Install with brew

Warning

This method of installation is no longer supported. For more details, see the discussion. An old version of mermaid-cli can be installed with brew.

brew install mermaid-cli

Known issues

1. Linux sandbox issue
2. Docker permission denied issue
3. How to setup up mermaid to use already installed chromium?

For contributors

Contributions are welcome. See the contribution guide.