advanced usage and some minor improvements

mermaid-js · Feb 12, 2020 · bb228bb · bb228bb
1 parent 0a38e35
commit bb228bb
Show file tree

Hide file tree

Showing 4 changed files with 190 additions and 43 deletions.
diff --git a/docs/n00b-advanced.md b/docs/n00b-advanced.md
@@ -1,21 +1,154 @@
-# Advanced n00b mermaid (Coming soon..)
+# Advanced mermaid usage
+
+## splitting the mermaid code
+In the [previous example](n00b-gettingStarted.md), mermaid was embedded directly in a web page.
+
+A more condensed html code can be achieved by embedding the mermaid diagram in its own .js file.
+
+Using the previous example with two diagrams, the two corresponding .js files can be referenced as follows:
 
-## splitting mermaid code from html
-A more condensed html code can be achieved by embedding the mermaid code in its own .js file, which is referenced like so:
 
 ```
-stuff stuff
-  </div>
+<html>
+  <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">
+      MyFirstDiagram.js
+    </div>
+
+    And here is another:
+    <div class="mermaid">
+      MySecondDiagram.js
+    </div>
   </body>
 </html>
 ```
-The actual mermaid file could for example look like this:
 
+Where the content of the file `MyFirstDiagram.js` is:
 ```
-mermaid content...
+graph TD
+A[Client] --> B[Load Balancer]
+B --> C[Server1]
+B --> D[Server2]
 ```
+
+And the content of the file `MySecondDiagram.js` is:
+```
+graph TD
+A[Client] -->|tcp_123| B(Load Balancer)
+B -->|tcp_456| C[Server1]
+B -->|tcp_456| D[Server2]
+```
+
+*Note* In this example, no mermaid version is referenced in the path to the mermaid renderer. We automatically get the latest version.
+
 ---
 
 ## mermaid configuration options
 
-...
+Often, using mermaid is as easy as just writing the diagram code.
+
+But sometimes we need to tweak how the diagram is rendered. This is done using the configuration options of the [mermaidAPI](mermaidAPI.md).
+
+- A simple example could be to define a theme, maybe we want the diagram to display in `dark` mode? Then we would set the `theme` configuration option to `dark`.
+
+- Or, maybe we want clickable html links inside the mermaid diagram? Then we would set the `securityLevel` to `loose`, changing it from the default of `strict`, and use the `click` keyword inside the diagram.
+
+- Or, maybe the area of the diagram is too narrow to contain our flowchart? Then we could set the `diagramMarginY` to a value greater than the default of `50`.
+
+The different configuration options are documented on the [mermaidAPI](mermaidAPI.md) page together with their default vaules.
+
+## config options - example 1
+To call the mermaid API, we expand on the content of the `<script>` tag used to initialize the mermaid renderer in the html `<body>`.
+
+Building on the previous example, we now want to diagram only the first of the diagrams. But we want one of the boxes, the load balancer, to be a clickable html link.
+
+To achieve this we:
+- set the `securityLevel` to `loose` using the mermaid API
+- use the `click` keyword to define an html link for the desired object - in this example `B`, the load balancer:
+
+```
+<html>
+  <body>
+    <script src="https://cdn.jsdelivr.net/npm/mermaid/dist/mermaid.min.js"></script>
+    <script>
+      var config = {
+        startOnLoad:true,
+        securityLevel:'loose',
+      };
+      mermaid.initialize(config);
+    </script>
+
+    Here is one mermaid diagram:
+    <div class="mermaid">
+      graph TD
+      A[Client] --> B[Load Balancer]
+      B --> C[Server1]
+      B --> D[Server2]
+      click B "http://www.github.com" "This is a tooltip for a link"
+    </div>
+
+    The second diagram was removed in this example.
+  </body>
+</html>
+
+```
+The new setting was defined in a variable `config`, which we referenced as we initialized the mermaid renderer. The variable could have any permissible name.
+
+## config options - example 2
+Some configuration options have their own attributes, i.e. specific configuration values are set through hiearchical levels.
+
+An example of this could be the flowchart diagram:
+```
+<script>
+  var config = {
+    startOnLoad:true,
+    flowchart:{
+      useMaxWidth:true,
+      htmlLabels:true,
+      curve:'cardinal',
+    },
+    securityLevel:'loose',
+  };
+  mermaid.initialize(config);
+</script>
+```
+Here the flowchart options were defined using a json list.
+
+The same options could equally be expressed like this:
+```
+<script>
+  var config = {
+    startOnLoad:true,
+    flowchart.useMaxWidth:true,
+    flowchart.htmlLabels:true,
+    flowchart.curve:'cardinal',
+    securityLevel:'loose',
+  };
+  mermaid.initialize(config);
+</script>
+```
+Which to use is a matter of personal preference.
+
+## Mermaid CLI
+[Mermaid CLI](mermaidCLI.md) is a command line interface for mermaid.
+
+The mermaid CLI does not render a web page from html as shown in the previous examples. Instead, the tool takes a mermaid definition file as input and generates svg/png/pdf file as output.
+
+Using mermaid CLI requires local installation of `node.js` and either of the `yarn` or `npm` package managers. Procedures for installing these environments are beyond the scope of this manual, but instructions may be found [here](https://www.w3schools.com/nodejs/nodejs_get_started.asp) and in a number of other places.
+
+With a working node environment, the mermaid CLI is installed using one of the commands `yarn add mermaid.cli` or `npm install mermaid.cli`.
+
+The CLI is invoked using `mmdc`, for example like so:
+`mmdc -i input.mmd -o output.pdf`
+
+Configuration options may be set with the mermaid CLI but the syntax is different. Current options are displayed with `mmdc -h`.
+
+For example, setting the diagram size can be done like so:
+`mmdc -i input.mmd -o output.svg -w 1024 -H 768`
+
+Further documentation of the Mermaid CLI can be found [here](https://github.com/mermaidjs/mermaid.cli).
+
diff --git a/docs/n00b-gettingStarted.md b/docs/n00b-gettingStarted.md
@@ -4,30 +4,36 @@ Writing mermaid code is simple.
 
 But how is the code turned into a diagram in a web page? To do this we need a mermaid renderer.
 
-Thankfully the mermaid renderer is very accessible, in essence it is a javascript.
+Thankfully the mermaid renderer is very accessible, in essence it is an online javascript.
 
-The requirement is on the part of the web browser. Modern web browsers, such as Firefox, Chrome and Safari, can render mermaid. But Internet Explorer cannot. The web browser also needs access to the online mermaid renderer which it downloads from https://cdn.jsdelivr.net/npm/mermaid
+The requirement is on the part of the web browser. Modern web browsers, such as Firefox, Chrome and Safari, can render mermaid. But Internet Explorer cannot.
 
-For an easy introduction, here follows three practical examples using:
+The web browser needs access to the online mermaid renderer which it downloads from https://cdn.jsdelivr.net/npm/mermaid
+
+As an easy introduction, here are 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 with converting your own mermaid code into web diagrams.
+Following either of these examples, you can quickly get started writing your own mermaid diagrams.
 
 ## the mermaid live editor
 
 The quickest way to get started with mermaid is to visit [The mermaid live editor](https://mermaidjs.github.io/mermaid-live-editor).
 
-In the `Code` section one can write or edit raw mermaid code, and instantly `Preview` the rendered result.
+In the `Code` section, see image below, one can write or edit raw mermaid code and instantly `Preview` the rendered result.
 
-This is a great way to get started.
+This is a super fast way to get started.
 
-It is also the easiest way to develop diagrams, the code of which can be pasted straight into documentation.
+It is also the easiest way to develop diagrams, the code of which can be pasted straight into your documentation.
 
 ![Flowchart](./img/n00b-liveEditor.png)
 
-The `Mermaid configuration` is for controlling mermaid behaviour. 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](mermaidAPI.md) page.
+The `Mermaid configuration` window of the live editor is for controlling mermaid behaviour.
+
+An easy introduction to mermaid configuration is found in the [Advanced usage](n00b-advanced.md) section.
+
+A configuration reference, also cataloguing default values, is found on the [mermaidAPI](mermaidAPI.md) page.
 
 
 ## mermaid using plugins
@@ -40,19 +46,19 @@ When the mermaid plugin is installed on a Confluence server, one can insert a me
 
 ---
 
-- In a Confluence page, Add Other macros.
+- In a Confluence page, choose to Add Other macros:
 
 ![Flowchart](./img/n00b-Confluence1.png)
 
 ---
 
-- Search for mermaid.
+- Search for mermaid:
 
 ![Flowchart](./img/n00b-Confluence2.png)
 
 ---
 
-- The mermaid object appears. Paste your mermaid code into it.
+- The mermaid object appears. Add it to the page and then paste your mermaid code into it.
 
 ![Flowchart](./img/n00b-Confluence3.png)
 
@@ -64,32 +70,34 @@ When the mermaid plugin is installed on a Confluence server, one can insert a me
 
 ---
 
-## mermaid using any web server (or just a browser)
+## mermaid using any web server (or locally with just a browser)
 
 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, apart from a normal file of html to be reached by a web browser (such as Firefox, Chrome, Safari, but not Internet Explorer). So if you want to really simplify things when testing this out, don't use a web server at all but just create the file locally and drag it into your browser window. It is the browser which does all the work of rendering mermaid!
+We do not need to install anything on the server, apart from a normal file of html to be reached by a web browser (such as Firefox, Chrome, Safari, but not Internet Explorer).
 
-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, the renderer is just a javascript.
+So if you want to really simplify things when testing, don't use a web server at all. Just create the file locally and drag it into your browser window. It is the browser which does all the work of rendering mermaid!
+
+In the html file we need to give the web browser three instructions. These are embedded inside the html code in the file:
+1. a reference for fetching the mermaid renderer (as the renderer is just an online javascript).
 2. the mermaid code we want to diagram.
-3. the `mermaid.initialize()` command to start the rendering process
+3. the `mermaid.initialize()` command which starts the rendering process
 
 All this is done in the html `<body>` section of the web page.
 
-This is what needs to go into the html file:
+So for a concrete stepwise example, this is what needs to go into the html file:
 
 
 
-1. The reference to the mermaid renderer is done in a `<script src>` tag like so:
+1. The mermaid renderer is referenced in a `<script src>` tag like so:
 
 ```
 <body>
   <script src="https://cdn.jsdelivr.net/npm/mermaid@8.4.0/dist/mermaid.min.js"></script>
 </body>
 ```
 
-2. The embedded mermaid code is similarly placed in a `<div>` tag:
+2. The embedded mermaid diagram is placed in a `<div>` tag:
 
 ```
 <body>
@@ -103,7 +111,7 @@ This is what needs to go into the html file:
 </body>
 ```
 
-3. When initializing mermaid using `mermaid.initialize()`, mermaid takes all the `<div class="mermaid">` tags it can find in the html body and starts to render them one by one. This is done like so:
+3. When initializing mermaid using `mermaid.initialize()`, mermaid searches the html body for all the `<div class="mermaid">` tags it can find and starts to render them one by one. This is done like so:
 
 ```
 <body>
@@ -112,7 +120,7 @@ This is what needs to go into the html file:
 ```
 
 *Finally*
-4. Putting the three steps together is as simple as:
+4. Putting the three steps together makes for a web page such as:
 ```
 <html>
   <body>
@@ -139,16 +147,20 @@ This is what needs to go into the html file:
 ```
 Save this to a html file and fetch it with a browser from the web server (or just drag it into your web browser window) and voila!
 
+Your web page can in all other respects contain anything you want.
+
 ---
 
-**Three additional comments from Knut Sveidqvist, creator of mermaid:**
+## Additional comments:
+Knut Sveidqvist, the creator of mermaid, had three additional comments to this page:
+
 - 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, older parts of the documentation frequently reflects the previous way which still works.
 
-- 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.
+- We initialize the mermaid rendering directly in the html code with `mermaid.initialize()`. 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 this may be when we think that all `<div>` tags may not have been loaded by the time `mermaid.min.js` runs.
 
-- In the example above, `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`:
+- In the example above, `mermaid.min.js` is called using an absolute path. Even worse, the example includes the mermaid version number. This number will naturally 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. I would suggest one of the following approaches for calling `mermaid.min.js`:
 
-  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).
+  1. If you do not enter a specific version, you automatically get the latest one. This is shown on the [advanced usage](n00b-advanced.md) page.
+  2. If you really need a specific version, hard code it (this is rare, but it happens).
   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==)
 
diff --git a/docs/n00b-overview.md b/docs/n00b-overview.md
@@ -1,8 +1,8 @@
 # Overview for n00bs
 
-As a sysadmin I frequently have to document things, including drawing stuff.
+As an IT professional one frequently has to document things, including drawing stuff.
 
-Using mermaid, I can type this as a comment in a script:
+Using mermaid, typing this as a comment in a script:
 
 ```
 graph TD
@@ -11,17 +11,19 @@ B --> C[Server01]
 B --> D[Server02]
 ```
 
-And end up with this in the documentation:
+produces this in the documentation:
 
 ![Flowchart](./img/n00b-firstFlow.png)
 
-Most of the stuff I need to visualize can be scripted in a similar way, with a varitety of different symbols and chart types available. Since the diagram source is text based, it can be part of production scripts (and other pieces of code). So less time needs be spent on documenting as a separate task.
+Most of the stuff in need of visualizing can be scripted in a similar way, with a varitety of different symbols and chart types available. As the diagram source is text based, it can be part of production scripts (and other pieces of code). Less time needs be spent on documenting as a separate task.
 
-Comparing with Visio and similar applications, mermaid is a really fast way to create good visualizations. This is especially apparent when editing a complex visualisation, this could take me hours in a desktop application but takes minutes (or even less if generation has been scripted) with mermaid.
+Comparing mermaid to Visio and other similar applications, mermaid is a really fast way to create good enough visualizations.
 
-With mermaid I can spend a fraction of the time I normally would spend, and instead automate the diagram generation and end up saving even more time. I love it!
+This is especially true when editing a complex diagram. A task which may consume hours with a desktop application, but which can take minutes (or even less if the diagram generation has been scripted) with mermaid.
 
+As the simple text based syntax is in itself inviting to automation of diagram generation, one can quickly end up saving even more time. What's not to love about that?
 
-However, a lot of the mermaid documentation is geared to professional frontend developers, presuming a skill set which I simply do not have.
 
-I needed a really basic instruction. And here it is.
+Due to its origin, a lot of the mermaid documentation is addressed to professional frontend developers and presumes a certain skill set. However, the way mermaid is implemented is so simple that any IT professional can benefit from it almost instantly.
+
+This instruction attempts to broaden the invitation to use mermaid.
diff --git a/docs/n00b-syntaxReference.md b/docs/n00b-syntaxReference.md
@@ -1,6 +1,6 @@
 ## Diagram syntax reference
 
-Having already [gotten started](n00b-gettingStarted.md), existing diagram syntax documentation was easy enough to follow even for a n00b like me..
+Now that you have [gotten started](n00b-gettingStarted.md) you can explore the different diagram types:
 
 - [Flowchart](flowchart.md)
 - [Sequence diagram](sequenceDiagram.md)