mirrors
/
mermaid
mirror of https://github.com/mermaid-js/mermaid.git
2
0
Fork 0
Code Issues Projects Releases Wiki Activity

Polishing

This commit is contained in:
Erik Ellingsen 2019-11-07 23:37:46 +01:00
parent 1542e15a1b
commit dc59632fb3
2 changed files with 23 additions and 20 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

BIN
docs/img/n00b-liveEditor.png
View File

Binary file not shown.
Side by Side Swipe Overlay

Before

Width:  |  Height:  |  Size: 100 KiB

After

Width:  |  Height:  |  Size: 111 KiB

43
docs/n00b-gettingStarted.md
View File

@ -2,11 +2,16 @@
Writing mermaid code is simple.
But how is it turned into a diagram in a web page? To do this We need a mermaid renderer.
But how is it turned into a diagram in a web page? To do this we need a mermaid renderer.
Thankfully the mermaid renderer is very accessible. The requirement is on the part of the web browser (modern web browsers such as Firefox, Chrome, Safari work, but Internet Explorer does not). The web browser also needs to be able to access the online mermaid renderer at cdn.jsdelivr.net/npm/
Thankfully the mermaid renderer is very accessible.
Here is one example using an online mermaid editor, one example using a mermaid plugin and one example using a generic web server.
The requirement is on the part of the web browser. Modern web browsers work, such as Firefox, Chrome, Safari. But Internet Explorer does not. The web browser also needs to be able to access the online mermaid renderer at cdn.jsdelivr.net/npm/
For an easy introduction, here follows three practical examples using:
1. an online mermaid editor
2. a mermaid plugin
3. a generic web server of your choosing
Following either of these examples, you can get started converting your own mermaid code into web diagrams.
@ -24,7 +29,7 @@ It is also the easiest way to develop diagrams, the code of which can be pasted
The `Mermaid configuration` is for controlling the behaviour of mermaid.
An easy introduction is found in the [n00b Advanced section] and a complete configuration reference is found [here].
An easy introduction to mermaid configuration is found in the [n00b Advanced section]. A complete configuration reference is found [here].
## mermaid using plugins
@ -49,13 +54,13 @@ When the mermaid plugin is installed on a Confluence server, one can insert a me
---
- The mermaid object appears. Paste your mermaid code in it.
- The mermaid object appears. Paste your mermaid code into it.
![Flowchart](./img/n00b-Confluence3.png)
---
- Save the page.
- Save the page and the diagram appears.
![Flowchart](./img/n00b-Confluence4.png)
@ -63,20 +68,20 @@ When the mermaid plugin is installed on a Confluence server, one can insert a me
## mermaid using any web server
This example can be used with any web server: Apache, IIS, nginx, node express [...]
This example can be used with any common web server. Apache, IIS, nginx, node express [...], you pick your favourite.
We do not need to install anything on the server, to have it serve a mermaid diagram to a web browser (such as Firefox, Chrome, Safari, but not Internet Explorer).
We do not need to install anything on the server, apart from a normal file of html which can be reached by a web browser (such as Firefox, Chrome, Safari, but not Internet Explorer).
Instead, we need to give the web browser three instructions inside the html code it retrieves:
1. a reference for fetching the online mermaid renderer, which in essence is a javascript.
Through the html file, we give the web browser three instructions inside the html code it retrieves:
1. a reference for fetching the online mermaid renderer, in essence a javascript.
2. the mermaid code we want to diagram.
3. the initialize mermaid command.
3. the `mermaid.initialize()` command to start the rendering process
All this is done in the html `<body>` section of the web page.
The reference to the mermaid renderer is done in a `<script src>` tag like so:
1. The reference to the mermaid renderer is done in a `<script src>` tag like so:
```
<body>
@ -84,7 +89,7 @@ The reference to the mermaid renderer is done in a `<script src>` tag like so:
</body>
```
The embedded mermaid code is similarly placed in a `<script>` tag:
2. The embedded mermaid code is similarly placed in a `<script>` tag:
```
<body>
@ -98,7 +103,7 @@ The embedded mermaid code is similarly placed in a `<script>` tag:
</body>
```
Initializing mermaid has the effekt of it starting to render the content of all the `<div class="mermaid">` tags it finds in the web page, and is done so:
3. When initializing mermaid, it starts to render the content of all the `<div class="mermaid">` tags it can find in the html body. This is done like so:
```
<body>
@ -106,14 +111,12 @@ Initializing mermaid has the effekt of it starting to render the content of all
</body>
```
Putting the three steps together is as simple as:
*Finally*
4. Putting the three steps together is as simple as:
```
<html>
<body>
Here the mermaid renderer is loaded:
<script src="//cdn.jsdelivr.net/npm/mermaid@8.4.0/dist/mermaid.min.js"></script>
Here we trigger the mermaid renderer, upon which it starts looking for mermaid <div> tags:
<script>mermaid.initialize({startOnLoad:true});</script>
Here is one mermaid diagram:
@ -143,9 +146,9 @@ Voila!
Three additional comments from Knut, the creator of mermaid:
- In early versions of mermaid, the `<script src>` tag was invoked in the `<head>` part of the web page. Nowdays we can place it directly in `<body>` as seen above. However, the documentation still frequently reflects the old way which still works.
- We initialize the mermaid rendering with `mermaid.initialize()` directly in the html code, this could instead in principle be done through placing `mermaid.initialize()` inside of mermaid.min.js. We would thereby eliminate this explicit line in the html. However, there are use cases where we do want to separate these two steps. Sometimes we want full control over when we start looking for `<div>`tags inside the web page, as all `<div>` tags may not have loaded when `mermaid.min.js` runs.
- We initialize the mermaid rendering with `mermaid.initialize()` directly in the html code, in principle this could instead be done through placing `mermaid.initialize()` inside of mermaid.min.js. We would thereby eliminate this explicit line in the html. However, there are use cases where we do want to separate these two steps. Sometimes we want full control over when we start looking for `<div>`tags inside the web page, as all `<div>` tags may not have loaded when `mermaid.min.js` runs.
- In the example above, the `mermaid.min.js` is called using an absolute path. Even worse, it includes the mermaid version, which will of course change as time goes by. However the example makes it easy to understand what is going on, even though it is 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`:
- In the example above, the `mermaid.min.js` is called using an absolute path. Even worse, it includes the mermaid version number, which will of course change as time goes by. However the example makes it easy to understand what is going on, even though it is 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`:
1. One
2. Two