- Mermaid is a Javascript based diagramming and charting tool that uses Markdown-inspired text definitions and a renderer to create and modify complex diagrams. The main purpose of Mermaid is to help documentation catch up with development. Diagramming and documentation costs precious developer time and gets outdated quickly.
- Cheat Sheet for Mermaid. Gantt dateFormat YYYY-MM-DD title Adding GANTT diagram functionality to mermaid section A section Completed task:done, des1, 2018-01-08 Active task:active, des2, 2018-01-09, 3d Future task: des3, after des2, 5d Future task2: des4, after des3, 5d section Critical tasks Completed task in the critical line:crit, done, 2018-01-06,24h Implement parser.
Simplify documentation and avoid heavy tools. Open source Visio Alternative. Commonly used for explaining your code! Mermaid is a simple markdown-like script language for generating charts from text via javascript.
This post demonstrate how to use memaid.js library to render simple text into flowcharts, sequence diagrams and gnatt charts.
Mermaid Gnatt Chart Examples
gantt dateFormat YYYY-MM-DD title Adding GANTT diagram functionality to mermaid section A section Completed task :done, des1, 2014-01-06,2014-01-08 Active task :active, des2, 2014-01-09, 3d Future task : des3, after des2, 5d Future task2 : des4, after des3, 5d section Critical tasks Completed task in the critical line :crit, done, 2014-01-06,24h Implement parser and jison :crit, done, after des1, 2d Create tests for parser :crit, active, 3d Future task in critical line :crit, 5d Create tests for renderer :2d Add to mermaid :1d section Documentation Describe gantt syntax :active, a1, after des1, 3d Add gantt diagram to demo page :after a1 , 20h Add another diagram to demo page :doc1, after a1 , 48h section Last section Describe gantt syntax :after doc1, 3d Add gantt diagram to demo page : 20h Add another diagram to demo page : 48h
Mermaid Sequence Chart Examples
sequenceDiagram Alice->>Sachin: Hello Sachin, how are you? Sachin-->>Alice: Great! Sachin-->>John: Alice On! Alice->>+John: Hello John, how are you? Alice->>+John: John, can yoy hear me? John-->>-Alice: Hi Alice, I can hear you! John-->>-Alice: I feel great! Note over Alice,John: A typical interaction Alice->Sachin: Hello John, how are you? loop Reply every minute Sachin-->Alice: Great! end Alice->>Bob: Hello Bob, how are you? alt is sick Bob->>Alice: Not so good :( else is well Bob->>Alice: Feeling fresh like a daisy end opt Extra response Bob->>Alice: Thanks for asking end
Mermaid FlowChart Examples
Mermaid Js Examples
graph TB subgraph one a1-->a2 end subgraph two b1-->b2 end subgraph three c1-->c2 end c1-->a2 style a1 fill:#f9f,stroke:#333,stroke-width:4px; style a2 fill:#ccf,stroke:#f66,stroke-width:2px,stroke-dasharray: 5, 5; classDef redbox fill:#f9f,stroke:#333,stroke-width:4px; class b1,c1 redbox; classDef dottedbox fill:#ccf,stroke:#f66,stroke-width:2px,stroke-dasharray: 5, 5; class b2,c2 redbox;
graph TD B['fa:fa-twitter for peace'] B-->C[fa:fa-ban forbidden] B-->D(fa:fa-spinner); B-->E(A fa:fa-camera-retro perhaps?);
graph LR A[Hard edge] -->|Link text| B(Round edge) B --> C{Decision} C -->|One| D[Result one] C -->|Two| E[Result two]
Mermaid Demo
graph LR A[Square Rect] -- Link text --> B((Circle)) A --> C(Round Rect) B --> D{Rhombus} C --> D
![Mermaid Js Examples Mermaid Js Examples](https://craftbakery.dev/content/images/2020/04/image-6.png)
graph TB sq[Square shape] --> ci((Circle shape)) subgraph A subgraph od>Odd shape]-- Two line
edge comment --> ro di{Diamond with
line break} -.-> ro(Rounded
square
shape) di>ro2(Rounded square shape) end %% Notice that no text in shape are added here instead that is appended further down e --> od3>Really long text with linebreak
in an Odd shape] %% Comments after double percent signs e((Inner / circle
and some odd
special characters)) --> f(,.?!+-*ز) cyr[Cyrillic]-->cyr2((Circle shape Начало)); classDef green fill:#9f6,stroke:#333,stroke-width:2px; classDef orange fill:#f96,stroke:#333,stroke-width:4px; class sq,e green class di orange
edge comment --> ro di{Diamond with
line break} -.-> ro(Rounded
square
shape) di>ro2(Rounded square shape) end %% Notice that no text in shape are added here instead that is appended further down e --> od3>Really long text with linebreak
in an Odd shape] %% Comments after double percent signs e((Inner / circle
and some odd
special characters)) --> f(,.?!+-*ز) cyr[Cyrillic]-->cyr2((Circle shape Начало)); classDef green fill:#9f6,stroke:#333,stroke-width:2px; classDef orange fill:#f96,stroke:#333,stroke-width:4px; class sq,e green class di orange
sequenceDiagram participant Alice participant Bob Alice->>John: Hello John, how are you? loop Healthcheck John->>John: Fight against hypochondria end Note right of John: Rational thoughts
prevail.. John-->>Alice: Great! John->>Bob: How about you? Bob-->>John: Jolly good!
prevail.. John-->>Alice: Great! John->>Bob: How about you? Bob-->>John: Jolly good!
![Examples Examples](/uploads/1/0/9/4/109454383/272114682.png)
Being able to write simple diagrams with text is very convenient.We can do this in Hugo by rendering with mermaid.js.
In particular I want to render some factor tree diagrams of the style of The Art of Insight.Like this one:
The final result looks like:
graph LR; A[sheets ream-1
500] -->|-1| B[thickness
10-2cm
] C[thickness ream-1
5cm] --> B B --> D[volume
1cm3] E[height
6cm] --> D F[width
15cm] --> D
500] -->|-1| B[thickness
10-2cm
] C[thickness ream-1
5cm] --> B B --> D[volume
1cm3] E[height
6cm] --> D F[width
15cm] --> D
I copied the Mermaid Hugo shortcode from the learn theme and put it in
layouts/shortcodes/mermaid.html
.Then following the mermaid documentation I inject the script into a template.For the
hugo-casper3
theme I do this by making a copy of layouts/partials/site-header.html
and adding the script to the top of the template.Chart Js Example
Then I can just include a diagram in any markdown document by putting the following between
<mermaid>
tags in handlebars.Ideally I would use Hugo to prerender the diagrams but unfortunately it's not possible at this stage.I could use Blogdown to generate the diagrams with R, but I don't want to have to write all my posts in RMarkdown.So instead we have to use client side rendering of diagrams, and R Markdown is a good example of this.
I found the solution with Mermaid in Julian Knight's article about Embedding diagrams in a Hugo Page, and saw the implementation in Learn theme.
Note that the
securityLevel: 'loose'
configuration above allows representing HTML inside the diagram.Mermaid Js Markdown
It would be better for stability to host the Mermaid files locally, rather than using the CDN above.For rendering speed it would be better in the footer than the header.But as a quick hack this seems to work well enough.