I have been working in the software industry for about 8 years now. One of the problems that has always existed and been a point of contention in the dev teams is the presence of good documentation. Why is that? There are a couple of reasons. One, good and relevant documentation is an ongoing maintenance effort. There aren’t too many people who are excited to maintain the documentation. Even in my personal experience, while I enjoy creating docs, I do not always follow through with up keeping it.

One of the tools that has caught my attention in the last couple of years was Mermaid.js. Digging into it a little bit, I saw the potential that could improve the experience of devs in relation to the documentation. Let’s discuss what it is and why is it so good.

What is Mermaid.js? 🧜‍♀️

According to Mermaid.js documentation,

Mermaid is a JavaScript based diagramming and charting tool that uses Markdown-inspired text definitions and a renderer to create and modify complex diagrams. The main purpose of Mermaid is to help documentation catch up with development.

In simpler terms, it is diagrams and charts represented in text. It is a simple, yet powerful concept. It allows the developers (and really anyone who needs diagrams and charts) to use the power of simple text to represent complex relationships that get visualized using Mermaid renderer.

Examples of the diagrams

Here are a couple of examples of what Mermaid.js is capable of. There are quite a few diagram and chart formats that are available. These and other examples could be found on Mermaid.js documentation site.

Sequence Diagram

  sequenceDiagram
    Alice ->> Bob: Hello Bob, how are you?
    Bob-->>John: How about you John?
    Bob--x Alice: I am good thanks!
    Bob-x John: I am good thanks!
    Note right of John: Bob thinks a long<br/>long time, so long<br/>that the text does<br/>not fit on a row.

    Bob-->Alice: Checking with John...
    Alice->John: Yes... John, how are you?

Syntax

sequenceDiagram
    Alice ->> Bob: Hello Bob, how are you?
    Bob-->>John: How about you John?
    Bob--x Alice: I am good thanks!
    Bob-x John: I am good thanks!
    Note right of John: Bob thinks a long<br/>long time, so long<br/>that the text does<br/>not fit on a row.

    Bob-->Alice: Checking with John...
    Alice->John: Yes... John, how are you?

Flowchart

  flowchart TD

A[Christmas] -->|Get money| B(Go shopping)

B --> C{Let me think}

C -->|One| D[Laptop]

C -->|Two| E[iPhone]

C -->|Three| F[fa:fa-car Car]

Syntax

flowchart TD
	A[Christmas] -->|Get money| B(Go shopping)
	B --> C{Let me think}
	C -->|One| D[Laptop]
	C -->|Two| E[iPhone]
	C -->|Three| F[fa:fa-car Car]

Class Diagram

  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()

}

Syntax

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()
	}

Other formats

Mermaid offers the ability to render more diagram and chart types:

Diagram-as-code 📊

To expand on why this is a powerful tool for developers and enterprise teams let’s focus on the main differentiating feature of Mermaid - a diagram-as-code solution.

Storing as text

Utilizing simple text as a medium for data transfer (compared to images in other solutions) is a very robust solution supporting an existing text-based environment of information exchange. It is a lot cheaper to send text than to send an image. It is a lot cheaper to store text rather than store an image. It is a lot easier to modify text than to modify an image. Text is a highly versatile medium. We do not need to create new innovative channels to exchange text information. We can use anything from email and instant messaging to version control systems to process and transfer it. This creates a product that is highly flexible and independent of the medium that we use in any given context.

Checking into VCS

Checking the code of the diagrams into VCS like Git will create a powerful and robust system that enables collaboration and version control for diagrams. Imagine viewing the diagram evolution over time using VCS by checking out earlier commits. What about storing these diagrams side-by-side with the code that they represent? This yet again showcases the power of text storage.

Using in Markdown

In addition to that, Mermaid integrates very well with the most common Markdown renderers. Even in writing of this post in using Hugo and writing markdown files they come with Mermaid rendering support with minimal configuration. GitHub follows the suit. Creating and editing diagrams in flow with the document creates a very convenient way to work with documentation. By putting all of the text together in one document, we create a coherent document that has text, code, and rendered diagrams.

Gaining Momentum 🏃‍♂️

Support for Mermaid in existing solutions

Mermaid is supported in Markdown. But that is far from all of the solutions that understand, render, and support Mermaid diagrams. For the list of all of the supported integrations refer to Integrations - Community page. Here is a list of the most prominent ones:

Flexibility in creation, modification, storage, and sharing

As mentioned above, creation, editing, storing, and sharing text is as simple as it gets in a text-based data exchange environment that is Internet. That removes all sorts of obstacles that other mediums would have created or required. There is no need in special software or protocols to exchange text beyond what already exists. The simplicity is the true power for Mermaid.

Integration with automation

Lastly, one of the things that got me excited about this tool initially was the potential to integrate it with automated processes like adding it as a build step in CI/CD pipelines. Since Mermaid is text-based, nothing is stopping us from creating scripts that generate Mermaid code based off existing code or input. That was the concept that led me to create an internal tool that generated sequence diagrams from end-to-end Appium tests written in Gherkin at Discover Financial Services. Once the tool was deployed, every code change started to reflect changes in the generated diagrams on-the-fly without requiring much (or any) of the maintenance effort.

Give it a try 🚀

And that is by far not the only application that Mermaid.js can aid in creation and modification of text-based diagrams and charts. I do recommend you to check this tool out and see if there is a place for it to be implemented in your projects. I hope I convinced you to give it a try.