2021-03-12 23:42:01 -08:00
# A Mermaid User-Guide for Beginners
2021-05-02 21:29:49 -07:00
Mermaid is composed of three parts, Deployment, Syntax and Configuration.
2019-11-07 23:15:53 +01:00
2021-05-02 21:29:49 -07:00
This section talks about the different ways to deploy Mermaid. Learning the [Syntax ](./n00b-syntaxReference.md ) ahead of time would be more helpful to the beginner.
2021-04-30 15:18:06 -07:00
2021-05-02 21:29:49 -07: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-04-16 23:41:27 -07:00
**Absolute beginners are recommended 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-16 23:41:27 -07:00
## Four ways of using mermaid:
2021-05-01 02:26:41 -07:00
1. Using the mermaid [Live Editor ](https://mermaid-js.github.io/mermaid-live-editor/ ).
2021-03-14 01:51:36 -08:00
2. Using [mermaid plugins ](./integrations.md ) with programs you are familiar with.
2021-04-30 15:18:06 -07:00
3. Calling the Mermaid Javascript API.
4. Deploying Mermaid as a dependency.
2020-07-24 12:30:06 -07:00
2021-03-11 23:46:59 -08:00
**Note: It is our recommendation that you review all approaches, and choose the one that is best for your project.**
>More in depth information can be found on [Usage ](./usage.md ).
2020-09-07 14:02:09 +08:00
2021-04-30 15:18:06 -07:00
## 1. Using [The Live Editor](https://mermaidjs.github.io/mermaid-live-editor).
2019-11-07 23:15:53 +01:00
2021-05-02 22:23:19 -07:00
2019-11-07 23:15:53 +01:00
2021-05-02 02:03:57 -07: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 22:23:19 -07: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 cataloguing default values is found on the [mermaidAPI ](Setup.md ) page.
2020-02-22 22:16:26 -08:00
2020-02-22 23:10:08 -08:00
2021-05-02 22:23:19 -07:00
2020-02-22 22:16:00 -08:00
2021-05-02 22:23:19 -07:00
### Saving a Diagram:
You may choose any of the methods below, to save it
2019-11-07 23:15:53 +01:00
2021-05-02 22:23:19 -07: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 01:59:16 -08:00
2021-05-02 22:23:19 -07:00
2019-11-07 23:15:53 +01:00
2021-05-02 22:23:19 -07:00
### Editing your diagrams
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-04-16 23:41:27 -07:00
## 2. Using Mermaid Plugins:
2019-11-07 23:15:53 +01:00
2021-03-27 18:14:56 -07:00
Using plug-ins you can generate mermaid diagrams from within popular applications, the same way that 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 14:02:09 +08:00
**This is covered in greater detail in the [Usage section ](usage.md )**
2019-11-07 23:15:53 +01:00
2021-04-30 15:18:06 -07:00
## 3. Calling the Javascript API
This method can be used with any common web server. Apache, IIS, nginx, node express, you are free to choose.
2019-11-07 23:15:53 +01:00
2021-04-30 15:18:06 -07:00
You will also need a text editting tool like Notepad++, to generate an html file. It is then deployed by a web browser (such as Firefox, Chrome, Safari, but not Internet Explorer).
2020-02-22 19:21:37 -08:00
2021-04-30 15:18:06 -07:00
The API works by pulling rendering instructions from a source from `mermaid.js` to render diagrams in the page.
2020-02-22 19:21:37 -08:00
2021-04-30 15:18:06 -07:00
### Requirements for the Mermaid API.
2020-02-22 19:21:37 -08:00
When writing the html file, we give the web browser three instructions inside the html code:
2020-02-27 01:07:25 -08:00
2021-04-30 15:18:06 -07:00
a. A reference for fetching the online mermaid renderer, through the `mermaid.js` or `mermaid.min.js` .
2020-02-27 01:06:38 -08:00
2020-02-22 19:21:37 -08:00
b. The mermaid code for the diagram we want to create.
2020-02-27 01:06:38 -08:00
2021-04-30 15:18:06 -07:00
c. The `mermaid.initialize()` call, which can dictate the appreance of diagrams and also start the rendering process .
2019-11-07 23:15:53 +01:00
2021-04-16 23:41:27 -07: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 14:02:09 +08:00
```html
2019-11-07 23:15:53 +01:00
< body >
2020-07-22 21:28:02 -07: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-16 23:41:27 -07:00
**b. The embedded mermaid diagram definition inside a `<div class="mermaid">` :**
2019-11-07 23:15:53 +01:00
2020-09-07 14:02:09 +08:00
```html
2019-11-07 23:15:53 +01:00
< body >
Here is a mermaid diagram:
< div class = "mermaid" >
graph TD
A[Client] --> B[Load Balancer]
B --> C[Server01]
B --> D[Server02]
< / div >
< / body >
```
2020-07-24 12:30:06 -07:00
**Notes**: every mermaid chart/graph/diagram definition, has to have separate `<div>` tags.
2021-04-16 23:41:27 -07:00
**c. The `mermaid.initialize()` call.**
2019-11-07 23:15:53 +01:00
2021-04-30 15:18:06 -07:00
`mermaid.initialize()` calls take all the definitions contained in `<div class="mermaid">` tags it can find in the html body and renders them into diagrams. Example:
2020-09-07 14:02:09 +08:00
```html
2019-11-07 23:15:53 +01:00
< body >
< script > mermaid . initialize ( { startOnLoad : true } ) ; < / script >
< / body >
```
2021-03-27 18:14:56 -07:00
2021-03-12 23:42:01 -08:00
**Notes**:
2021-03-27 18:14:56 -07:00
Mermaid rendering is initalized with `mermaid.initialize()` .You can place `mermaid.initialize()` inside of `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()` , such as when you think that noy all `<div>` tags may not have been loaded when `mermaid.min.js` runs.
`startOnLoad` is one of the parameters that can be defined by `mermaid.initialize()`
2019-11-07 23:15:53 +01:00
2021-03-27 18:14:56 -07:00
| Parameter | Description | Type | Values |
| --------- | --------------- | ------ | ---------------------------------------------------- |
|startOnLoad| Toggle for Rendering upon loading | Boolean | true, false |
2021-03-11 23:46:59 -08:00
2021-04-30 15:18:06 -07:00
### Working Examples
2021-04-16 23:41:27 -07:00
**Here is a full working example of the mermaidAPI being called through the CDN:**
2020-07-15 21:30:23 -07:00
2020-09-07 14:02:09 +08:00
```html
2019-11-07 23:15:53 +01:00
< html >
< body >
2020-07-22 21:28:02 -07:00
< script src = "https://cdn.jsdelivr.net/npm/mermaid/dist/mermaid.min.js" > < / script >
2019-11-07 23:15:53 +01:00
< script > mermaid . initialize ( { startOnLoad : true } ) ; < / script >
Here is one mermaid diagram:
< div class = "mermaid" >
graph TD
A[Client] --> B[Load Balancer]
2019-11-28 12:34:26 +01:00
B --> C[Server1]
B --> D[Server2]
2019-11-07 23:15:53 +01:00
< / div >
2019-11-28 12:34:26 +01:00
And here is another:
2019-11-07 23:15:53 +01:00
< div class = "mermaid" >
graph TD
2019-11-28 12:34:26 +01:00
A[Client] -->|tcp_123| B(Load Balancer)
B -->|tcp_456| C[Server1]
B -->|tcp_456| D[Server2]
2019-11-07 23:15:53 +01:00
< / div >
< / body >
< / html >
```
2021-03-12 23:42:01 -08:00
**Another Option:**
In this example mermaid.js is referenced in `src` as a separate JavaScript file, in an example Path.
2020-09-07 14:02:09 +08:00
```html
2020-07-22 21:31:49 -07:00
< html lang = "en" >
< head >
< meta charset = "utf-8" >
< / head >
< body >
< div class = "mermaid" >
graph LR
A --- B
B-->C[fa:fa-ban forbidden]
B-->D(fa:fa-spinner);
< / div >
< div class = "mermaid" >
graph TD
A[Client] --> B[Load Balancer]
B --> C[Server1]
B --> D[Server2]
< / div >
2021-03-27 18:14:56 -07:00
< script src = "The \Path \In \Your \Package \mermaid.js" ></ script >
2020-07-22 21:31:49 -07:00
< script > mermaid . initialize ( { startOnLoad : true } ) ; < / script >
< / body >
< / html >
2020-07-22 21:28:02 -07:00
```
2021-03-11 23:46:59 -08:00
---
2021-04-16 23:41:27 -07:00
## 4. Adding Mermaid as a dependency.
2019-11-07 23:15:53 +01:00
2021-03-11 23:46:59 -08:00
1. install node v10 or 12, which would have npm
2020-08-21 01:01:06 +08:00
2021-03-11 23:46:59 -08:00
2. download yarn using npm by entering the command below:
npm install -g yarn
3. After yarn installs, enter the following command:
yarn add mermaid
4. To add Mermaid as a Dev Dependency
yarn add --dev mermaid
2021-03-12 23:42:01 -08:00
**Comments from Knut Sveidqvist, creator of mermaid:**
2021-03-11 23:46:59 -08: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.
