2022-10-18 04:58:51 +02:00
> **Warning**
>
> ## THIS IS AN AUTOGENERATED FILE. DO NOT EDIT.
>
2023-08-23 22:38:06 +02:00
> ## Please edit the corresponding file in [/packages/mermaid/src/docs/intro/getting-started.md](../../packages/mermaid/src/docs/intro/getting-started.md).
2022-09-03 09:35:47 +02:00
2023-12-04 22:47:20 +01:00
# Mermaid User Guide
2022-09-03 05:43:37 +02:00
2023-12-04 22:47:20 +01:00
## Mermaid is composed of three parts
2022-09-03 05:43:37 +02:00
2024-03-23 07:09:02 +01:00
1. Deployment
2. Syntax
3. Configuration
2022-09-03 05:43:37 +02:00
2023-12-04 22:47:20 +01:00
This section talks about the different ways to **deploy** Mermaid.
2022-09-03 05:43:37 +02:00
2023-12-04 22:47:20 +01:00
If you are a beginner:
2022-09-03 05:43:37 +02:00
2023-12-04 22:47:20 +01:00
- Check out the [Diagram Syntax ](syntax-reference.md ) page
2024-01-12 00:00:30 +01:00
- Check out the [Tutorials ](../ecosystem/tutorials.md ) page
2022-09-03 05:43:37 +02:00
2023-12-04 22:47:20 +01:00
## Ways to use Mermaid
2022-09-03 05:43:37 +02:00
2024-03-23 07:09:02 +01:00
1. [Using the Mermaid Live Editor ](getting-started.md#_1-using-the-mermaid-live-editor )
2. [Using the Mermaid Chart Editor ](getting-started.md#_2-using-the-mermaid-chart-editor )
3. [Using Mermaid Plugins and Integrations ](getting-started.md#_3-using-mermaid-plugins )
4. [Calling the Mermaid JavaScript API ](getting-started.md#_4-calling-the-mermaid-javascript-api )
5. [Adding Mermaid as a dependency ](getting-started.md#_5-adding-mermaid-as-a-dependency )
2022-09-03 05:43:37 +02:00
2023-12-04 22:47:20 +01:00
To learn more, visit the [Usage ](../config/usage.md ) page.
2022-09-03 05:43:37 +02:00
2023-12-19 21:16:01 +01:00
## 1. Using the Mermaid Live Editor
2022-09-03 05:43:37 +02:00
2023-12-04 22:47:20 +01:00
Available at the [Mermaid Live Editor ](https://mermaid.live ) website.
### Features
< br / >
#### • Diagram Code
In the `Code` panel, write or edit Mermaid code, and instantly `Preview` the rendered result in the diagram panel.
Here is an example of Mermaid code and its rendered result:
2022-09-03 05:43:37 +02:00
2022-10-15 05:50:11 +02:00
```mermaid-example
graph TD
A[Enter Chart Definition] --> B(Preview)
B --> C{decide}
C --> D[Keep]
C --> E[Edit Definition]
E --> B
D --> F[Save Image and Code]
F --> B
```
```mermaid
graph TD
A[Enter Chart Definition] --> B(Preview)
B --> C{decide}
C --> D[Keep]
C --> E[Edit Definition]
E --> B
D --> F[Save Image and Code]
F --> B
```
2022-09-03 05:43:37 +02:00
2023-12-04 22:47:20 +01:00
< br / >
#### • Configurations
2022-09-03 05:43:37 +02:00
2023-12-04 22:47:20 +01:00
Configuration options are available in the `Configuration` panel. The options are applied to the diagram in the `Preview` panel.
2024-01-11 23:41:00 +01:00
To learn more, visit the [Configuration Reference ](../config/setup/README.md ) page
2022-09-03 05:43:37 +02:00
![Code,Config and Preview ](./img/Code-Preview-Config.png )
2023-12-04 22:47:20 +01:00
< br / >
#### • Editing History
2022-09-03 05:43:37 +02:00
2023-12-04 22:47:20 +01:00
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.
2022-09-03 05:43:37 +02:00
2023-12-04 22:47:20 +01:00
Alternatively, you can manually save code by clicking on the `Save` icon from the `History` section.
2022-09-03 05:43:37 +02:00
2023-12-04 22:47:20 +01:00
> **Note**
> History is stored in the browser storage only.
2022-09-03 05:43:37 +02:00
2023-12-04 22:47:20 +01:00
< br / >
2022-09-03 05:43:37 +02:00
2023-12-04 22:47:20 +01:00
#### • Saving a diagram
2022-09-03 05:43:37 +02:00
2023-12-04 22:47:20 +01:00
There are multiple ways of saving your diagram from the `Actions` section:
- export PNG
- export SVG
- export as Markdown
2022-09-03 05:43:37 +02:00
![Flowchart ](./img/Live-Editor-Choices.png )
2023-12-04 22:47:20 +01:00
< br / >
#### • Editing your diagrams
To edit your diagram, you can copy paste existing Mermaid diagram code into the `Code` section of the `Live Editor` .
Or:
2022-09-03 05:43:37 +02:00
2023-12-04 22:47:20 +01:00
- create a new diagram from scratch
- use a Sample Diagram from the `Sample Diagrams` section
2022-09-03 05:43:37 +02:00
2023-12-04 22:47:20 +01:00
< br / >
2022-09-03 05:43:37 +02:00
2023-12-04 22:47:20 +01:00
#### • Loading from Gists
2022-09-03 05:43:37 +02:00
2023-12-04 22:47:20 +01:00
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 ).
2022-09-03 05:43:37 +02:00
2023-12-04 22:47:20 +01:00
> **Note**
> 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).
2022-09-03 05:43:37 +02:00
2023-12-04 22:47:20 +01:00
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.
2022-09-03 05:43:37 +02:00
2023-12-04 22:47:20 +01:00
Here is an example of a Gist being loaded into the Editor:
2022-09-03 05:43:37 +02:00
2023-12-04 22:47:20 +01:00
< https: / / mermaid . live / edit ? gist = https://gist.github.com/sidharthv96/6268a23e673a533dcb198f241fd7012a >
2022-09-03 05:43:37 +02:00
2023-12-04 22:47:20 +01:00
And, here is the diagram view from the above example:
2022-09-03 05:43:37 +02:00
2023-12-04 22:47:20 +01:00
< https: / / mermaid . live / view ? gist = https://gist.github.com/sidharthv96/6268a23e673a533dcb198f241fd7012a >
2022-09-03 05:43:37 +02:00
2023-12-19 21:16:01 +01:00
## 2. Using the Mermaid Chart Editor
2022-09-03 05:43:37 +02:00
2023-12-19 21:16:01 +01:00
Available at the [Mermaid Chart ](https://www.mermaidchart.com/ ) website.
2022-09-03 05:43:37 +02:00
2023-12-19 21:16:01 +01:00
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.
2022-09-03 05:43:37 +02:00
2023-12-19 21:16:01 +01:00
Features include:
2022-09-03 05:43:37 +02:00
2023-12-19 21:16:01 +01:00
- AI diagramming
- Collaboration & multi-user editing
- Storage
- and more
2022-09-03 05:43:37 +02:00
2023-12-19 21:16:01 +01:00
To learn more, visit the [Mermaid Chart page ](/ecosystem/mermaid-chart.html ) in the Ecosystem section of the documentation.
2022-09-03 05:43:37 +02:00
2023-12-19 21:16:01 +01:00
Or go to the [Mermaid Chart website ](https://www.mermaidchart.com/app/sign-up ) to sign up for a Free account.
2022-09-03 05:43:37 +02:00
2023-12-04 22:47:20 +01:00
## 3. Using Mermaid Plugins
2022-09-03 05:43:37 +02:00
2023-12-04 22:47:20 +01:00
### Mermaid Plugins
2022-09-03 05:43:37 +02:00
2023-12-04 22:47:20 +01:00
You can generate Mermaid diagrams from within popular applications using plug-ins.
For a list of Mermaid Plugins and Integrations, visit the [Integrations page ](../ecosystem/integrations-community.md ).
### Mermaid Chart Plugins
Mermaid Chart plugins are available for:
2024-05-16 10:51:44 +02:00
- [ChatGPT ](https://docs.mermaidchart.com/plugins/mermaid-chart-gpt )
2023-12-04 22:47:20 +01:00
- [JetBrains IDE ](https://docs.mermaidchart.com/plugins/jetbrains-ide )
2023-12-19 21:16:01 +01:00
- [Microsoft PowerPoint ](https://docs.mermaidchart.com/plugins/microsoft-powerpoint )
- [Microsoft Word ](https://docs.mermaidchart.com/plugins/microsoft-word )
2023-12-04 22:47:20 +01:00
- [Visual Studio Code ](https://docs.mermaidchart.com/plugins/visual-studio-code )
To learn more, visit the [Mermaid Chart Plugins ](https://www.mermaidchart.com/plugins ) page.
2023-12-19 21:16:01 +01:00
### Native Mermaid Support
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.
````markdown
The following code-block will be rendered as a Mermaid diagram:
```mermaid
flowchart LR
A --> B
```
````
2023-12-04 22:47:20 +01:00
## 4. Calling the Mermaid JavaScript API
This method can be used with any common web server like `Apache` , `IIS` , `Nginx` , and `Node Express` .
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` .
> **Note**
> Internet Explorer is not supported.
2022-09-03 05:43:37 +02:00
The API works by pulling rendering instructions from the source `mermaid.js` in order to render diagrams on the page.
2023-12-04 22:47:20 +01:00
### Requirements for the Mermaid API
When writing the `html` file, we give two instructions inside the `html code` to the `web browser` :
2022-09-03 05:43:37 +02:00
2023-12-04 22:47:20 +01:00
a. The Mermaid code for the diagram we want to create.
2022-09-03 05:43:37 +02:00
2023-12-04 22:47:20 +01:00
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.
2022-09-03 05:43:37 +02:00
2023-12-04 22:47:20 +01:00
#### Examples
2022-09-03 05:43:37 +02:00
2023-12-04 22:47:20 +01:00
- This is an example of an embedded Mermaid diagram definition inside a `<pre class="mermaid">` :
2022-09-03 05:43:37 +02:00
```html
< body >
2022-09-03 10:00:16 +02:00
Here is a mermaid diagram:
2022-09-04 21:55:28 +02:00
< pre class = "mermaid" >
2023-08-28 10:43:20 +02:00
graph TD
A[Client] --> B[Load Balancer]
B --> C[Server01]
2022-09-04 21:55:28 +02:00
B --> D[Server02]
< / pre >
2022-09-03 05:43:37 +02:00
< / body >
```
2023-12-04 22:47:20 +01:00
> **Note**
> Every Mermaid chart/graph/diagram definition should have separate `<pre>` tags.
2022-09-03 05:43:37 +02:00
2023-12-04 22:47:20 +01:00
- This is an example of a Mermaid import and the `mermaid.initialize()` call.
2022-09-03 05:43:37 +02:00
2023-12-04 22:47:20 +01:00
> **Note**
> A `mermaid.initialize()` call takes all the definitions contained within `<pre class="mermaid">` tags and renders them into diagrams.
2022-09-03 05:43:37 +02:00
```html
< body >
2022-10-08 03:27:19 +02:00
< script type = "module" >
2023-08-13 15:03:41 +02:00
import mermaid from 'https://cdn.jsdelivr.net/npm/mermaid@11/dist/mermaid.esm.min.mjs';
2022-09-03 10:00:16 +02:00
mermaid.initialize({ startOnLoad: true });
< / script >
2022-09-03 05:43:37 +02:00
< / body >
```
2023-12-04 22:47:20 +01:00
> **Note**
> 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.
2022-09-03 05:43:37 +02:00
`startOnLoad` is one of the parameters that can be defined by `mermaid.initialize()`
| Parameter | Description | Type | Values |
| ----------- | --------------------------------- | ------- | ----------- |
| startOnLoad | Toggle for Rendering upon loading | Boolean | true, false |
2023-12-04 22:47:20 +01:00
In this example, the `mermaidAPI` is being called through the `CDN` :
2022-09-03 05:43:37 +02:00
```html
< html >
2022-09-03 10:00:16 +02:00
< body >
Here is one mermaid diagram:
2022-09-04 21:55:28 +02:00
< pre class = "mermaid" >
2023-08-28 10:43:20 +02:00
graph TD
A[Client] --> B[Load Balancer]
B --> C[Server1]
2022-09-04 21:55:28 +02:00
B --> D[Server2]
< / pre >
2022-09-03 10:00:16 +02:00
And here is another:
2022-09-04 21:55:28 +02:00
< pre class = "mermaid" >
2023-08-28 10:43:20 +02:00
graph TD
2022-09-04 21:55:28 +02:00
A[Client] -->|tcp_123| B
2023-08-28 10:43:20 +02:00
B(Load Balancer)
B -->|tcp_456| C[Server1]
2022-09-04 21:55:28 +02:00
B -->|tcp_456| D[Server2]
< / pre >
2022-10-08 03:27:19 +02:00
< script type = "module" >
2023-08-13 15:03:41 +02:00
import mermaid from 'https://cdn.jsdelivr.net/npm/mermaid@11/dist/mermaid.esm.min.mjs';
2022-10-08 03:27:19 +02:00
mermaid.initialize({ startOnLoad: true });
< / script >
2022-09-03 10:00:16 +02:00
< / body >
2022-09-03 05:43:37 +02:00
< / html >
```
2023-12-04 22:47:20 +01:00
In this example, `mermaid.js` is referenced in `src` as a separate JavaScript file:
2022-09-03 05:43:37 +02:00
```html
< html lang = "en" >
2022-09-03 10:00:16 +02:00
< head >
< meta charset = "utf-8" / >
< / head >
< body >
2022-09-04 21:55:28 +02:00
< pre class = "mermaid" >
2023-08-28 10:43:20 +02:00
graph LR
A --- B
B-->C[fa:fa-ban forbidden]
2022-09-04 21:55:28 +02:00
B-->D(fa:fa-spinner);
< / pre >
< pre class = "mermaid" >
2023-08-28 10:43:20 +02:00
graph TD
A[Client] --> B[Load Balancer]
B --> C[Server1]
2022-09-04 21:55:28 +02:00
B --> D[Server2]
< / pre >
2022-10-08 03:27:19 +02:00
< script type = "module" >
2022-10-08 13:20:06 +02:00
import mermaid from 'The/Path/In/Your/Package/mermaid.esm.mjs';
2022-09-03 10:00:16 +02:00
mermaid.initialize({ startOnLoad: true });
< / script >
< / body >
2022-09-03 05:43:37 +02:00
< / html >
```
2023-12-04 22:47:20 +01:00
## 5. Adding Mermaid as a dependency
2022-09-03 05:43:37 +02:00
2023-12-04 22:47:20 +01:00
Below are the steps for adding Mermaid as a dependency:
2022-09-03 05:43:37 +02:00
2024-03-23 07:09:02 +01:00
1. Install `node v16`
2022-09-03 05:43:37 +02:00
2023-12-04 22:47:20 +01:00
> **Note**
> 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).
2022-09-03 05:43:37 +02:00
2024-03-23 07:09:02 +01:00
1. Install `yarn` using `npm` with this command:
2022-09-03 05:43:37 +02:00
2024-03-23 07:09:02 +01:00
`npm install -g yarn`
2022-09-03 05:43:37 +02:00
2024-03-23 07:09:02 +01:00
2. After yarn installs, enter this command:
2022-09-03 05:43:37 +02:00
2024-03-23 07:09:02 +01:00
`yarn add mermaid`
2022-09-03 05:43:37 +02:00
2024-03-23 07:09:02 +01:00
3. To add Mermaid as a dev dependency, enter this command:
2023-12-04 22:47:20 +01:00
2024-03-23 07:09:02 +01:00
`yarn add --dev mermaid`
2023-12-04 22:47:20 +01:00
## Closing note
> **Note**
> Comments from Knut Sveidqvist, creator of Mermaid:
>
> - 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.