2020-02-23 08:20:50 +01:00
# A basic mermaid User-Guide for Beginners
2019-11-07 23:15:53 +01:00
2020-07-16 06:30:23 +02:00
Creating diagrams and charts using mermaid code is simple.
2021-03-04 13:48:58 +01:00
mermaid allows you to dynamically code and modify diagrams.
when called, mermaid renders code definitions into a diagram in SVG format.
2019-11-07 23:15:53 +01:00
2021-03-04 13:48:58 +01:00
>The live editor is enough for most general uses of mermaid
2021-03-06 10:59:16 +01: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
2019-11-07 23:37:46 +01:00
2020-07-23 06:28:02 +02:00
## For beginners, there are four relatively easy ways you can use mermaid:
2021-03-06 10:59:16 +01:00
1. Using the mermaid [Live Editor ](https://mermaid-js.github.io/mermaid-live-editor/ ).
2021-03-04 13:48:58 +01:00
- Learning the [Syntax ](./n00b-syntaxReference ) would be helpful.
2. Using one of the many [mermaid plugins ](./integrations.md ).
2020-07-26 03:15:37 +02:00
3. Hosting mermaid on a webpage, with an absolute link.
2020-08-20 19:01:06 +02:00
4. Downloading mermaid and hosting it on your Web Page.
2020-07-24 21:30:06 +02:00
**Notes**: More in depth information can be found on [Usage ](./usage.md ).
2020-09-07 08:02:09 +02:00
2020-07-24 21:30:06 +02:00
# Following any of these examples, you can get started with creating your own diagrams using mermaid code.
2019-11-07 23:15:53 +01:00
2020-02-23 07:16:00 +01:00
## 1. The mermaid live editor:
2019-11-07 23:15:53 +01:00
2020-02-23 07:16:00 +01:00
A great way to get started with mermaid is to visit [The mermaid live editor ](https://mermaidjs.github.io/mermaid-live-editor ).
2019-11-07 23:15:53 +01:00
2020-02-23 04:21:37 +01:00
In the `Code` section one can write or edit raw mermaid code, and instantly `Preview` the rendered result on the panel beside it.
2020-02-23 07:16:26 +01:00
2020-08-20 19:01:06 +02:00
**This is a great way to learn how to define a mermaid diagram.**
2020-07-23 06:28:02 +02:00
2021-03-06 10:59:16 +01:00
The Live Editor opens on a [Flowchart ](./flowchart.md ).
2019-11-07 23:15:53 +01:00
2020-11-15 12:25:02 +01:00
2020-02-23 08:10:08 +01:00
2021-03-02 01:24:48 +01:00
**Saving a Diagram:**
Downloading the image may be a ideal for a majority uses.
2019-11-07 23:15:53 +01:00
2021-03-02 01:24:48 +01:00
The Links and the markdown code can be referenced to display the diagram.
2020-02-23 07:16:00 +01:00
2021-03-03 01:07:34 +01:00
2019-11-07 23:15:53 +01:00
2021-03-06 10:59:16 +01:00
**Configuration**
2021-03-03 01:04:44 +01:00
*The Mermaid configuration* is for configuring 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.
2019-11-07 23:15:53 +01:00
2020-11-15 12:25:02 +01:00
2019-11-07 23:15:53 +01:00
2020-11-15 12:25:02 +01:00
## 2. Using mermaid plugins:
2019-11-07 23:15:53 +01:00
2020-11-15 12:25:02 +01:00
Thanks to the growing popularity of mermaid, many plugins already allow the generation of mermaid diagrams from within popular applications. An extensive list of applications the support mermaid plugins can be found [here ](./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
2021-03-12 03:09:43 +01:00
## 3. Deploying mermaid with Inline JavaScript
2019-11-07 23:15:53 +01:00
2020-02-23 04:21:37 +01:00
This method can be used with any common web server. Apache, IIS, nginx, node express [...], you pick your favourite.
2020-08-20 19:01:06 +02:00
We do not need to install anything on the server, apart from a program (like Notepad++) that can generate an html file, which 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-03-12 03:09:43 +01:00
Just create an HTML file locally and open it using a desired browser.
2020-02-23 04:21:37 +01:00
2021-03-12 03:09:43 +01:00
### Written in the html `<body>` section of the web page.
2020-02-23 04:21:37 +01:00
When writing the html file, we give the web browser three instructions inside the html code:
2020-02-27 10:07:25 +01:00
2020-02-23 04:21:37 +01:00
a. A reference for fetching the online mermaid renderer, which is written in Javascript.
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
2020-11-15 12:25:02 +01:00
c. The `mermaid.initialize()` call to start the rendering process.
2019-11-07 23:15:53 +01:00
2021-03-12 03:09:43 +01:00
## Three requirements for the mermaidAPI to render a diagram:
2019-11-07 23:15:53 +01:00
2021-03-12 03:09:43 +01:00
### a. A reference to the external CDN in a `<script src>` tag:
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 >
2020-07-23 06:28:02 +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-03-12 03:09:43 +01: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 >
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 21:30:06 +02:00
**Notes**: every mermaid chart/graph/diagram definition, has to have separate `<div>` tags.
2021-03-12 03:09:43 +01:00
### c. The `mermaid.initialize()` call.
2019-11-07 23:15:53 +01:00
2021-03-12 03:09:43 +01:00
`mermaid.initialize()` calls take all the definitions contained in `<div class="mermaid">` tags it can find in the html body and render. Example:
**Values:**
startOnLoad:true
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 >
< script > mermaid . initialize ( { startOnLoad : true } ) ; < / script >
< / body >
```
2020-07-25 18:52:11 +02:00
**Notes**: It is good practice to keep the `mermaid.initialize()` API call right next the `mermaid.min.js` `script` tag.
`startOnLoad` is a parameter that can optionally be changed to false, this would then prevent mermaid from immediately rendering upon loading.
2019-11-07 23:15:53 +01:00
2021-03-12 03:09:43 +01:00
### Here is a full working example of the mermaidAPI being called through HTML:
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 >
< body >
2020-07-23 06:28:02 +02: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 >
```
2020-07-24 21:30:06 +02:00
2019-11-07 23:15:53 +01:00
---
2021-03-12 03:09:43 +01:00
## 4. Adding mermaid as a dependency.
2020-07-23 06:28:02 +02:00
1. install node v10 or 12, which would have npm
2020-07-24 21:30:06 +02:00
2. download yarn using npm by entering the command below:
npm install -g yarn
2020-07-23 06:28:02 +02:00
3. After yarn installs, enter the following command:
yarn add mermaid
2021-03-12 03:09:43 +01:00
4. To add Mermaid as a Dev Dependency
yarn add --dev mermaid
2020-07-23 06:31:49 +02:00
**As seen here, in this full example:**
2020-09-07 08:02:09 +02:00
```html
2020-07-23 06:31:49 +02: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 >
2020-07-24 21:30:06 +02:00
< script src = "C: \Users \MyPC \mermaid \dist \mermaid.js" ></ script >
2020-07-23 06:31:49 +02:00
< script > mermaid . initialize ( { startOnLoad : true } ) ; < / script >
< / body >
< / html >
2020-07-23 06:28:02 +02:00
```
2019-11-07 23:15:53 +01:00
2019-11-08 01:25:41 +01:00
**Three additional comments from Knut Sveidqvist, creator of mermaid:**
2020-10-14 14:41:15 +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 directly in `<body>` as seen above. However, older parts of the documentation frequently reflects the previous way which still works.
2020-08-20 19:01:06 +02:00
2019-11-08 10:36:41 +01:00
- We initialize the mermaid rendering with `mermaid.initialize()` directly in the html code. In principle this could be done through placing `mermaid.initialize()` inside of `mermaid.min.js` . We would then eliminate the need for this explicit line in the html. However, there are use cases where we do want to separate the two steps. Sometimes we want full control over when we start looking for `<div>` tags inside the web page with `mermaid.initialize()` , for example when we think that all `<div>` tags may not have been loaded by the time `mermaid.min.js` runs.
2019-11-07 23:15:53 +01:00
2020-07-23 06:28:02 +02:00
- In the third method, `mermaid.min.js` is called using an absolute path. Even worse, the example includes the mermaid version number which of course will change as time goes by. However, the example makes it easy to understand what is going on - even though it is perhaps doomed in a way we do not want in a production environment. When going from testing mermaid out to getting serious with it, I would suggest one of the following approaches for calling `mermaid.min.js` :
2020-08-20 19:01:06 +02:00
2019-11-28 13:13:26 +01:00
1. If you do not enter a specific version, you automatically get the latest one.
2. If you really need a specific version, hard code it (this is rare but it happens).
2019-11-28 13:14:29 +01:00
3. If you need to know the current mermaid version, replace a mermaid code block with the word `info` and the version will be returned like [this ](https://mermaid-js.github.io/mermaid-live-editor/#/edit/eyJjb2RlIjoiaW5mb1xuXG4iLCJtZXJtYWlkIjp7InRoZW1lIjoiZGVmYXVsdCJ9fQ== )
