Creating Beautiful Graphs using Markdown | Mermaid

Before starting the coding phase, the most important thing in the journey of programming/solving a problem is its algorithm phase. The best practice for any programmer is to always include a flowchart of the algorithm being used in the solution so that it can be easier for any new programmer to take and proceed further. Also, this practice can come in handy if you have to present your solution to someone.

Imagine you are a part of team working on a common problem statement. If the solution requires brain storming, the best way is to create an algorithm first and once the algorithm is finalized, move to the programming phase. This algorithm forms the base of the project. This not only saves the hit and trial time but also any bugs, errors or loop holes can be easily detected in initial steps.

So today I will show you how you can easily create and manage a flow chart of algorithms along with your project development using nothing but Markdown. Yes you hear it right, just using markdown. This not only makes it super easy to create but also any future changes can be easily added into the flowchart without opening some third-party application and modifying the chart.

A basic Introduction to Markdown:

In simple terms, it is a markup language which was created to provide the easiest way to create a content. One can say that it removes all the hassle of formatting and the writer can just focus on content. It is mostly used in managing project/SDKs/Github Repo Documentation as it requires frequent updates.


In Markdown

# This is a heading

- This is a list item
[   ] This is an empty Checkbox
[ X ] This is a marked Checkbox

We will be using just this markdown language and create a flowchart for our code base.

An Introduction to Mermaid

So our aim is to create a flowchart without using any fancy software, and here Mermaid comes to Rescue

Mermaid is a JavaScript based framework which provides all the functionality to create any type of flowcharts or class diagrams and what not. The beauty of mermaid is that it can be rendered by browsers into flowcharts and graphs. The simplicity of mermaid makes it the best tool to use in any project documentation or source code explanation.

Getting Started With Mermaid

Lets start by taking a small piece of code and visualizing it into a flowchart.


The code is simple, it will iterate 5 times and with each iteration increment the value of b. Lets see how the flowchart for this code will look like.

Mermaid Live Editor

Pretty Interesting Right. Lets see its Mermaid Code:

graph TD;
    start-->initialize[a=5, b=0]
    initialize-->if[/if a>0/]
    if --yes-->add[b=b+a]
    if--No-->loop[Come out of loop]

The code is pretty self explanatory but still I will explain it:

The first line graph TD; Indicates the graph must be Top-Down, the same graph will become left to right if we change it from TD to LR

The next lines after graph TD are the graph definitions.

Lets move to them

To Create a node the simple way is to initialize it without any text in it, this means whatever is the name of the node, the same name will appear in the graph. Example start in first line of the code.

If you want to add a text in the node just add it inside [ ] (brackets like in other lines). To connect nodes the simple way is to use hyphen and greater than sign, somewhat like –>

Types of Nodes in Mermaid

There are a lot of node types in mermaid, I will discuss here few of them , the list can be found on the official website link

Some basic nodes which are generally used are

graph LR;
    simpleNode1[Simple Node with text]
    rounded(Rounded Node)
    Condition{Condition Node}

These nodes are most commonly used during the formation of flowchart.

Mermaid Setup on VS CODE

Now we know what is mermaid and how we can create graph, but the question still remains, how to add it into your project lifecycle. The best way according to me for using mermaid is to add a VS Code Extension for Mermaid, this allows direct mermaid graph creation in your favorite code editor.

Note: Even before testing it on VS Code if you want to give it a try, you can directly go to

So lets see how to add it into VS Code and get started with this beautiful journey of creating charts and graphs.

Step 1: Open VS Code Extensions pane and search Mermaid

Here in the Marketplace of VS Code, there are multiple extensions which can be used, just search Mermaid, you will get extensions varying from color scheme and syntax highlighting of mermaid to mermaid previews.

Step 2: Open the extension by Matt Biemer and Install

This is by far the easiest and fastest Mermaid extension which I have used till date. It directly plugs itself in the builtin Markdown previewer of VS Code and directly renders any mermaid Code block in the whole markdown content.

And done, that’s all, now create a markdown file ( .md extension ) and start creating graphs out of it.

Create a markdown file and open markdown preview of VS code by search pressing ctrl+shift+p and search markdown preview. Select Live Preview.

Create a code block in markdown and initialize it with mermaid as shown below.

And Done. That’ all, your graph is ready, it will be live reloaded as you will edit the markdown, so you can see it coming into action.

How I Compile Mermaid Directly on GitHub Using GitHub Action

Another way in which I like using mermaid is directly using Github actions.

Github doesn’t support mermaid in their Github Flavored markdown so there are actions available on github which can be used and can be triggered every time you push some markdown with mermaid graphs, the github action will compile the markdown into a image of graph and attach it to the file.

More on it in Next blog on mermaid. Let me know in comments if you need the next part of it.


If You find it interesting!! we would really like to hear from you.

Ping us at Instagram/@the.blur.code


Thanks for reading!! 

Happy Coding

Leave a Reply

Your email address will not be published. Required fields are marked *

Related Posts

Begin typing your search term above and press enter to search. Press ESC to cancel.

Back To Top
Hey, wait!

Before you dive into the exciting Article, wanna join our newsletter list, We promise we will not spam