mermaid-cli

To run the CLI without a permanent installation using npx, you must use the -p flag to specify the package name, as it differs from the command name (mmdc).

npx -p @mermaid-js/mermaid-cli mmdc -h

You can install mermaid-cli globally via npm to use the mmdc command anywhere in your terminal.

Alternatively, if you encounter issues with global installation, you can install it locally in your project directory and call the binary from ./node_modules/.bin/mmdc.

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

Use the mmdc command to convert a .mmd diagram file into an output file. The output format is determined by the file extension provided to the -o flag.

Basic usage:

mmdc -i input.mmd -o output.svg

If you prefer not to install the package locally, you can use Docker or Podman. The container expects input files to be located in the /data directory inside the container.

Docker usage:

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

Podman usage: Podman requires --userns keep-id to maintain user permissions and the :z flag on volume mounts for SELinux relabeling.

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

If you want to use a pre-installed browser (like Chrome or Firefox) instead of the bundled Chromium, you can provide a JSON configuration file using the --puppeteerConfigFile flag.

Note that Puppeteer is only guaranteed to work with the bundled Chromium; using an external executable is done at your own risk. You can check compatible Chrome versions via the Puppeteer repository if needed.

Supported Puppeteer launch options via this config include:

• executablePath: Path to your browser executable.
• product: Specify if you want to use firefox instead of chrome.
• timeout: Adjust the timeout before Puppeteer throws an error.

You can inline custom CSS into an SVG using the --cssFile option. This is useful for adding animations to your diagrams.

Warning: If you want to override mermaid's themeCSS, it is recommended to add {"themeCSS": "..."} to your mermaid --configFile instead. You may also need to use !important to ensure your styles override mermaid's defaults.

Warning: Inline CSS files may be blocked by the browser's Content-Security-Policy (CSP) depending on where the SVG is hosted.

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

To apply custom Puppeteer arguments (such as --no-sandbox) when running the Mermaid CLI, create a puppeteer-config.json file and pass it to the mmdc command using the -p flag.

mmdc -p puppeteer-config.json ...

If you encounter the error Failed to launch chrome! or Running as root without --no-sandbox is not supported when using mmdc on Linux, you can bypass the sandbox requirement by providing a Puppeteer configuration file.

Note: The recommended long-term solutions are to avoid running as the root user and to ensure your Linux kernel is updated to the latest version. Use the --no-sandbox workaround only if you cannot follow those recommendations.

{
    "args": ["--no-sandbox"]
}

When running the mermaid-cli Docker image, you may encounter an EACCES: permission denied error when attempting to write output files (e.g., .svg). This typically happens because the container process does not have permission to write to the mounted volume.

To resolve this, use the -u flag to run the container with your current user's UID (User ID).

docker run -u $UID -it --rm -v "$(pwd)":data minlag/mermaid-cli -i /data/diagram.mmd

The CLI can process a Markdown file, find all mermaid code blocks, convert them into SVG files, and replace the code blocks with image references in a new Markdown file.

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