| 6dd74de | | | 1 | > **Warning** |
| 6dd74de | | | 2 | > |
| 6dd74de | | | 3 | > ## THIS IS AN AUTOGENERATED FILE. DO NOT EDIT. |
| 6dd74de | | | 4 | > |
| 6dd74de | | | 5 | > ## Please edit the corresponding file in [/packages/mermaid/src/docs/intro/getting-started.md](../../packages/mermaid/src/docs/intro/getting-started.md). |
| 6dd74de | | | 6 | |
| 6dd74de | | | 7 | # Mermaid User Guide |
| 6dd74de | | | 8 | |
| 6dd74de | | | 9 | ## Mermaid is composed of three parts |
| 6dd74de | | | 10 | |
| 6dd74de | | | 11 | 1. Deployment |
| 6dd74de | | | 12 | 2. Syntax |
| 6dd74de | | | 13 | 3. Configuration |
| 6dd74de | | | 14 | |
| 6dd74de | | | 15 | This section talks about the different ways to **deploy** Mermaid. |
| 6dd74de | | | 16 | |
| 6dd74de | | | 17 | If you are a beginner: |
| 6dd74de | | | 18 | |
| 6dd74de | | | 19 | - Check out the [Diagram Syntax](syntax-reference.md) page |
| 6dd74de | | | 20 | - Check out the [Tutorials](../ecosystem/tutorials.md) page |
| 6dd74de | | | 21 | |
| 6dd74de | | | 22 | ## Ways to use Mermaid |
| 6dd74de | | | 23 | |
| 6dd74de | | | 24 | 1. [Using the Mermaid Live Editor](getting-started.md#_1-using-the-mermaid-live-editor) |
| 6dd74de | | | 25 | 2. [Using the Mermaid Chart Editor](getting-started.md#_2-using-the-mermaid-chart-editor) |
| 6dd74de | | | 26 | 3. [Using Mermaid Plugins and Integrations](getting-started.md#_3-using-mermaid-plugins) |
| 6dd74de | | | 27 | 4. [Calling the Mermaid JavaScript API](getting-started.md#_4-calling-the-mermaid-javascript-api) |
| 6dd74de | | | 28 | 5. [Adding Mermaid as a dependency](getting-started.md#_5-adding-mermaid-as-a-dependency) |
| 6dd74de | | | 29 | |
| 6dd74de | | | 30 | To learn more, visit the [Usage](../config/usage.md) page. |
| 6dd74de | | | 31 | |
| 6dd74de | | | 32 | ## 1. Using the Mermaid Live Editor |
| 6dd74de | | | 33 | |
| 6dd74de | | | 34 | Available at the [Mermaid Live Editor](https://mermaid.live) website. |
| 6dd74de | | | 35 | |
| 6dd74de | | | 36 | ### Features |
| 6dd74de | | | 37 | |
| 6dd74de | | | 38 | <br /> |
| 6dd74de | | | 39 | |
| 6dd74de | | | 40 | #### • Diagram Code |
| 6dd74de | | | 41 | |
| 6dd74de | | | 42 | In the `Code` panel, write or edit Mermaid code, and instantly `Preview` the rendered result in the diagram panel. |
| 6dd74de | | | 43 | |
| 6dd74de | | | 44 | Here is an example of Mermaid code and its rendered result: |
| 6dd74de | | | 45 | |
| 6dd74de | | | 46 | ```mermaid-example |
| 6dd74de | | | 47 | graph TD |
| 6dd74de | | | 48 | A[Enter Chart Definition] --> B(Preview) |
| 6dd74de | | | 49 | B --> C{decide} |
| 6dd74de | | | 50 | C --> D[Keep] |
| 6dd74de | | | 51 | C --> E[Edit Definition] |
| 6dd74de | | | 52 | E --> B |
| 6dd74de | | | 53 | D --> F[Save Image and Code] |
| 6dd74de | | | 54 | F --> B |
| 6dd74de | | | 55 | ``` |
| 6dd74de | | | 56 | |
| 6dd74de | | | 57 | ```mermaid |
| 6dd74de | | | 58 | graph TD |
| 6dd74de | | | 59 | A[Enter Chart Definition] --> B(Preview) |
| 6dd74de | | | 60 | B --> C{decide} |
| 6dd74de | | | 61 | C --> D[Keep] |
| 6dd74de | | | 62 | C --> E[Edit Definition] |
| 6dd74de | | | 63 | E --> B |
| 6dd74de | | | 64 | D --> F[Save Image and Code] |
| 6dd74de | | | 65 | F --> B |
| 6dd74de | | | 66 | ``` |
| 6dd74de | | | 67 | |
| 6dd74de | | | 68 | <br /> |
| 6dd74de | | | 69 | |
| 6dd74de | | | 70 | #### • Configurations |
| 6dd74de | | | 71 | |
| 6dd74de | | | 72 | Configuration options are available in the `Configuration` panel. The options are applied to the diagram in the `Preview` panel. |
| 6dd74de | | | 73 | |
| 6dd74de | | | 74 | To learn more, visit the [Configuration Reference](../config/setup/README.md) page |
| 6dd74de | | | 75 | |
| 6dd74de | | | 76 |  |
| 6dd74de | | | 77 | |
| 6dd74de | | | 78 | <br /> |
| 6dd74de | | | 79 | |
| 6dd74de | | | 80 | #### • Editing History |
| 6dd74de | | | 81 | |
| 6dd74de | | | 82 | Your code will be autosaved and appear in the `Timeline` tab of the `History` section. Edits are saved every minute and only the last 30 edits are viewable. |
| 6dd74de | | | 83 | |
| 6dd74de | | | 84 | Alternatively, you can manually save code by clicking on the `Save` icon from the `History` section. |
| 6dd74de | | | 85 | |
| 6dd74de | | | 86 | > **Note** |
| 6dd74de | | | 87 | > History is stored in the browser storage only. |
| 6dd74de | | | 88 | |
| 6dd74de | | | 89 | <br /> |
| 6dd74de | | | 90 | |
| 6dd74de | | | 91 | #### • Saving a diagram |
| 6dd74de | | | 92 | |
| 6dd74de | | | 93 | There are multiple ways of saving your diagram from the `Actions` section: |
| 6dd74de | | | 94 | |
| 6dd74de | | | 95 | - export PNG |
| 6dd74de | | | 96 | - export SVG |
| 6dd74de | | | 97 | - export as Markdown |
| 6dd74de | | | 98 | |
| 6dd74de | | | 99 |  |
| 6dd74de | | | 100 | |
| 6dd74de | | | 101 | <br /> |
| 6dd74de | | | 102 | |
| 6dd74de | | | 103 | #### • Editing your diagrams |
| 6dd74de | | | 104 | |
| 6dd74de | | | 105 | To edit your diagram, you can copy paste existing Mermaid diagram code into the `Code` section of the `Live Editor`. |
| 6dd74de | | | 106 | |
| 6dd74de | | | 107 | Or: |
| 6dd74de | | | 108 | |
| 6dd74de | | | 109 | - create a new diagram from scratch |
| 6dd74de | | | 110 | - use a Sample Diagram from the `Sample Diagrams` section |
| 6dd74de | | | 111 | |
| 6dd74de | | | 112 | <br /> |
| 6dd74de | | | 113 | |
| 6dd74de | | | 114 | #### • Loading from Gists |
| 6dd74de | | | 115 | |
| 6dd74de | | | 116 | The Gist you create should have a `code.mmd` file and optionally a `config.json`, similar to this [example](https://gist.github.com/sidharthv96/6268a23e673a533dcb198f241fd7012a). |
| 6dd74de | | | 117 | |
| 6dd74de | | | 118 | > **Note** |
| 6dd74de | | | 119 | > To learn about Gists, visit the GitHub documentation page on [Creating gists](https://docs.github.com/en/get-started/writing-on-github/editing-and-sharing-content-with-gists/creating-gists). |
| 6dd74de | | | 120 | |
| 6dd74de | | | 121 | Once you have created a Gist, copy paste the Gist URL into the respective field in the `Actions` section and click on the `Load Gist` button. |
| 6dd74de | | | 122 | |
| 6dd74de | | | 123 | Here is an example of a Gist being loaded into the Editor: |
| 6dd74de | | | 124 | |
| 6dd74de | | | 125 | <https://mermaid.live/edit?gist=https://gist.github.com/sidharthv96/6268a23e673a533dcb198f241fd7012a> |
| 6dd74de | | | 126 | |
| 6dd74de | | | 127 | And, here is the diagram view from the above example: |
| 6dd74de | | | 128 | |
| 6dd74de | | | 129 | <https://mermaid.live/view?gist=https://gist.github.com/sidharthv96/6268a23e673a533dcb198f241fd7012a> |
| 6dd74de | | | 130 | |
| 6dd74de | | | 131 | ## 2. Using the Mermaid Chart Editor |
| 6dd74de | | | 132 | |
| 6dd74de | | | 133 | Available at the [Mermaid Chart](https://mermaid.ai/) website. |
| 6dd74de | | | 134 | |
| 6dd74de | | | 135 | Mermaid Chart is a web-based diagram editor that allows you to create and edit diagrams in your browser. It is built by the team behind Mermaid. |
| 6dd74de | | | 136 | |
| 6dd74de | | | 137 | Features include: |
| 6dd74de | | | 138 | |
| 6dd74de | | | 139 | - AI diagramming |
| 6dd74de | | | 140 | - Collaboration & multi-user editing |
| 6dd74de | | | 141 | - Storage |
| 6dd74de | | | 142 | - and more |
| 6dd74de | | | 143 | |
| 6dd74de | | | 144 | To learn more, visit the [Mermaid Chart page](/ecosystem/mermaid-chart.html) in the Ecosystem section of the documentation. |
| 6dd74de | | | 145 | |
| 6dd74de | | | 146 | Or go to the [Mermaid Chart website](https://mermaid.ai/app/sign-up) to sign up for a Free account. |
| 6dd74de | | | 147 | |
| 6dd74de | | | 148 | ## 3. Using Mermaid Plugins |
| 6dd74de | | | 149 | |
| 6dd74de | | | 150 | ### Mermaid Plugins |
| 6dd74de | | | 151 | |
| 6dd74de | | | 152 | You can generate Mermaid diagrams from within popular applications using plug-ins. |
| 6dd74de | | | 153 | |
| 6dd74de | | | 154 | For a list of Mermaid Plugins and Integrations, visit the [Integrations page](../ecosystem/integrations-community.md). |
| 6dd74de | | | 155 | |
| 6dd74de | | | 156 | ### Mermaid Chart Plugins |
| 6dd74de | | | 157 | |
| 6dd74de | | | 158 | Mermaid Chart plugins are available for: |
| 6dd74de | | | 159 | |
| 6dd74de | | | 160 | - [ChatGPT](https://mermaid.ai/docs/plugins/mermaid-chart-gpt) |
| 6dd74de | | | 161 | - [JetBrains IDE](https://mermaid.ai/docs/plugins/jetbrains-ide) |
| 6dd74de | | | 162 | - [Microsoft PowerPoint](https://mermaid.ai/docs/plugins/microsoft-powerpoint) |
| 6dd74de | | | 163 | - [Microsoft Word](https://mermaid.ai/docs/plugins/microsoft-word) |
| 6dd74de | | | 164 | - [Visual Studio Code](https://mermaid.ai/docs/plugins/visual-studio-code) |
| 6dd74de | | | 165 | |
| 6dd74de | | | 166 | To learn more, visit the [Mermaid Chart Plugins](https://mermaid.ai/plugins) page. |
| 6dd74de | | | 167 | |
| 6dd74de | | | 168 | ### Native Mermaid Support |
| 6dd74de | | | 169 | |
| 6dd74de | | | 170 | For apps that support markdown (e.g. [GitHub](https://docs.github.com/en/get-started/writing-on-github/working-with-advanced-formatting/creating-diagrams) and [GitLab](https://handbook.gitlab.com/handbook/tools-and-tips/mermaid/)), you can add Mermaid diagrams by making a `mermaid` code block. |
| 6dd74de | | | 171 | |
| 6dd74de | | | 172 | ````markdown |
| 6dd74de | | | 173 | The following code-block will be rendered as a Mermaid diagram: |
| 6dd74de | | | 174 | |
| 6dd74de | | | 175 | ```mermaid |
| 6dd74de | | | 176 | flowchart LR |
| 6dd74de | | | 177 | A --> B |
| 6dd74de | | | 178 | ``` |
| 6dd74de | | | 179 | ```` |
| 6dd74de | | | 180 | |
| 6dd74de | | | 181 | ## 4. Calling the Mermaid JavaScript API |
| 6dd74de | | | 182 | |
| 6dd74de | | | 183 | This method can be used with any common web server like `Apache`, `IIS`, `Nginx`, and `Node Express`. |
| 6dd74de | | | 184 | |
| 6dd74de | | | 185 | You will also need a text editing tool like `Notepad++` to generate an `html` file. It is then deployed by a web browser, i.e. `Firefox`, `Chrome`, `Safari`. |
| 6dd74de | | | 186 | |
| 6dd74de | | | 187 | > **Note** |
| 6dd74de | | | 188 | > Internet Explorer is not supported. |
| 6dd74de | | | 189 | |
| 6dd74de | | | 190 | The API works by pulling rendering instructions from the source `mermaid.js` in order to render diagrams on the page. |
| 6dd74de | | | 191 | |
| 6dd74de | | | 192 | ### Requirements for the Mermaid API |
| 6dd74de | | | 193 | |
| 6dd74de | | | 194 | When writing the `html` file, we give two instructions inside the `html code` to the `web browser`: |
| 6dd74de | | | 195 | |
| 6dd74de | | | 196 | a. The Mermaid code for the diagram we want to create. |
| 6dd74de | | | 197 | |
| 6dd74de | | | 198 | b. The importing of the Mermaid library through the `mermaid.esm.mjs` or `mermaid.esm.min.mjs`, and the `mermaid.initialize()` call, which dictates the appearance of diagrams and also starts the rendering process. |
| 6dd74de | | | 199 | |
| 6dd74de | | | 200 | #### Examples |
| 6dd74de | | | 201 | |
| 6dd74de | | | 202 | - This is an example of an embedded Mermaid diagram definition inside a `<pre class="mermaid">`: |
| 6dd74de | | | 203 | |
| 6dd74de | | | 204 | ```html |
| 6dd74de | | | 205 | <body> |
| 6dd74de | | | 206 | Here is a mermaid diagram: |
| 6dd74de | | | 207 | <pre class="mermaid"> |
| 6dd74de | | | 208 | graph TD |
| 6dd74de | | | 209 | A[Client] --> B[Load Balancer] |
| 6dd74de | | | 210 | B --> C[Server01] |
| 6dd74de | | | 211 | B --> D[Server02] |
| 6dd74de | | | 212 | </pre> |
| 6dd74de | | | 213 | </body> |
| 6dd74de | | | 214 | ``` |
| 6dd74de | | | 215 | |
| 6dd74de | | | 216 | > **Note** |
| 6dd74de | | | 217 | > Every Mermaid chart/graph/diagram definition should have separate `<pre>` tags. |
| 6dd74de | | | 218 | |
| 6dd74de | | | 219 | - This is an example of a Mermaid import and the `mermaid.initialize()` call. |
| 6dd74de | | | 220 | |
| 6dd74de | | | 221 | > **Note** |
| 6dd74de | | | 222 | > A `mermaid.initialize()` call takes all the definitions contained within `<pre class="mermaid">` tags and renders them into diagrams. |
| 6dd74de | | | 223 | |
| 6dd74de | | | 224 | ```html |
| 6dd74de | | | 225 | <body> |
| 6dd74de | | | 226 | <script type="module"> |
| 6dd74de | | | 227 | import mermaid from 'https://cdn.jsdelivr.net/npm/mermaid@11/dist/mermaid.esm.min.mjs'; |
| 6dd74de | | | 228 | mermaid.initialize({ startOnLoad: true }); |
| 6dd74de | | | 229 | </script> |
| 6dd74de | | | 230 | </body> |
| 6dd74de | | | 231 | ``` |
| 6dd74de | | | 232 | |
| 6dd74de | | | 233 | > **Note** |
| 6dd74de | | | 234 | > Rendering in Mermaid is initialized by the `mermaid.initialize()` call. However, doing the opposite lets you control when it starts looking for `<pre>` tags inside the web page with `mermaid.initialize()`. This is useful when you think that not all `<pre>` tags may have loaded on the execution of `mermaid.esm.min.mjs` file. |
| 6dd74de | | | 235 | |
| 6dd74de | | | 236 | `startOnLoad` is one of the parameters that can be defined by `mermaid.initialize()` |
| 6dd74de | | | 237 | |
| 6dd74de | | | 238 | | Parameter | Description | Type | Values | |
| 6dd74de | | | 239 | | ----------- | --------------------------------- | ------- | ----------- | |
| 6dd74de | | | 240 | | startOnLoad | Toggle for Rendering upon loading | Boolean | true, false | |
| 6dd74de | | | 241 | |
| 6dd74de | | | 242 | In this example, the `mermaidAPI` is being called through the `CDN`: |
| 6dd74de | | | 243 | |
| 6dd74de | | | 244 | ```html |
| 6dd74de | | | 245 | <html> |
| 6dd74de | | | 246 | <body> |
| 6dd74de | | | 247 | Here is one mermaid diagram: |
| 6dd74de | | | 248 | <pre class="mermaid"> |
| 6dd74de | | | 249 | graph TD |
| 6dd74de | | | 250 | A[Client] --> B[Load Balancer] |
| 6dd74de | | | 251 | B --> C[Server1] |
| 6dd74de | | | 252 | B --> D[Server2] |
| 6dd74de | | | 253 | </pre> |
| 6dd74de | | | 254 | |
| 6dd74de | | | 255 | And here is another: |
| 6dd74de | | | 256 | <pre class="mermaid"> |
| 6dd74de | | | 257 | graph TD |
| 6dd74de | | | 258 | A[Client] -->|tcp_123| B |
| 6dd74de | | | 259 | B(Load Balancer) |
| 6dd74de | | | 260 | B -->|tcp_456| C[Server1] |
| 6dd74de | | | 261 | B -->|tcp_456| D[Server2] |
| 6dd74de | | | 262 | </pre> |
| 6dd74de | | | 263 | |
| 6dd74de | | | 264 | <script type="module"> |
| 6dd74de | | | 265 | import mermaid from 'https://cdn.jsdelivr.net/npm/mermaid@11/dist/mermaid.esm.min.mjs'; |
| 6dd74de | | | 266 | mermaid.initialize({ startOnLoad: true }); |
| 6dd74de | | | 267 | </script> |
| 6dd74de | | | 268 | </body> |
| 6dd74de | | | 269 | </html> |
| 6dd74de | | | 270 | ``` |
| 6dd74de | | | 271 | |
| 6dd74de | | | 272 | In this example, `mermaid.js` is referenced in `src` as a separate JavaScript file: |
| 6dd74de | | | 273 | |
| 6dd74de | | | 274 | ```html |
| 6dd74de | | | 275 | <html lang="en"> |
| 6dd74de | | | 276 | <head> |
| 6dd74de | | | 277 | <meta charset="utf-8" /> |
| 6dd74de | | | 278 | </head> |
| 6dd74de | | | 279 | <body> |
| 6dd74de | | | 280 | <pre class="mermaid"> |
| 6dd74de | | | 281 | graph LR |
| 6dd74de | | | 282 | A --- B |
| 6dd74de | | | 283 | B-->C[fa:fa-ban forbidden] |
| 6dd74de | | | 284 | B-->D(fa:fa-spinner); |
| 6dd74de | | | 285 | </pre> |
| 6dd74de | | | 286 | <pre class="mermaid"> |
| 6dd74de | | | 287 | graph TD |
| 6dd74de | | | 288 | A[Client] --> B[Load Balancer] |
| 6dd74de | | | 289 | B --> C[Server1] |
| 6dd74de | | | 290 | B --> D[Server2] |
| 6dd74de | | | 291 | </pre> |
| 6dd74de | | | 292 | <script type="module"> |
| 6dd74de | | | 293 | import mermaid from 'The/Path/In/Your/Package/mermaid.esm.mjs'; |
| 6dd74de | | | 294 | mermaid.initialize({ startOnLoad: true }); |
| 6dd74de | | | 295 | </script> |
| 6dd74de | | | 296 | </body> |
| 6dd74de | | | 297 | </html> |
| 6dd74de | | | 298 | ``` |
| 6dd74de | | | 299 | |
| 6dd74de | | | 300 | ## 5. Adding Mermaid as a dependency |
| 6dd74de | | | 301 | |
| 6dd74de | | | 302 | Below are the steps for adding Mermaid as a dependency: |
| 6dd74de | | | 303 | |
| 6dd74de | | | 304 | 1. Install `node v16` |
| 6dd74de | | | 305 | |
| 6dd74de | | | 306 | > **Note** |
| 6dd74de | | | 307 | > To learn more about downloading and installing `Node.js` and `npm`, visit the [npm Docs website](https://docs.npmjs.com/downloading-and-installing-node-js-and-npm). |
| 6dd74de | | | 308 | |
| 6dd74de | | | 309 | 1. Install `yarn` using `npm` with this command: |
| 6dd74de | | | 310 | |
| 6dd74de | | | 311 | `npm install -g yarn` |
| 6dd74de | | | 312 | |
| 6dd74de | | | 313 | 2. After yarn installs, enter this command: |
| 6dd74de | | | 314 | |
| 6dd74de | | | 315 | `yarn add mermaid` |
| 6dd74de | | | 316 | |
| 6dd74de | | | 317 | 3. To add Mermaid as a dev dependency, enter this command: |
| 6dd74de | | | 318 | |
| 6dd74de | | | 319 | `yarn add --dev mermaid` |
| 6dd74de | | | 320 | |
| 6dd74de | | | 321 | ## Closing note |
| 6dd74de | | | 322 | |
| 6dd74de | | | 323 | > **Note** |
| 6dd74de | | | 324 | > Comments from Knut Sveidqvist, creator of Mermaid: |
| 6dd74de | | | 325 | > |
| 6dd74de | | | 326 | > - In early versions of Mermaid, the `<script>` tag was invoked in the `<head>` part of the web page. Nowadays, we can place it in the `<body>` as seen above. Older parts of the documentation frequently reflect the previous way, which still works. |