DEV Community

Cover image for Enhance your READMEs with native Mermaid diagrams
Marcelo Arias
Marcelo Arias

Posted on • Originally published at

Enhance your READMEs with native Mermaid diagrams

Many times when we think about how to solve a problem we choose to draw a flowchart or another type of visualization with the aim that everything is clear and that we don't miss anything by the end.

When explaining this part to our friends, it can be very helpful for them to also have clear diagrams of the core parts of a system. And on GitHub, we have a native solution within our Markdown files (like READMEs) for creating these diagrams:

READMEs are a great way to provide a visual description of how your project works, from overall architecture to specific details. With flowcharts, you can illustrate the sequence of steps in a process, the different components of a system, or the relationship between elements (like classes).

What is Mermaid?

Mermaid is a popular library for creating diagrams and flowcharts from text. It is easy to use and can be used to create diagrams using simple text commands. It's also open source and you can use it in GitHub.

In this article you will know how to use Mermaid to design diagrams with examples using the mermaid tags.

How to use Mermaid tags?

All you need to do is to define the diagram using a simple text-based syntax and then render the diagram using the mermaid tag.

For example, let's say I want a flowchart diagram of 4 components. The "A" node will have arrows to "B" and "C", and both "B" and "C" have arrows with a "D" node. I could represent this in code like this:

flowchart TD
A --> B;
A --> C;
B --> D;
C --> D;
Enter fullscreen mode Exit fullscreen mode

And this code will render the following diagram:

Diagram with Mermaid

As you can see, the syntax is quite simple and easy to understand.

Mermaid Basics

The Mermaid flowcharts are composed of nodes: shapes, edges, arrows and lines.

You need to define the flowchart orientation at the beggining. In the example of above the diagram will go from top to the bottom. But other orientations are:

  • TB - top to bottom
  • TD - top-down/ same as top to bottom
  • BT - bottom to top
  • RL - right to left
  • LR - left to right

In addition to flowcharts, Mermaid can also be used to create a variety of other diagrams, such as sequence diagrams.

Sequence Diagrams

To draw a Sequence Diagram, you need to write "sequenceDiagram" in the first line.

After that, you can connect with arrows two nodes. Using the characters:

Enter fullscreen mode Exit fullscreen mode

Here is an example of a sequence diagram created with Mermaid:

    Alice->>+John: Hello John, how are you?
    Alice->>+John: John, can you hear me?
    John-->>-Alice: Hi Alice, I can hear you!
    John-->>-Alice: I feel great!
Enter fullscreen mode Exit fullscreen mode

Sequence Diagram example of Alice and John nodes

State Diagrams

A state diagram is used to describe the flow of a variable. And you can also create a State Diagram using Mermaid. Starting with the stateDiagram and making connections between nodes with the characters: -->.

    [*] --> Still
    Still --> [*]
    Still --> Moving
    Moving --> Still
    Moving --> Crash
    Crash --> [*]
Enter fullscreen mode Exit fullscreen mode

The result will be the following:

State Diagram Example

Class Diagram

A class diagram is a great way to visualize relationships between classes. In this case, you will need to write the classes methods and you can add relationships between classes using other type of arrows.

    Animal <|-- Duck
    Animal <|-- Fish
    Animal <|-- Zebra
    Animal : +int age
    Animal : +String gender
    Animal: +isMammal()
    Animal: +mate()
    class Duck{
      +String beakColor
    class Fish{
      -int sizeInFeet
    class Zebra{
      +bool is_wild
Enter fullscreen mode Exit fullscreen mode

Class Diagram Example

Creation of other diagrams dynamically

How can you make the process of drawing diagrams even easier?

With Mermaid Live Editor you can create diagrams directly on the web. Using this website, every change you make on the code editor in the left side is reflected on the result in the right side. Like a CodePen.

Mermaid Live Editor

Top comments (9)

derlin profile image
Lucy Linder

Mermaid is cool 😎

Speaking of which, I created a command line tool to generate mermaid diagrams from docker-compose files, docker-compose-viz-mermaid, allowing you to easily document a complex architecture in READMEs.

It supports generation of mermaid code or images (SVG/PNG). it can also directly redirect you to the mermaid editor, if you want to edit the result.

If you are interested check it out!

360macky profile image
Marcelo Arias

Wow! It's a brilliant idea @derlin!
Thanks for providing a Mermaid alternative. 😁

leob profile image


ken_mwaura1 profile image
Zoo Codes

Definitely using this in the next project

rascode profile image
Justin Rascoe

Great tutorial! Thanks for sharing with the class.

ashutoshvaidya profile image
Ashutosh Vaidya

Thanks for sharing this one is a useful tool.

kamtoeddy profile image
Kamto Eddy

This is precious.
Thanks for sharing

ranggakd profile image
Retiago Drago

this is like Marp but for diagram

ranggakd profile image
Retiago Drago

I wonder if we can use it in dev markdown editor now. 🤔 @ben @thepracticaldev
also, can we use Marp in here?