Introduction and getting started howtos

2025-01-28 07:03:17 +08:00 · 2019-11-07 23:15:53 +01:00 · 2019-11-07 23:15:53 +01:00 · 1542e15a1b
commit 1542e15a1b
parent 061a02dddc
11 changed files with 190 additions and 6 deletions
--- a/docs/_sidebar.md
+++ b/docs/_sidebar.md
@ -14,8 +14,14 @@
  - [State Diagram](stateDiagram.md)
  - [Gantt](gantt.md)
  - [Pie Chart](pie.md)
+
 - Guide

  - [Development](development.md)
  - [mermaidAPI](mermaidAPI.md)
-  - [Changelog](CHANGELOG.md)
+  - [Changelog](CHANGELOG.md)
+
+- I'm a n00b
+  - [overview](n00b-overview.md)
+  - [Getting started - easier](n00b-gettingStarted.md)
+  - [Three web server examples](n00b-webServers.md)
--- a/docs/img/n00b-Confluence1.png
+++ b/docs/img/n00b-Confluence1.png
--- a/docs/img/n00b-Confluence2.png
+++ b/docs/img/n00b-Confluence2.png
--- a/docs/img/n00b-Confluence3.png
+++ b/docs/img/n00b-Confluence3.png
--- a/docs/img/n00b-Confluence4.png
+++ b/docs/img/n00b-Confluence4.png
--- a/docs/img/n00b-firstFlow.png
+++ b/docs/img/n00b-firstFlow.png
--- a/docs/img/n00b-liveEditor.png
+++ b/docs/img/n00b-liveEditor.png
--- a/docs/mermaidAPI.md
+++ b/docs/mermaidAPI.md
@ -275,7 +275,7 @@ mermaidAPI.initialize({

 <pre>

-<script>
+&lt;script>
  var config = {
    theme:'default',
    logLevel:'fatal',
@ -317,8 +317,7 @@ mermaidAPI.initialize({
    }
  };
  mermaid.initialize(config);
-</script>
-
+&lt;/script>
 </pre>

 [1]: https://github.com/knsv/mermaid/blob/master/docs/mermaidAPI.md#render
--- a/docs/n00b-gettingStarted.md
+++ b/docs/n00b-gettingStarted.md
@ -0,0 +1,153 @@
+# A more basic getting started
+
+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.
+
+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/
+
+Here is one example using an online mermaid editor, one example using a mermaid plugin and one example using a generic web server.
+
+Following either of these examples, you can get started converting your own mermaid code into web 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.
+
+This is a great way to get started.
+
+It is also the easiest way to develop diagrams, the code of which can be pasted straight into documentation.
+
+![Flowchart](./img/n00b-liveEditor.png)
+
+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].
+
+
+## mermaid using plugins
+
+Thanks to the growing popularity of mermaid, many plugins already exist which incorporate a mermaid renderer.
+
+One example is the [Atlassian Confluence mermaid plugin](https://marketplace.atlassian.com/apps/1214124/mermaid-plugin-for-confluence?hosting=server&tab=overview)
+
+When the mermaid plugin is installed on a Confluence server, one can insert a mermaid object into any Confluence page.
+
+---
+
+- In a Confluence page, Add Other macros.
+
+![Flowchart](./img/n00b-Confluence1.png)
+
+---
+
+- Search for mermaid.
+
+![Flowchart](./img/n00b-Confluence2.png)
+
+---
+
+- The mermaid object appears. Paste your mermaid code in it.
+
+![Flowchart](./img/n00b-Confluence3.png)
+
+---
+
+- Save the page.
+
+![Flowchart](./img/n00b-Confluence4.png)
+
+---
+
+## mermaid using any web server
+
+This example can be used with any web server: Apache, IIS, nginx, node express [...]
+
+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).
+
+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.
+2. the mermaid code we want to diagram.
+3. the initialize mermaid command.
+
+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:
+
+```
+<body>
+  <script src="//cdn.jsdelivr.net/npm/mermaid@8.4.0/dist/mermaid.min.js"></script>
+</body>
+```
+
+The embedded mermaid code is similarly placed in a `<script>` tag:
+
+```
+<body>
+  Here is a mermaid diagram:
+  <div class="mermaid">
+    graph TD
+    A[Client] --> B[Load Balancer]
+    B --> C[Server01]
+    B --> D[Server02]
+  </div>
+</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:
+
+```
+<body>
+  <script>mermaid.initialize({startOnLoad:true});</script>
+</body>
+```
+
+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:
+    <div class="mermaid">
+      graph TD
+      A[Client] --> B[Load Balancer]
+      B --> C[Server01]
+      B --> D[Server02]
+    </div>
+
+    And here is another diagram:
+    <div class="mermaid">
+      graph TD
+      A[Client] -->|tcp_1234| B(Load Balancer)
+      B -->|tcp_5678| C[Server01]
+      B -->|tcp_5678| D[Server02]
+    </div>
+  </body>
+</html>
+```
+Save this to a file and fetch it with a browser from the web server.
+
+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.
+
+- 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`:
+  
+  1. One
+  2. Two
+  3. ...
+   
--- a/docs/n00b-overview.md
+++ b/docs/n00b-overview.md
@ -0,0 +1,26 @@
+# Overview for n00bs
+
+As a sysadmin I frequently have to document things, including drawing stuff.
+
+Using mermaid I can type this as a comment in a script:
+
+```
+graph TD
+A[Client] --> B[Load Balancer]
+B --> C[Server01]
+B --> D[Server02]
+```
+
+And end up getting this in the documentation on a web page:
+
+![Flowchart](./img/n00b-firstFlow.png)
+
+Most of the stuff I need to visualize can be done, using a varitety of different symbols and chart types.
+
+Compared to Visio and other similar applications, mermaid is a really easy way to create visualizations when writing documentation.
+
+Since the diagram source can be part of scripts (and other pieces of code), less time needs be spent documenting as a separate task.
+
+However, a lot of the mermaid documentation is geared to professional developers and presumes a skill set which I don't have.
+
+I need a really simple and basic instruction.
--- a/src/mermaidAPI.js
+++ b/src/mermaidAPI.js
@ -686,7 +686,7 @@ export default mermaidAPI;
 * ## mermaidAPI configuration defaults
 * <pre>
 *
- * <script>
+ * &lt;script>
 *   var config = {
 *     theme:'default',
 *     logLevel:'fatal',
@ -728,6 +728,6 @@ export default mermaidAPI;
 *     }
 *   };
 *   mermaid.initialize(config);
- * </script>
+ * &lt;/script>
 *</pre>
 */