What is Mermaid JS?
Flowcharts, sequence diagrams, class diagrams, Gantt charts, and Git graphs
When it comes to flowcharts in written materials or presentations, the first option that comes to mind is often graphic applications. However, due to update requirements, operations performed through programs may not always be very effective. So, what are the alternative solutions?
Although design programs are a primary option for requirements such as flowcharts, sequence diagrams, class diagrams, Gantt charts, and Git graphs, operations can also be performed through various applications and/or programming languages. Thanks to these solutions, the relevant graphs can be output dynamically and/or statically. However, of course, we can benefit from these capabilities within their own dependencies and limitations. Mermaid, developed with the JavaScript language, is one of these options. What sets Mermaid JS apart from others is its ability to be easily adapted to different environments and its Markdown-like (markdownish) syntax that allows us to easily create flowcharts, sequence diagrams, class diagrams, Gantt charts, and Git graphs. Of course, there are other options besides mermaid, such as PlantUML1 and Kroki2.
Mermaid JS
Mermaid-js is an open-source, JavaScript-based diagram and graph tool that allows us to easily create flowcharts, sequence diagrams, class diagrams, Gantt charts, and Git graphs through writing rules similar to markdown syntax3.
Through basic formatting definitions, complex diagrams can be created and modified quickly and dynamically. You can apply and edit the examples below quickly using the Mermaid Live Editor4.
Let's proceed by creating an example flowchart.
graph LR;
A-->B;
A-->C;
B-->D;
C-->D;
In the example above, the graph
indicates that the expressions we specify should be considered in a flowchart format. TD shows how the relevant format should be oriented5. A, B, C, and D denote the relevant points, while -->
defines the relationship between these points. In summary, the above mermaid definition is interpreted (rendered) and presented to us in SVG format6. You can see the output of the above example in Figure 1 (a).
%%{init: { 'theme': 'dark' } }%%
graph LR;
A[/Lorem/]-.->|X| B(Ipsum);
A--> C[Dolor];
B-->D[fa:fa-car Sit Amet];
C==>|Y| D;
%%{init: {'theme':'base'}}%%
flowchart TB;
A(Lorem)-.->|X| B(Ipsum);
A--xC(Dolor);
B--oD((fa:fa-car Sit Amet));
C<==>|Y| B & D;
subgraph section
B
C
end
You can see the outputs of the two mermaid definitions above in Figure 1 (b) and Figure 1 (c) respectively. graph
can essentially be considered a simpler use of flowchart
. flowchart can be preferred in cases where more detailed definitions are required.
I should note that at the time of writing this article, flowchart is in beta mode. init directive allows us to make changes to the configuration7.
It carries parameters such as security definitions for the interpretation process, theme definitions, and log operations. Its most basic use is as follows:
%%{init: { <argümanlar> }}%%
For more comprehensive usage, you can view and update the following example with the Mermaid Live Editor.
graph LR
A[Campaign]
B[LP: lp-1]
C[LP: lp-2]
D[Order Form: bp-1]
E[Order Form: bp-2]
F[Order Form: of-1]
G[Order Form: of-2]
H[Up-sell 1]
I[Up-sell 2]
J[Order Completed]
A --> B & C
subgraph s11 [split testing - 1]
B & C
end
subgraph st2 [split testing - 2]
B-->|%50|D & E
C-->|%50|E & D
end
subgraph st3 [split testing - 3]
D-->|%70|F & G
E-->|%30|G & F
end
F & G --> H
H --> I
I --> J
It is worth mentioning that we can also make interactions with mermaid diagrams. However, this feature cannot be used in the securityLevel='strict'
definition. Therefore, the security definition needs to be edited as securityLevel='loose'
8.
var callback = function(){
alert('A callback was triggered');
}
graph LR;
A-->B;
B-->C;
C-->D;
click A callback "Tooltip for a callback"
click B "http://www.github.com" "This is a tooltip for a link"
click A call callback() "Tooltip for a callback"
click B href "http://www.github.com" "This is a tooltip for a link"
Of course, the formats we can use with Mermaid are not limited to flowchart
and graph
.
We can create sequence diagrams using sequenceDiagram
. sequenceDiagram can also be considered as a simple level Unified Modelling Language (UML) solution that determines and explains how business systems can be modeled9.
Dialogues between individuals or requests and responses between services can be given as examples for the sequence flow.
sequenceDiagram
participant John
participant Alice
participant Ela
Alice->>John: Hello John, how are you?
Alice->>Ela: Hi
John-->>Alice: Great!
Ela ->> John: Hello!
We can enrich the above sequence flow with notes and loops. You can see the code snippet below to visualize the changes in the diagram using the Mermaid Live Editor 4.
sequenceDiagram
participant John
participant Alice
participant Ela
Alice->>John: Hello John, how are you?
Note right of John: Text in note
Alice->>Ela: Hi
John-->>Ela: Fine!
loop Every minute
John->>Alice: Great!
end
Ela ->> John: Hello!
As mentioned on the relevant Wikipedia page, class diagrams are a type of static structural diagram in the Unified Modeling Language (UML) that define the structure of a system by showing its classes, attributes, operations (or methods), and the relationships between objects in software engineering10.
We can start formatting with class to create a class diagram, which is the main building block of object-oriented modeling. Let's create a class
diagram for animals to visualize their different types and actions11.
classDiagram
Animal <|-- Duck
Animal <|-- Fish
Animal <|-- Zebra
Animal : +int age
Animal : +String gender
Animal: +isMammal()
Animal: +mate()
class Duck{
+String beakColor
+swim()
+quack()
}
class Fish{
-int sizeInFeet
-canEat()
}
class Zebra{
+bool is_wild
+run()
}
State diagrams are commonly used to define a limited number of states related to system behaviors. We can define a state diagram using stateDiagram-v2
through Mermaid. Two special states can be used to represent the start and stop of the diagram, respectively. These expressions are written with the [*]
syntax, and the direction of the transition defines it as a start or stop state.
stateDiagram-v2
[*] --> s1
s1 --> [*]
We can create nested flows with it as following.
stateDiagram-v2
[*] --> First
First --> Second
First --> Third
First --> Fourth
state First {
[*] --> fir
fir --> [*]
}
state Second {
[*] --> sec
sec --> [*]
}
state Third {
[*] --> thi
thi --> [*]
}
state Fourth {
[*] --> Sixth
state Fifth {
[*] --> Sixth
second --> Third
state Sixth {
[*] --> third
third --> [*]
}
}
}
Entity-relationship (ER) diagrams explain related topics in a specific scope of information. They are often used to create databases. For example, we can handle order and address definitions in the context of customer data using an entity-relationship diagram. A basic ER model consists of entity types (which classify things of interest) and specifies the relationships (instances of these entity types) that can exist between entities12.
erDiagram
CUSTOMER ||--o{ ORDER : places
ORDER ||--|{ LINE-ITEM : contains
CUSTOMER }|..|{ DELIVERY-ADDRESS : uses
User journey diagrams are a type of diagram that allows us to track the steps users take to reach a defined goal in a system, application, or website. For example, we can interpret all the steps from the cart to the payment result page for an e-commerce site using this type of diagram. We can create such diagrams using journey
.
journey
title My working day
section Go to work
Make tea: 5: Me
Go upstairs: 3: Me
Do work: 1: Me, Cat
section Go home
Go downstairs: 5: Me
Sit down: 5: Me
As mentioned in the article "What is TeamGantt?", I provided basic information about Gantt charts in the context of TeamGantt. Gantt charts are a type of bar chart that shows the flow of a project and the time required to complete it. Mermaid allows us to create such a diagram using gantt13.
gantt
dateFormat YYYY-MM-DD
title Adding GANTT diagram functionality to mermaid
excludes weekends
%% (`excludes` accepts specific dates in YYYY-MM-DD format, days of the week ("sunday") or "weekends", but not the word "weekdays".)
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
Pie charts are a type of graph used to show the ratio between related numerical values. In a pie chart, the length of each slice (and thus its central angle and area) represents the amount it corresponds to. Mermaid allows us to create such graphs using pie
. They contain much more basic features compared to other diagrams.
pie title Pets adopted by volunteers
"Dogs" : 386
"Cats" : 85
"Rats" : 15
Git graphs (experimental) are a type of diagram that is presented experimentally and continues to be developed to visualize changes in a Git repository. They can be created using gitGraph
3.
gitGraph:
options
{
"nodeSpacing": 150,
"nodeRadius": 10
}
end
commit
branch newbranch
checkout newbranch
commit
commit
checkout master
commit
commit
merge newbranch
As mentioned in the introduction of the article, diagrams are presented in SVG format, which allows for many customization options either directly or indirectly. When configuration definitions expressed with init
are insufficient, we can manipulate the styles with CSS. Below, you can see the code for the diagram I created to summarize the new theme transition process with the purpose of illustrating how we can use CSS to adjust the background and label padding values14.
div.mermaid {
background: #1c2230;
}
div.mermaid .edgeLabel,
div.mermaid .label {
padding: 15px 10px;
}
%%{
init: {
'theme': 'base',
'themeVariables': {
'primaryColor': '#48556d',
'primaryBorderColor': '#151920',
'lineColor': '#135cff',
'edgeLabelBackground':'#135cff',
'tertiaryColor': '#151920',
'nodeTextColor': '#ffffff',
'arrowheadColor': '#ffffff'
}
}
}%%
graph TD
A(WordPress v.1) -- CMS ve Tema Değişikliği --> B(Grav CMS)
B ==>|Light| C(v.2 Gliese 667 Cb)
B --> |Dark| D(v.3 HD 189733 b)
subgraph Geliştirmeler
B
C
end
C ==>|Modüller| D
C -- Geri Bildirimler --> E[A/B Testi]
C -- Online Ürünler --> F[MVT]
E -- Sayfa İçi Özellikler --> C
subgraph Testler
B
C
E
F
end
E ==>|UI Geliştirme| D
F ==>|Modüler Sayfalar| D
linkStyle 0 stroke-width:2px,fill:none,stroke:blue;
linkStyle 1 stroke-width:2px,fill:none,stroke:green;
linkStyle 2 stroke-width:2px,fill:none,stroke:yellow;
linkStyle 3 stroke-width:2px,fill:none,stroke:pink;
linkStyle default stroke-width:2px,fill:none,stroke:red;
As seen, we can customize the styles of directives with linkStyle
and also define general theme-related configurations with init
. The background and label padding
value are achieved through CSS15.
Platforms such as GitHub and GitLab currently do not support Mermaid. However, developments in this area are being closely monitored by the community1617. On the other hand, it is possible to benefit from various plugins for this process18. Additionally, various plugins are available for static site tools such as Jekyll19.
If you use Notion, you can easily include Mermaid diagrams in your content20 21.
As I continue to learn more about Mermaid, which I have encountered recently and used many times in a short period of time, I will make additions related to different writing styles and customizations.
Conclusion
In conclusion, while design programs such as Adobe Illustrator or Sketch are frequently used for creating diagrams, various tools and libraries that enable the creation of diagrams in various formats using programming languages and simple text-based syntaxes exist. One of these options is Mermaid JS, which is a versatile and easily adaptable tool for creating diagrams such as flowcharts, sequence diagrams, class diagrams, Gantt charts, and Git graphs. Additionally, there are other options such as PlantUML and Kroki. Ultimately, selecting a tool or library depends on the specific requirements of the project and the individual's familiarity with programming languages and syntaxes.
- PlantUML. Open-source tool that uses simple textual descriptions to draw beautiful UML diagrams ↩
- Kriki. Creates diagrams from textual descriptions ↩
- About Mermaid ↩ ↩
- Mermaid Live Editor. GitHub ↩ ↩
- Matt Kenny. (2020). Mermaid JS ↩
- Flowcharts - Basic Syntax ↩
- Directives. Mermaid ↩
- Interaction. Mermaid ↩
- UML. Wikipedia ↩
- Class diagram. Wikipedia ↩
- Trevor Lasn. (2019). Mermaid — Create Charts and Diagrams With Markdown-like Syntax ↩
- Varlık-bağıntı modeli. Wikipedia ve Entity–relationship model. Wikipedia ↩
- Aashish Manandhar. (2020). Documenting your code should be done this way ↩
- Karanlık tema testleri ise hem desktop hem de mobile için müthiş değişim sağladı... ↩
- Styling. Mermaid ↩
- How to make GitHub Pages Markdown support mermaid diagram? Stackoverflow ↩
- Feature Request: Support Mermaid (markdown) graph diagrams in .md files. GitHub Support Community ↩
- GitHub + Mermaid. Chrome Extension ↩
- Jekyll-spaceship. GitHub ↩
- Notion + Diagrams ↩
- Notion is working on supporting Mermaid Diagrams. Twitter ↩