## File: README.md # mermaid-cli [](https://www.npmjs.com/package/@mermaid-js/mermaid-cli) [](https://www.npmjs.com/package/@mermaid-js/mermaid-cli) [](https://hub.docker.com/r/minlag/mermaid-cli) [](https://github.com/mermaid-js/mermaid-cli/actions/workflows/compile-mermaid.yml) [](https://percy.io/Mermaid/mermaid-cli) [](https://join.slack.com/t/mermaid-talk/shared_invite/enQtNzc4NDIyNzk4OTAyLWVhYjQxOTI2OTg4YmE1ZmJkY2Y4MTU3ODliYmIwOTY3NDJlYjA0YjIyZTdkMDMyZTUwOGI0NjEzYmEwODcwOTE) This is a command-line interface (CLI) for [mermaid](https://mermaid.js.org/). It takes a mermaid definition file as input and generates an SVG/PNG/PDF file as output. ## Installation ```sh npm install @mermaid-js/mermaid-cli ``` ## Usage Convert Mermaid mmd Diagram File To SVG ```sh mmdc -i input.mmd -o output.svg ``` > **Note** > > See [Alternative installations](#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 ```sh 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](test-positive/flowchart1.css) for an example of a CSS file that has animations. **Warning**: If you want to override `mermaid`'s [`themeCSS`](https://mermaid.js.org/config/schema-docs/config.html#themecss), we recommend instead adding `{"themeCSS": "..."})` to your mermaid `--configFile`. You may also need to use [`!important`](https://developer.mozilla.org/en-US/docs/Web/CSS/important) to override mermaid's `themeCSS`. **Warning**: Inline CSS files may be blocked by your browser, depending on the [HTTP Content-Security-Policy header](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Content-Security-Policy) of the website that hosts your SVG. ```sh 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 ```sh 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: ````md ### 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: ```md ### Some markdown ### Some more markdown ### Mermaid with custom title/desc ``` ### 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). ```sh cat << EOF | mmdc --input - graph TD A[Client] --> B[Load Balancer] EOF ``` ### See All Available Options ```sh mmdc -h ``` # Alternative installations ## Use Docker/Podman: ```sh docker pull minlag/mermaid-cli ``` or pull from Github Container Registry ```sh docker pull ghcr.io/mermaid-js/mermaid-cli/mermaid-cli ``` or e.g. version 8.8.0 ```sh 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: ```sh docker run --rm -u `id -u`:`id -g` -v /path/to/diagrams:/data minlag/mermaid-cli -i diagram.mmd ``` Or, if using [Podman](https://podman.io/), instead do: ```sh 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. To learn more, see the [`userns=mode` documentation](https://docs.podman.io/en/v4.4/markdown/options/userns.container.html). - 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 of [podman-run (1)](https://docs.podman.io/en/latest/markdown/podman-run.1.html#volume-v-source-volume-host-dir-container-dir-options) for more info. In previous version, the input files were mounted in `/home/mermaidcli`. You can restore this behaviour with the `--workdir` option: ```sh 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. ```js import { run } from "@mermaid-js/mermaid-cli"; await run( "input.mmd", "output.svg", // {optional options}, ); ``` ## Install locally Some people are [having issues](https://github.com/mermaidjs/mermaid.cli/issues/15) installing this tool globally. Installing it locally is an alternative solution: ``` npm install @mermaid-js/mermaid-cli ./node_modules/.bin/mmdc -h ``` ### Run with npx [`npx`](https://www.npmjs.com/package/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](https://brew.sh) > **Warning** > > This method of installation is no longer supported. > For more details, see the [discussion](https://github.com/mermaid-js/mermaid-cli/issues/288). > An old version of mermaid-cli can be installed with brew. > > ```sh > brew install mermaid-cli > ``` ## Known issues 1. [Linux sandbox issue](docs/linux-sandbox-issue.md) 2. [Docker permission denied issue](docs/docker-permission-denied.md) 3. [How to setup up mermaid to use already installed chromium?](docs/already-installed-chromium.md) ## For contributors Contributions are welcome. See the [contribution guide](CONTRIBUTING.md). --- ## File: docs/already-installed-chromium.md The text below is taken from Issue #331. If you run mermaid-cli with the `--help` flag, there's an option for `--puppeteerConfigFile`, which is a JSON configuration file for puppeteer. These are options passed to [`puppeteer.launch`](https://pptr.dev/api/puppeteer.puppeteernode.launch/). The useful options for you are: - [`executablePath`](https://pptr.dev/api/puppeteer.launchoptions.executablepath) Path to a browser executable to use instead of the bundled Chromium. Note that Puppeteer is only guaranteed to work with the bundled Chromium, so use this setting at your own risk. You may find https://github.com/puppeteer/puppeteer/blob/main/versions.js useful to see **which versions of Chrome are compatible with versions of puppeteer**. - [`product`](https://pptr.dev/api/puppeteer.product) (in case you want to use firefox instead of chrome) - [`timeout`](https://pptr.dev/api/puppeteer.launchoptions.timeout) can be used to increase/decrease timeout before puppeteer throws an error You'll probably want a file called `puppeteerConfigFile.json` with contents: ```json { "executablePath": "C:\\path\\to\\your\\chrome.exe" } ``` Then run mermaid-cli with option `mmdc --puppeteerConfigFile puppeteerConfigFile.json`. You might also be able to do the same thing with environment variables by following: https://pptr.dev/#environment-variables. Btw, if you set `PUPPETEER_SKIP_DOWNLOAD=1` as an env variable when running `yarn install` or `npm install`, it should skip downloading CHROMIUM too. --- ## File: docs/docker-permission-denied.md When running the Docker image with Docker or Podman you get the following error: ``` › podman run -it -v "$(pwd)":/data:z minlag/mermaid-cli -i /data/diagram.mmd node:fs:582 handleErrorFromBinding(ctx); ^ Error: EACCES: permission denied, open '/data/diagram.mmd.svg' at Object.openSync (node:fs:582:3) at Object.writeFileSync (node:fs:2143:35) at /home/mermaidcli/node_modules/@mermaid-js/mermaid-cli/index.bundle.js:169:10 at Generator.next () at step (/home/mermaidcli/node_modules/@mermaid-js/mermaid-cli/index.bundle.js:4:191) at /home/mermaidcli/node_modules/@mermaid-js/mermaid-cli/index.bundle.js:4:361 at processTicksAndRejections (node:internal/process/task_queues:96:5) { errno: -13, syscall: 'open', code: 'EACCES', path: '/data/diagram.mmd.svg' } ``` You can solve this issue by using docker `-u` option with your `UID`: ``` docker run -u $UID -it --rm -v "$(pwd)":data minlag/mermaid-cli -i /data/diagram.mmd ``` The issue is described in [issue #140](https://github.com/mermaid-js/mermaid-cli/issues/140) --- ## File: docs/linux-sandbox-issue.md ``` (node:8281) UnhandledPromiseRejectionWarning: Error: Failed to launch chrome! [0416/092218.828861:ERROR:zygote_host_impl_linux.cc(88)] Running as root without --no-sandbox is not supported. See https://crbug.com/638180. (node:8191) UnhandledPromiseRejectionWarning: Error: Failed to launch chrome! [0416/091938.210735:FATAL:zygote_host_impl_linux.cc(124)] No usable sandbox! Update your kernel or see https://chromium.googlesource.com/chromium/src/+/master/docs/linux_suid_sandbox_development.md for more information on developing with the SUID sandbox. If you want to live dangerously and need an immediate workaround, you can try using --no-sandbox. ``` First and foremost, you should not run as root and you should upgrade your Linux kernel to latest version. But if you don't want to follow the advice above and just want to disable sandbox, here you go: Create a `puppeteer-config.json` file: ```json { "args": ["--no-sandbox"] } ``` And when you invoke `mmdc`: ```sh mmdc -p puppeteer-config.json ... ``` --- ## File: docs/reviewing.md # Reviewing a PR ## Running Percy Visual Inspection tests from a PR from a fork In order to run Percy visual inspection tests, a PR from a fork may have to be brought into the main repo. This is because uploading to Percy requires a GitHub Secret token, which cannot be accessed from forks for security reasons. After you have reviewed the work, and made sure there is no security exploit (e.g. no `echo "$TOKEN"`), then you can run the following to get percy working: ```bash git switch -c "" git pull "https://github.com//mermaid-cli.git" "" # Make sure the commit hash matches the commit hash of the PR you reviewed git log --max-count=1 git push git@github.com:mermaid-js/mermaid-cli.git "" ``` After pushing, CI should re-run on that commit, and Percy should show up on the PR after a few minutes, **as long as both branches have the same commit hash**.