Mermaid: Helping Documentation Catch Up with Development

Brian Buchta Development Technologies, Programming Leave a Comment

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.

0 0 votes
Article Rating
Subscribe
Notify of
guest

0 Comments
Inline Feedbacks
View all comments