|
1 | | -# mermaid-cli |
| 1 | +# visio2mermaid |
2 | 2 |
|
3 | | -[](https://www.npmjs.com/package/@mermaid-js/mermaid-cli) |
4 | | -[](https://www.npmjs.com/package/@mermaid-js/mermaid-cli) |
5 | | -[](https://hub.docker.com/r/minlag/mermaid-cli) |
6 | | -[](https://github.com/mermaid-js/mermaid-cli/actions/workflows/compile-mermaid.yml) |
7 | | -[](https://percy.io/Mermaid/mermaid-cli) |
8 | | -[](https://join.slack.com/t/mermaid-talk/shared_invite/enQtNzc4NDIyNzk4OTAyLWVhYjQxOTI2OTg4YmE1ZmJkY2Y4MTU3ODliYmIwOTY3NDJlYjA0YjIyZTdkMDMyZTUwOGI0NjEzYmEwODcwOTE) |
9 | | - |
10 | | -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. |
| 3 | +This is a command-line interface (CLI) to export a diagram from Visio to [mermaid](https://mermaid.js.org/). It takes a Visio vsdx file as input, and will generate the corresponding mermaid syntax into a .mmd file or direct output. |
11 | 4 |
|
12 | 5 | ## Installation |
13 | | - |
14 | | -```sh |
15 | | -npm install -g @mermaid-js/mermaid-cli |
16 | | -``` |
17 | | - |
18 | | -## Usage |
19 | | - |
20 | | -Convert Mermaid mmd Diagram File To SVG |
21 | | - |
22 | | -```sh |
23 | | -mmdc -i input.mmd -o output.svg |
24 | | -``` |
25 | | - |
26 | | -> **Note** |
27 | | -> |
28 | | -> See [Alternative installations](#alternative-installations) if you don't want to install the package globally. |
29 | | -> |
30 | | -> Locate how to call the mmdc executable for your preferred method |
31 | | -> i.e. Docker, Yarn, NPM, local install, etc. |
32 | | -
|
33 | | -## Examples |
34 | | - |
35 | | -### Create A PNG With A Dark Theme And Transparent Background |
36 | | - |
37 | | -```sh |
38 | | -mmdc -i input.mmd -o output.png -t dark -b transparent |
39 | | -``` |
40 | | - |
41 | | -### Animating an SVG file with custom CSS |
42 | | - |
43 | | -The `--cssFile` option can be used to inline some custom CSS. |
44 | | - |
45 | | -Please see [./test-positive/flowchart1.css](test-positive/flowchart1.css) for an example of a CSS file that has animations. |
46 | | - |
47 | | -**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 mermiad's `themeCSS`. |
48 | | - |
49 | | -**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. |
50 | | - |
51 | | -```sh |
52 | | -mmdc --input test-positive/flowchart1.mmd --cssFile test-positive/flowchart1.css -o docs/animated-flowchart.svg |
53 | | -``` |
54 | | - |
55 | | -<details> |
56 | | - <summary>Example output: docs/animated-flowchart.svg</summary> |
57 | | - |
58 | | -  |
59 | | -</details> |
60 | | - |
61 | | -### Transform a markdown file with mermaid diagrams |
62 | | - |
63 | | -```sh |
64 | | -mmdc -i readme.template.md -o readme.md |
65 | | -``` |
66 | | - |
67 | | -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. |
68 | | - |
69 | | -This: |
70 | | - |
71 | | -~~~md |
72 | | -### Some markdown |
73 | | -```mermaid |
74 | | -graph |
75 | | - [....] |
76 | | -``` |
77 | | - |
78 | | -### Some more markdown |
79 | | -```mermaid |
80 | | -sequenceDiagram |
81 | | - [....] |
82 | | -``` |
83 | | - |
84 | | -### Mermaid with custom title/desc |
85 | | -```mermaid |
86 | | -graph |
87 | | - accTitle: My title here |
88 | | - accDescr: My description here |
89 | | - A-->B |
90 | | -``` |
91 | | -~~~ |
92 | | - |
93 | | -Becomes: |
94 | | - |
95 | | -```md |
96 | | -### Some markdown |
97 | | - |
98 | | - |
99 | | -### Some more markdown |
100 | | - |
101 | | - |
102 | | -### Mermaid with custom title/desc |
103 | | - |
104 | | -``` |
105 | | - |
106 | | -### Piping from stdin |
107 | | - |
108 | | -You can easily pipe input from stdin. This example shows how to use a heredoc to |
109 | | -send a diagram as stdin to mermaid-cli (mmdc). |
110 | | - |
111 | | -```sh |
112 | | -cat << EOF | mmdc --input - |
113 | | - graph TD |
114 | | - A[Client] --> B[Load Balancer] |
115 | | -EOF |
116 | | -``` |
117 | | - |
118 | | -### See All Available Options |
119 | | - |
120 | | -```sh |
121 | | -mmdc -h |
122 | | -``` |
123 | | - |
124 | | -# Alternative installations |
125 | | - |
126 | | -## Use Docker/Podman: |
127 | | - |
128 | | -```sh |
129 | | -docker pull minlag/mermaid-cli |
130 | | -``` |
131 | | - |
132 | | -or pull from Github Container Registry |
133 | | - |
134 | | -```sh |
135 | | -docker pull ghcr.io/mermaid-js/mermaid-cli/mermaid-cli |
136 | | -``` |
137 | | - |
138 | | -or e.g. version 8.8.0 |
139 | | - |
140 | | -```sh |
141 | | -docker pull minlag/mermaid-cli:8.8.0 |
142 | | -``` |
143 | | - |
144 | | -The container looks for input files in `/data`. So for example, if you have a |
145 | | -diagram defined on your system in `/path/to/diagrams/diagram.mmd`, you can use |
146 | | -the container to generate an SVG file as follows: |
147 | | - |
148 | | -```sh |
149 | | -docker run --rm -u `id -u`:`id -g` -v /path/to/diagrams:/data minlag/mermaid-cli -i diagram.mmd |
150 | | -``` |
151 | | - |
152 | | -Or, if using [Podman](https://podman.io/), instead do: |
153 | | - |
154 | | -```sh |
155 | | -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 |
156 | | -``` |
157 | | - |
158 | | -The key differences in the podman command versus the docker command are: |
159 | | - |
160 | | -- 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](https://docs.podman.io/en/latest/markdown/options/userns.container.html) |
161 | | -- 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](https://docs.podman.io/en/latest/markdown/podman-run.1.html#volume-v-source-volume-host-dir-container-dir-options) for more info. |
162 | | - |
163 | | -In previous version, the input files were mounted in `/home/mermaidcli`. You can |
164 | | -restore this behaviour with the `--workdir` option: |
165 | | - |
166 | | -```sh |
167 | | -docker run [...] --workdir=/home/mermaidcli minlag/mermaid-cli [...] |
168 | | -``` |
169 | | - |
170 | | - |
171 | | -## Use Node.JS API |
172 | | - |
173 | | -It's possible to call `mermaid-cli` via a Node.JS API. |
174 | | -Please be aware that **the NodeJS API is not covered by semver**, as `mermaid-cli` follows |
175 | | -`mermaid`'s versioning. |
176 | | - |
177 | | -```js |
178 | | -import { run } from "@mermaid-js/mermaid-cli" |
179 | | - |
180 | | -await run( |
181 | | - "input.mmd", "output.svg", // {optional options}, |
182 | | -) |
183 | | -``` |
184 | | - |
185 | | -## Install locally |
186 | | - |
187 | | -Some people are [having issues](https://github.com/mermaidjs/mermaid.cli/issues/15) |
188 | | -installing this tool globally. Installing it locally is an alternative solution: |
189 | | - |
190 | | -``` |
191 | | -npm install @mermaid-js/mermaid-cli |
192 | | -./node_modules/.bin/mmdc -h |
193 | | -``` |
194 | | - |
195 | | -Or use NPM: |
196 | | - |
197 | | -``` |
198 | | -npm install @mermaid-js/mermaid-cli |
199 | | -./node_modules/.bin/mmdc -h |
200 | | -``` |
201 | | - |
202 | | -### Run with npx |
203 | | - |
204 | | -[`npx`](https://www.npmjs.com/package/npx) is installed by default with NPM. It |
205 | | -downloads and runs commands at the same time. To use Mermaid CLI with npx, you |
206 | | -need to use the `-p` flag because the package name is different than the command |
207 | | -it installs (`mmdc`). `npx -p @mermaid-js/mermaid-cli mmdc -h` |
208 | | - |
209 | | - |
210 | | -## Install with [brew](https://brew.sh) |
211 | | - |
212 | | -> **Warning** |
213 | | -> |
214 | | -> This method of installation is no longer supported. |
215 | | -> For more details, see the [discussion](https://github.com/mermaid-js/mermaid-cli/issues/288). |
216 | | -> An old version of mermaid-cli can be installed with brew. |
217 | | -> ```sh |
218 | | -> brew install mermaid-cli |
219 | | -> ``` |
220 | | -
|
221 | | -
|
222 | | -## Known issues |
223 | | -
|
224 | | -1. [Linux sandbox issue](docs/linux-sandbox-issue.md) |
225 | | -2. [Docker permission denied issue](docs/docker-permission-denied.md) |
226 | | -3. [How to setup up mermaid to use already installed chromium?](docs/already-installed-chromium.md) |
227 | | -
|
228 | | -## For contributors |
229 | | -
|
230 | | -Contributions are welcome. See the [contribution guide](CONTRIBUTING.md). |
0 commit comments