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