diff --git a/docs/n00b-advanced.md b/docs/n00b-advanced.md index 407be8c081..973ba39182 100644 --- 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 - + + + + + + Here is one mermaid diagram: +
+ MyFirstDiagram.js +
+ + And here is another: +
+ MySecondDiagram.js +
``` -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 ` + + + Here is one mermaid diagram: +
+ 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" +
+ + The second diagram was removed in this example. + + + +``` +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: +``` + +``` +Here the flowchart options were defined using a json list. + +The same options could equally be expressed like this: +``` + +``` +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 index 96cd576c9d..59e3173887 100644 --- 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,24 +70,26 @@ 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 `` 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 `