Documentation is an integral part of any development process and can take significant time and effort to write. Additionally, even if we write quality documentation, oftentimes it fails to evolve as development best practices change and can quickly become outdated. Mermaid aims to fix this so-called “Doc-Rot” by creating a quick and easy way to create detailed diagrams that can evolve alongside code development.
Today, we will be going over Mermaid and, more specifically, how it can be used to both create and maintain complex documentation using diagrams.
Interacting with Mermaid
At its core, Mermaid is a Javascript-based diagramming and charting tool that can help bridge the gap between documentation and development by using markdown-inspired text. There are several ways that Mermaid can be interacted with, and while we will briefly talk about most of them, we will mainly focus on the live editor and project integration for documentation purposes.
Online Editors
The Mermaid Live editor is essentially the introductory tool for Mermaid. It provides immediate visual feedback demonstrating how text changes will impact the rendered diagram. It also has the benefit of not needing any account setup to dive right in and play around with some of the features Mermaid can provide.
For example, you can easily view and edit some of the sample diagrams provided or create your own, like I have below.
journey title This Blog section Want to learn about Mermaid Look for Blogs: 3: You Find this blog: 7: You Read the blog: 7: You section What I learned about Mermaid How it works: 7: Me, You How to improve documentation: 6: You
The Mermaid chart editor is the step up from the live editor. You’ll need to sign up for an account and get access to additional features.
Integrations
There are also a ton of community-driven integrations for Mermaid, including plugins for Visual Studio Code and JetBrains IDEs as well as support for ChatGPT. Mermaid is also natively supported by apps that use markdown language, such at Github or Gitlab, which is why it is so valuable as a documentation aid. Adding a Mermaid diagram to a markdown file is as easy as adding a mermaid block around your diagram text.
```mermaid flowchart LR A --> B ```
The above code block will be rendered as a Mermaid diagram in GitHub markdown. Notice how the only difference from a diagram you may generate in an editor is the mermaid block
wrapper around the diagram text. This ability to plug and play diagrams into markdown means that there can be seamless transitions between documentation text and visual diagramming for things like workflows and design considerations.
Mermaid also supports diagram embedding via the use of the Mermaid API to insert diagrams directly into HTML content, or you can import the Mermaid dependency directly.
Using Mermaid for Documentation
Now that we’ve gone over the ways to interact with Mermaid, it’s time to dive into some more specifics of how it can enhance documentation.
As seen in the couple of examples above, Mermaid works by defining a diagram type at the start and then adding the content under the diagram type. This structure consolidates all of the needed information for a diagram in a fairly compact form factor, and because of native Github support with markdown, this lets you keep all of the information in one place. This means that rather than having to replace a diagram image pulled in from somewhere else, all of the information is stored directly in markdown and can be dynamically updated right in the markdown file.
Let’s take a look at a couple of real-world examples that Mermaid can help with. First, we will look at a Flowchart diagram, which will map out a simple full-stack explanation of a design flow, and then follow that up with a class diagram. Let’s get started!
Flowchart Diagram
A Flowchart diagram is one of the simplest diagrams to wrap your head around while being flexible enough to convey most topics. Take the following example of a frontend to backend communication flow:
flowchart TD A(Frontend) --> B B(Auth) --> C D[(Database)] <--> C(Service) C --> A
This outlines a frontend calling into Auth, the Auth calling into the Service, the Service calling into and receiving data from a Database, and then the service returning that data to the frontend. Also, one thing to note about flow-based diagrams is that changing the order you define your nodes in the diagram can change the visual appearance of the diagram – even if all of the nodes are still connected the same way. This is especially useful if you are looking for certain diagram layouts that are more spread out or condensed depending on your use case.
Class Diagram
Another common diagram used for documentation is a Class Diagram that describes object-oriented relationships. Below is a basic one outlining a blog object and a comment object with both field and methods built out:
classDiagram Blog --> Comment Blog: string topic Blog: Learn() Comment: string feedback Comment: postFeedback()
These two diagrams are just a few of the many options that Mermaid can provide. I recommend checking out all of the possible options here.
Configuration
Now that we have seen how Mermaid diagrams work and some of the places they can be implemented, let’s take a quick look at Mermaid’s configuration, and how it can be used to customize diagrams.
Mermaid config can be broken down into three distinct pieces, the default config that is already applied, the Mermaid API site level overrides in the initialize call, and the the Frontmatter config defined directly before a diagram. For brevity, we will focus on the Frontmatter config, as it’s the config most relevant for document-related integration.
Frontmatter config is essentially a YAML block of code located directly above the diagram and can contain any modifications to the config you would prefer.
--- title: A Title Name config: theme: forest fontFamily: fantasy --- flowchart A[The] --> B[diagram]
This config block lets you modify things in the diagram like font size, font family, theme, and title. I encourage you to check out all the ways you can customize a diagram to fit your use case. You can find the full list of config options here.
Conclusion
While we have just scratched the surface of what Mermaid can offer, I invite you to try it out for yourself if you haven’t already by either going to the Live or Chart editors and giving it a go. Who knows? Mermaid may be just the tool to push your documentation diagramming to the next level of both clarity and quality.
Thanks for sticking it out to the end! While I’m sure most of us may not love to write documentation, it’s often a necessary evil to ensure code can be understood.
If you liked this blog and would like to explore other topics, the Keyhole Software Dev blog is a great place to start.