minutes read

Mermaid - Let diagrams explain your codes


September 19, 2022

feature image

A better way to debug your PHP code

A better way to debug your PHP code

Khoa Pham

November 16, 2022

Discover iOS Dark Mode Programming

Discover iOS Dark Mode Programming


November 1, 2022


Code Documentation is anything you write in addition to your code to help others understand how it works. A good example of technical documentation I was inspired by is the Rails README file.

Providing coherent and concise code documentation with your GitHub project is not only good for knowledge transfer but also supports troubleshooting issues and makes future management easier in case of additional integrations.

When you write a code document to explain a codebase structure or a project architecture, you need to use diagrams to illustrate it. In this article, I would like to introduce Mermaid - a helpful diagram tool in your Markdown README file.

many examples of charts made using Mermaid

1. Get to know Mermaid

A diagram tells a thousand words. Normally, I would draw mine using draw.io and embed those images into Markdown files. They explain the code structures just fine, but sometimes I would prefer if my diagrams could:

  • be easily up to date with changes
  • generated quickly with codes
  • be drawn without the need to use the mouse

If you find yourself struggling with the same problem, I have just an alternative tool for your diagrams - Mermaid.

Mermaid is a JavaScript-based diagramming and charting tool that takes Markdown-inspired text definitions and creates diagrams dynamically in the browser. It supports a bunch of different common diagram types for software projects, including flowcharts, UML, Git graphs, user journey diagrams, and even the dreaded Gantt chart.

Therefore, you don’t have to draw anything, just write down what you want to see! For example:

  • This is the diagram I made using draw.io, then exporting to SVG file and embedding the image to README file
a diagram made with draw.io that depicts what happens when a client login and Auth0 will gain them access token w API

This is how we do it with Mermaid

And this is the result:

a diagram made with mermaid that depicts what happens when a client login and Auth0 will gain them access token w API

One advantage of using Mermaid is that when you want to keep your diagrams up to date with your change, you can easily edit them by changing the Mermaid codes instead of re-drawing images and embedding them again into the README file.

2. How to include Mermaid diagrams in Github Repo?

You can now embed Mermaid code in your README.md and other markdown files. If you do, GitHub will render those codes into a diagram.

Mermaid code uses a simple syntax with mermaid that describes the individual parts of each diagram in plain text. Here’s a closer look at each type of Mermaid chart.

2.1. Flow chart

a mermaid flowchart example

The start graph TD indicates the orientation of the graph: top-down as opposed to LR (left-right), RL (right-left), or BT (bottom-top).

You can specify nodes by a short identifier (A, B, C, etc.) here and indicate what shape and text they should have with the brackets following it. You can specify many shapes, including circles, rhombus, or trapezoids.

To specify the arrows from one box to another, you just type the two node IDs joined by an arrow, depending on what arrow type you want. You can add text to the arrows with the |<text>| before the destination node.

2.2. Pie chart

You will see this pie chart in the markdown file:

a mermaid pie chart generated from the above code

2.3. Class Diagram

2.4. Gantt chart

Another chart type is Gantt, commonly used for project management.

Mermaid also supports the following types of diagrams:

  • State Diagram
  • Entity Relationship
  • User Journey
  • Requirement Diagram

Some editors support Mermaid, including Atom, VIM and VS Code. Using VS Code, and the extension Markdown Preview Mermaid Support is very helpful in rendering the graphs in the markdown previews.

3. Online Editor

This is the simplest way to try out Mermaid, using their online tool. You can start with a template, and verify how your changes affect the final result. You can also try another powerful online Markdown editor Stackedit https://stackedit.io/app#

a screenshot of StackEdit welcome screen


Mermaid diagrams are a useful addition to GitHub/GitLab by default in its Markdown, particularly since they encourage better documentation, saving you so much time and effort to create diagrams. They’re what our team at FABA use along with our code documentation to explain our projects in a more coherent and direct way.


  1. https://mermaid-js.github.io/
  2. https://github.blog/2022-02-14-include-diagrams-markdown-files-mermaid/