Wednesday, August 1, 2018

Mermaid.js tutorial - Javascript Diagram Tool

Learn Mermaid.js 

It is javascript framework for generating diagrams from text content. Text content is an in a syntax similar to markdown text. This project uses D3 and dagre-d3 libraries for graphics layout and drawing. This also has an online editor where you can design the diagrams and test it.

With this library can generate the following diagrams using javascript
  • FlowChart
  • Sequence Diagram
  • Gantt Diagram
  • Class Diagram
  • Git Graphs

Advantages

 No need for any commercial tools to generate flow and sequence diagram tools.
 Simple tool to generate basic diagrams
 Free to use
Online Editor to test text content.

Installation and Setup

This library can be used as javascript/jquery and node-based application

using CDN


Include CDN URL in script tag of HTML as like below

<script src="https://cdnjs.cloudflare.com/ajax/libs/mermaid/8.0.0-rc.8/mermaid.min.js"></script>
<script>mermaid.initialize({startOnLoad:true});</script>

Using NodeJS npm 


yarn add mermaid
npm install -g mermaid
This installs dependencies in your nodejs application.

mermaidJS API usage

 This will be used in client applications on the webpage to load it. These calls render function, parse the text syntax and Generate the diagram and output to SVN element In HTML, we will write HTML tag like this and class="mermaid"

<script>mermaid.initialize({startOnLoad:true});</script>
<div class="mermaid">
</div>

Sample Flowchart Example 

Following snippet of code generates a simple flowchart diagram

<!doctype html>
<html lang="en">
   <head>
      <title>Mermaind Javascript Flow chart Example</title>
      <script src="https://cdnjs.cloudflare.com/ajax/libs/mermaid/8.0.0-rc.8/mermaid.min.js"></script>
      <script>mermaid.initialize({startOnLoad:true});</script>
   </head>
   <body>
      <div class="mermaid">
         graph TD
         A[Start] --> C{Answer Question?}
         C -->|Yes| D[Do Something]
         C -->|No| E[Do Something]
      </div>
   </body>
</html>
Please see the output of this code as per screenshot mermaidJS javascript diagram tool

Mermaid CLI Usage

It is command line interface tool which takes mmd extension file as input and output to SVG, png and PDF format. mmd is a mermaid definition file which contains text markdown syntax formatted content. This has various options to configure, height, background color and css styles.
Install cli - using npm command, This installs tool globally


yarn global add mermaid.cli
or 
npm install -g mermaid.cli
this cli provides mmdc command line option. you can check the usage and options as per below
B:\Workspace\blog\mermaid>mmdc -h

  Usage: index.bundle [options]
  Options:
    -V, --version                                   output the version number
    -t, --theme [theme]                             Theme of the chart, could be default, forest, dark or neutral. Optional. Default: default (default: default)
    -w, --width [width]                             Width of the page. Optional. Default: 800 (default: 800)
    -H, --height [height]                           Height of the page. Optional. Default: 600 (default: 600)
    -i, --input                              Input mermaid file. Required.
    -o, --output [output]                           Output file. It should be either svg, png or pdf. Optional. Default: input + ".svg"
    -b, --backgroundColor [backgroundColor]         Background color. Example: transparent, red, '#F0F0F0'. Optional. Default: white
    -c, --configFile [configFile]                   JSON configuration file for mermaid. Optional
    -C, --cssFile [cssFile]                         CSS file for the page. Optional
    -p --puppeteerConfigFile [puppeteerConfigFile]  JSON configuration file for puppeteer. Optional
    -h, --help                                      output usage information

Export to PDF/PNG/SVG example

This is an example of generating a sequence diagram from the text and convert into a png file and download it. Use a mmdc tool which accepts text file and generates a png file

mmdc -i sequence.mmd  -o sequence.png -w 1024 -H 768
you are also supplying width and height configuration for generated png file. sequence.mmd file contains below markdown text syntax
sequenceDiagram
Browser->> Server: send request 
Server->> Database: get records
Note right of Database: Records Processed.
Database->> Server: returns records
Server->> Browser: returned response to browser
Generated Sequence Diagram is as follows
mermaid sequence diagram example
sequence.png
Mermaid Live Editor tool
This is online Editor tool to edit/preview/download mermaid flowcharts and diagrams. This will be very useful for coding mermaid definition file and test and preview the diagram flows. This will help developers to save time and debug if any issues. This has also various options like generate the link for the generated diagram and share it with others, Others can also edit the code and see the diagram. You can also download generated flow as SVG file.

Available Themes 

  • Dark
  • Default
  • forest 
  • neutral


EmoticonEmoticon

Note: Only a member of this blog may post a comment.