Creating Mermaid diagrams in markdown using vscode
Table of Contents
Introduction
Exploring some of the unused features of my Hugo theme, I noticed that it supports mermaid. I’ve seen mermaid around the web and it has been on my list of things to try out. I thought I would have a little experiment with it as I do have some blog posts that I want to write where it could be useful. Here’s my first few steps.
What is Mermaid?
The headline that originally caught my interest is:
Mermaid lets you create diagrams and visualizations using text and code.
That interests me because Visio is so bad. I do use other tools but the flaw with this can oftentimes be that not every organisation I work with permits those tools. Here’s a little about it:
- It is a JavaScript based diagramming and charting tool
- It renders Markdown-inspired text definitions to create and modify diagrams dynamically
- It supports flowcharts, sequence diagrams, Gantt charts, and more
One of it’s big sells is that it is easy to embed in markdown and thus develop along with your code base.
How to install
Ummm…it’s built into my theme! I’m not going to explore that this time round but if you want to get started quickly here is a live editor.
My very first attempt
Specifically in Hugo, you write the mermaid code in a code block with the language set to mermaid. Whether that is how it works elsewhere I have yet to find out. Here is my first attempt at a flowchart:
flowchart LR;
A[Fight with Luke] --> B[Disarm Luke...literally];
B --> C[Inform Luke I'm his Father];
C --> D[Pause for Dramatic Screams];That was pretty easy to write! Here is what the code looks like:
flowchart LR;
A[Fight with Luke] --> B[Disarm Luke (literally)];
B --> C[Inform Luke I'm his Father];
C --> D[Pause for Dramatic Screams];
I am declaring the diagram type flowchart LR at the start of the code block. This tells mermaid to draw a flowchart and to draw the flow from left to right.
Flowcharts are made up of nodes and edges. I have declared four nodes, A, B, C, and D. The edges are determined by the arrow type and the direction.
A node can have two parts, the first part is the node name and the second part is the node label. For ease of reading, once you have declared the label you only need to reference the node name. If you do however, write a label for a node more than once, the last one will be used.
Extending the flowchart
In the flowchart above, all of the nodes are rectangles. However, there are other shapes that you can use simply by altering the label. I’m also going to change the direction of the flowchart.
flowchart TD;
A([Crash land on Dagobah]) --> B[Meet Yoda];
B --> C[Learn to Use the Force];
C --> F
D --> F{Am I ready?}
F --> |"No"|D[Face Fears in Cave];
F --> |"No but my friends need me"|G([Leave Dagobah]);
flowchart TD;
A([Crash land on Dagobah]) --> B[Meet Yoda];
B --> C[Learn to Use the Force];
C --> F
D --> F{Am I ready?}
F --> |"No"|D[Face Fears in Cave];
F --> |"No but my friends need me"|G([Leave Dagobah]);flowchart LR is now flowchart TD which tells mermaid to draw the flowchart from top to bottom. The first and last nodes are set to stadium-shape (??) nodes by using parentheses. I have drawn a decision point by using curly brackets. By adding the |No| and |Yes| ahead of the node relationship, it displays them as decision outcomes. I have added two edges to the decision node, one for each outcome. I can also change the appearance of the edge by using different syntax, here I used -.-> which is a dashed line.
Different diagram types
Mermaid supports a number of different diagram types, you do this by declare the. Here are a few examples:
Entity Relationship Diagram (ERD)
An entity relationship diagram is a visual representation of the relationships between tables in a database. This could be used for conceptual modelling or database design.
erDiagram
JEDI ||--|| LIGHTSABER : "wields"
JEDI }|--|| PLANET : "resides on"
JEDI }|--|| PLANET : "originates from"
erDiagram
JEDI ||--|| LIGHTSABER : "wields"
JEDI }|--|| PLANET : "resides on"
JEDI }|--|| PLANET : "originates from"The erDiagram declaration tells mermaid to draw an entity relationship diagram. And the notation between nodes declares what sort of relationship it is and draws the relationship using crow’s foot notation. I can also describe the relationship between the nodes by using a colon one or more words (if more than one word it must be enclosed in quotes).
I can expand on this diagram by adding column names like this:
erDiagram
JEDI ||--|| LIGHTSABER : "wields"
JEDI }|--|| PLANET : "resides on"
JEDI }|--|| PLANET : "originates from"
JEDI {
int jediId
string name
string species
date dateOfBirth
}
LIGHTSABER {
int lightsaberId
string color
string crystal
}
PLANET {
int planetId
string name
string galaxy
}
erDiagram
JEDI ||--|| LIGHTSABER : "wields"
JEDI }|--|| PLANET : "resides on"
JEDI }|--|| PLANET : "originates from"
JEDI {
int jediId
string name
string species
date dateOfBirth
}
LIGHTSABER {
int lightsaberId
string color
string crystal
}
PLANET {
int planetId
string name
string galaxy
}Gitgraph
This is the one that led me to find mermaid! I was looking for a way to visualise git branching strategies and that is how I came across mermaid. Here is a simple example:
---
title: A very simple git diagram
---
gitGraph
commit
commit
branch develop
commit
commit
commit
checkout main
merge develop
--- title: A very simple git diagram --- gitGraph commit commit branch develop commit commit commit checkout main merge develop
I’ll be experimenting with this in future blog posts.
C4 Model
This one is interesting to me because I have been asked to create architecture diagrams using the C4 model. The C4 model is a way to visualise software architecture. It is a hierarchical model that describes the static structure of a software system. This one is under development right now, I pinched this example from the mermaid website:
C4Dynamic
title Dynamic diagram for Internet Banking System - API Application
ContainerDb(c4, "Database", "Relational Database Schema", "Stores user registration information, hashed authentication credentials, access logs, etc.")
Container(c1, "Single-Page Application", "JavaScript and Angular", "Provides all of the Internet banking functionality to customers via their web browser.")
Container_Boundary(b, "API Application") {
Component(c3, "Security Component", "Spring Bean", "Provides functionality Related to signing in, changing passwords, etc.")
Component(c2, "Sign In Controller", "Spring MVC Rest Controller", "Allows users to sign in to the Internet Banking System.")
}
Rel(c1, c2, "Submits credentials to", "JSON/HTTPS")
Rel(c2, c3, "Calls isAuthenticated() on")
Rel(c3, c4, "select * from users where username = ?", "JDBC")
C4Dynamic
title Dynamic diagram for Internet Banking System - API Application
ContainerDb(c4, "Database", "Relational Database Schema", "Stores user registration information, hashed authentication credentials, access logs, etc.")
Container(c1, "Single-Page Application", "JavaScript and Angular", "Provides all of the Internet banking functionality to customers via their web browser.")
Container_Boundary(b, "API Application") {
Component(c3, "Security Component", "Spring Bean", "Provides functionality Related to signing in, changing passwords, etc.")
Component(c2, "Sign In Controller", "Spring MVC Rest Controller", "Allows users to sign in to the Internet Banking System.")
}
Rel(c1, c2, "Submits credentials to", "JSON/HTTPS")
Rel(c2, c3, "Calls isAuthenticated() on")
Rel(c3, c4, "select * from users where username = ?", "JDBC")Timeline
It’s really easy to construct a timeline, you simply list the entries using the notation {time period} : {event}. Here is an example:
%%{init: { 'logLevel': 'debug', 'theme': 'dark' } }%%
timeline
title Star Wars Movie Release Dates
1977 : A New Hope
1980 : Empire Strikes Back
1983 : Return of the Jedi
%%{init: { 'logLevel': 'debug', 'theme': 'dark' } }%%
timeline
title Star Wars Movie Release Dates
1977 : A New Hope
1980 : Empire Strikes Back
1983 : Return of the JediConclusion
This was a fun little experiment. I’m going to explore this futher in future blog posts. I can also see how this could be useful for visualising code and architecture which I’ll explore in the future.
References
#mtfbwy