2021-03-13 08:42:01 +01:00
# A Mermaid User-Guide for Beginners
2019-11-07 23:15:53 +01:00
2021-09-29 18:48:46 +02:00
Mermaid is composed of three parts: Deployment, Syntax and Configuration.
2019-11-07 23:15:53 +01:00
2021-09-29 18:48:46 +02:00
This section talks about the different ways to deploy Mermaid. Learning the [Syntax ](./n00b-syntaxReference.md ) would be of great help to the beginner.
2021-05-01 00:18:06 +02:00
2021-07-06 22:41:06 +02:00
> Generally the live editor is enough for most general uses of mermaid, and is a good place to start learning.
2019-11-07 23:15:53 +01:00
2021-09-29 18:48:46 +02:00
**Absolute beginners are advised to view the Video [Tutorials ](./Tutorials.md ) on the Live Editor, to gain a better understanding of mermaid.**
2019-11-07 23:15:53 +01:00
2021-04-17 08:41:27 +02:00
## Four ways of using mermaid:
2021-07-06 22:41:06 +02:00
2021-09-28 11:26:13 +02:00
1. Using the Mermaid Live Editor at [mermaid.live ](https://mermaid.live ).
2021-03-14 10:51:36 +01:00
2. Using [mermaid plugins ](./integrations.md ) with programs you are familiar with.
2022-05-22 07:12:51 +02:00
3. Calling the Mermaid JavaScript API.
2021-05-01 00:18:06 +02:00
4. Deploying Mermaid as a dependency.
2020-07-24 21:30:06 +02:00
2021-03-12 08:46:59 +01:00
**Note: It is our recommendation that you review all approaches, and choose the one that is best for your project.**
2021-09-29 18:48:46 +02:00
> More in depth information can be found at [Usage](./usage.md).
2020-09-07 08:02:09 +02:00
2021-09-28 11:26:13 +02:00
## 1. Using the Live Editor
Available at [mermaid.live ](https://mermaid.live )
2019-11-07 23:15:53 +01:00
2021-07-06 22:41:06 +02:00
2019-11-07 23:15:53 +01:00
2021-07-15 10:22:33 +02:00
In the `Code` section one can write or edit raw mermaid code, and instantly `Preview` the rendered result on the panel beside it.
2021-05-02 11:03:57 +02:00
2021-09-29 18:48:46 +02:00
The `Configuration` Section is for changing the appearance and behavior of mermaid diagrams. An easy introduction to mermaid configuration is found in the [Advanced usage ](./n00b-advanced.md ) section. A complete configuration reference cataloging the default values can be found on the [mermaidAPI ](Setup.md ) page.
2020-02-23 07:16:26 +01:00
2021-05-03 07:23:19 +02:00
2020-02-23 07:16:00 +01:00
2021-07-06 22:41:06 +02:00
### Editing History
2021-09-29 18:48:46 +02:00
Your code will be autosaved every minute into the Timeline tab of History which shows the most recent 30 items.
2021-07-06 22:41:06 +02:00
2021-09-29 18:48:46 +02:00
You can manually save code by clicking the Save icon in the History section. It can also be accessed in the Saved tab. This is stored in the browser storage only.
2021-07-06 22:41:06 +02:00
2021-05-03 07:23:19 +02:00
### Saving a Diagram:
2021-07-06 22:41:06 +02:00
2021-07-15 10:22:33 +02:00
You may choose any of the methods below, to save it
2019-11-07 23:15:53 +01:00
2021-05-03 07:23:19 +02:00
**We recommend that you save your diagram code on top of any method you choose, in order to make edits and modifications further down the line.**
2021-03-06 10:59:16 +01:00
2021-05-03 07:23:19 +02:00
2019-11-07 23:15:53 +01:00
2021-05-03 07:23:19 +02:00
### Editing your diagrams
2019-11-07 23:15:53 +01:00
2021-07-15 10:22:33 +02:00
Editing is as easy as pasting your **Diagram code** , into the `code` section of the `Live Editor` .
2019-11-07 23:15:53 +01:00
2021-07-06 22:41:06 +02:00
### Loading from Gists
The Gist you create should have a code.mmd file and optionally a config.json. [Example ](https://gist.github.com/sidharthv96/6268a23e673a533dcb198f241fd7012a )
2022-06-24 07:41:22 +02:00
To load a gist into the Editor, you can use https://mermaid.live/edit?gist=https://gist.github.com/sidharthv96/6268a23e673a533dcb198f241fd7012a
2021-07-06 22:41:06 +02:00
2022-06-24 07:41:22 +02:00
and to View, https://mermaid.live/view?gist=https://gist.github.com/sidharthv96/6268a23e673a533dcb198f241fd7012a
2019-11-07 23:15:53 +01:00
2021-04-17 08:41:27 +02:00
## 2. Using Mermaid Plugins:
2019-11-07 23:15:53 +01:00
2021-09-29 18:48:46 +02:00
You can generate mermaid diagrams from within popular applications using plug-ins. It can be done in the same way, you would use the Live Editor. Here's a list of [Mermaid Plugins ](./integrations.md ).
2019-11-07 23:15:53 +01:00
2020-09-07 08:02:09 +02:00
**This is covered in greater detail in the [Usage section ](usage.md )**
2019-11-07 23:15:53 +01:00
2022-05-22 07:12:51 +02:00
## 3. Calling the JavaScript API
2021-05-01 00:18:06 +02:00
2021-09-29 18:48:46 +02:00
This method can be used with any common web server like Apache, IIS, nginx, node express.
2019-11-07 23:15:53 +01:00
2021-09-29 18:48:46 +02:00
You will also need a text editing tool like Notepad++ to generate a .html file. It is then deployed by a web browser (such as Firefox, Chrome, Safari, but not Internet Explorer).
2020-02-23 04:21:37 +01:00
2021-09-29 18:48:46 +02:00
The API works by pulling rendering instructions from the source `mermaid.js` in order to render diagrams on the page.
2020-02-23 04:21:37 +01:00
2021-07-06 22:41:06 +02:00
### Requirements for the Mermaid API.
2020-02-23 04:21:37 +01:00
2021-09-29 18:48:46 +02:00
When writing the .html file, we give three instructions inside the html code to the web browser:
2020-02-27 10:07:25 +01:00
2021-05-01 00:18:06 +02:00
a. A reference for fetching the online mermaid renderer, through the `mermaid.js` or `mermaid.min.js` .
2020-02-27 10:06:38 +01:00
2020-02-23 04:21:37 +01:00
b. The mermaid code for the diagram we want to create.
2020-02-27 10:06:38 +01:00
2021-09-29 18:48:46 +02:00
c. The `mermaid.initialize()` call, which dictates the appearance of diagrams and also starts the rendering process .
2019-11-07 23:15:53 +01:00
2021-04-17 08:41:27 +02:00
**a. A reference to the external CDN in a `<script src>` tag, or a reference to mermaid.js as a separate file.:**
2019-11-07 23:15:53 +01:00
2020-09-07 08:02:09 +02:00
```html
2019-11-07 23:15:53 +01:00
< body >
2021-07-06 22:41:06 +02:00
< script src = "https://cdn.jsdelivr.net/npm/mermaid/dist/mermaid.min.js" > < / script >
2019-11-07 23:15:53 +01:00
< / body >
```
2021-04-17 08:41:27 +02:00
**b. The embedded mermaid diagram definition inside a `<div class="mermaid">` :**
2019-11-07 23:15:53 +01:00
2020-09-07 08:02:09 +02:00
```html
2019-11-07 23:15:53 +01:00
< body >
2021-07-06 22:41:06 +02:00
Here is a mermaid diagram:
< div class = "mermaid" >
2022-01-08 11:05:04 +01:00
graph TD
A[Client] --> B[Load Balancer]
B --> C[Server01]
B --> D[Server02]
2021-07-06 22:41:06 +02:00
< / div >
2019-11-07 23:15:53 +01:00
< / body >
```
2021-07-06 22:41:06 +02:00
2021-09-29 18:48:46 +02:00
**Notes**: Every Mermaid chart/graph/diagram definition, should have separate `<div>` tags.
2020-07-24 21:30:06 +02:00
2021-04-17 08:41:27 +02:00
**c. The `mermaid.initialize()` call.**
2019-11-07 23:15:53 +01:00
2021-09-29 18:48:46 +02:00
`mermaid.initialize()` call takes all the definitions contained in all the `<div class="mermaid">` tags that it finds in the html body and renders them into diagrams. Example:
2021-07-06 22:41:06 +02:00
2020-09-07 08:02:09 +02:00
```html
2019-11-07 23:15:53 +01:00
< body >
2021-07-06 22:41:06 +02:00
< script >
mermaid.initialize({ startOnLoad: true });
< / script >
2019-11-07 23:15:53 +01:00
< / body >
```
2021-03-28 03:14:56 +02:00
2021-03-13 08:42:01 +01:00
**Notes**:
2022-03-01 13:00:52 +01:00
Rendering in Mermaid is initialized by `mermaid.initialize()` call. You can place `mermaid.initialize()` inside `mermaid.min.js` for brevity. However, doing the opposite lets you control when it starts looking for `<div>` tags inside the web page with `mermaid.initialize()` . This is useful when you think that not all `<div>` tags may have loaded on the execution of `mermaid.min.js` file.
2021-03-28 03:14:56 +02:00
`startOnLoad` is one of the parameters that can be defined by `mermaid.initialize()`
2019-11-07 23:15:53 +01:00
2021-07-06 22:41:06 +02:00
| Parameter | Description | Type | Values |
| ----------- | --------------------------------- | ------- | ----------- |
| startOnLoad | Toggle for Rendering upon loading | Boolean | true, false |
2021-03-12 08:46:59 +01:00
2021-07-15 10:22:33 +02:00
### Working Examples
2021-05-01 00:18:06 +02:00
2021-04-17 08:41:27 +02:00
**Here is a full working example of the mermaidAPI being called through the CDN:**
2020-07-16 06:30:23 +02:00
2020-09-07 08:02:09 +02:00
```html
2019-11-07 23:15:53 +01:00
< html >
2021-07-06 22:41:06 +02:00
< body >
< script src = "https://cdn.jsdelivr.net/npm/mermaid/dist/mermaid.min.js" > < / script >
< script >
mermaid.initialize({ startOnLoad: true });
< / script >
Here is one mermaid diagram:
< div class = "mermaid" >
2022-01-08 11:05:04 +01:00
graph TD
A[Client] --> B[Load Balancer]
B --> C[Server1]
B --> D[Server2]
2021-07-06 22:41:06 +02:00
< / div >
And here is another:
< div class = "mermaid" >
2022-01-08 11:05:04 +01:00
graph TD
2022-02-16 21:21:58 +01:00
A[Client] -->|tcp_123| B
2022-01-08 11:05:04 +01:00
B(Load Balancer)
B -->|tcp_456| C[Server1]
B -->|tcp_456| D[Server2]
2021-07-06 22:41:06 +02:00
< / div >
< / body >
2019-11-07 23:15:53 +01:00
< / html >
```
2021-07-06 22:41:06 +02:00
2021-03-13 08:42:01 +01:00
**Another Option:**
2021-07-15 10:22:33 +02:00
In this example mermaid.js is referenced in `src` as a separate JavaScript file, in an example Path.
2021-07-06 22:41:06 +02:00
2020-09-07 08:02:09 +02:00
```html
2020-07-23 06:31:49 +02:00
< html lang = "en" >
2021-07-06 22:41:06 +02:00
< head >
< meta charset = "utf-8" / >
< / head >
< body >
< div class = "mermaid" >
2022-01-08 11:05:04 +01:00
graph LR
A --- B
B-->C[fa:fa-ban forbidden]
B-->D(fa:fa-spinner);
2021-07-06 22:41:06 +02:00
< / div >
< div class = "mermaid" >
2022-01-08 11:05:04 +01:00
graph TD
A[Client] --> B[Load Balancer]
B --> C[Server1]
B --> D[Server2]
2021-07-06 22:41:06 +02:00
< / div >
< script src = "The \Path \In \Your \Package \mermaid.js" ></ script >
< script >
mermaid.initialize({ startOnLoad: true });
< / script >
< / body >
2020-07-23 06:31:49 +02:00
< / html >
2020-07-23 06:28:02 +02:00
```
2021-03-12 08:46:59 +01:00
---
2021-07-06 22:41:06 +02:00
2021-04-17 08:41:27 +02:00
## 4. Adding Mermaid as a dependency.
2019-11-07 23:15:53 +01:00
2021-07-15 10:22:33 +02:00
1. install node v16, which would have npm
2020-08-20 19:01:06 +02:00
2021-03-12 08:46:59 +01:00
2. download yarn using npm by entering the command below:
2021-07-06 22:41:06 +02:00
npm install -g yarn
2021-03-12 08:46:59 +01:00
3. After yarn installs, enter the following command:
2021-07-06 22:41:06 +02:00
yarn add mermaid
2021-07-15 10:22:33 +02:00
2021-03-12 08:46:59 +01:00
4. To add Mermaid as a Dev Dependency
2021-07-06 22:41:06 +02:00
yarn add --dev mermaid
2021-03-12 08:46:59 +01:00
2021-03-13 08:42:01 +01:00
**Comments from Knut Sveidqvist, creator of mermaid:**
2021-07-06 22:41:06 +02:00
- In early versions of mermaid, the `<script src>` 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 reflects the previous way which still works.
