Introducing Mermaid with Markdown

First, let's go over some background. The idea for Mermaid came about after I tried to make a small update to a diagram within a document, a task that ended up taking a surprising amount of time. It turned out that the source file for the diagram was nowhere to be found, so the diagram had to be redrawn from scratch. This made me wonder how we could have a complete document in a text format, with document text and images in the same text file. Due to this, we came up with Markdown in combination with a new utility for rendering diagrams from text. Later the same evening, I sat down in my living room to start this new side project – a new graph rendering library – while my kids were watching The Little Mermaid on TV. And from this, the somewhat whimsical name for the software was born: Mermaid.

Mermaid.js is a scripting language that lets you represent different types of diagrams as text. It uses a web browser to transform the diagram text into an SVG, rendering a graphical display of the information in the text. Mermaid.js lets you create various diagrams and flowcharts using only simple markup-like text. It is a free, open source, and easy-to-use JavaScript library. Mermaid.js lets you simplify documentation and helps you avoid using heavy, bulky tools to explain your ideas.

One of the core goals of Mermaid.js is to help you write your documentation and catch up with development. Typically, in today's world, development is done very quickly, but for some reason, the documentation is still lagging. It is this division between the progress of product development and the progress of documentation that Mermaid.js tries to address.

Often, it is difficult to express your code or use cases with just words in your documentation. There were no good solutions that supported declarative styles of writing in documentation, especially for developers; to many developers, it is much easier and more rewarding when they are writing documentation that is similar to coding. Having something that can transform a few lines of text into an elegant-looking diagram would make their lives easier, and this is exactly what Mermaid.js aims to do.

If you want to add Mermaid to your documentation process, you should know that Mermaid is versatile and can be used in many different ways, as follows:

• Supports collaboration and sharing of diagrams via code snippets using the Mermaid Live Editor, where rendering happens by feeding code snippets to the Live Editor. This means that different members can alter the design in order to present an idea.
• Can be integrated into a site or a product. This allows you to add the necessary diagram rendering capabilities to the site or product.
• Can be integrated into a customized documentation system such as Docsify, Gatsby, and so on.
• Can be used to generate simple standalone diagrams using the Mermaid Live Editor and the mermaid-cli.
• With the help of custom plugins, it can be used in popular editors such as VSCode, Sublime Text, and so on. This way, charts and diagrams can be updated and changed, alongside the software project. This makes it easy to use and update documents.
• It is open source and free to use. There's no need for bulky and pricey tools for creating diagrams.

Apart from that, Mermaid can already be used in many established document sources/wikis and tools such as Confluence, GitLab, and so on.

Not sold on Mermaid yet? Listen to the experts in the industry. Mermaid.js won the "Most exciting use of technology" award at the JavaScript Open Source awards 2019.

Diagrams are a powerful tool in the documentation toolbox, but diagrams need context, text with broader meaning, as well as explanations of the diagrams themselves. A great solution for this is to use Mermaid together with Markdown. In the next section, we explain why Mermaid and Markdown fit so well together.

Blending Mermaid with Markdown

Now that we know about efficient documentation, we should explore how we can achieve this by switching the method of documentation to a text-based form of documentation. This can be done by using Markdown combined with Mermaid.

Markdown is a lightweight markup language that allows you to create formatted text using a regular text editor. The format of Markdown allows the author to write text with formatting, but without tags that make the text harder to read. The greatness of Markdown is that it's easy to write, as well as easy to read. This formatted text can then easily be transformed into other formats, such as HTML, for publishing.

Now, let's look at why you should consider using Mermaid together with Markdown:

• Minimize the number of distractions: We want to eliminate as many distractions as possible from documentation tasks. One such distraction is formatting – we have all been there, in that we've been distracted by a word processor's formatting possibilities and ended up focusing as much or more on how the document looked instead of focusing on writing the content. However, by writing the documentation in Markdown, we can avoid this. Mermaid helps you to create diagrams such as graphs, flowcharts, pie charts, and more directly from plain and simple text so that you don't need to switch to a different tool for them; Mermaid magically handles the layout, rendering, and formation of the diagram from the text input of the user.
• Manage versions of the documentation: When adding or changing a feature, it is great to be able to keep the updates in the documentation regarding that change, together with the actual feature in the code. This is usually achieved by creating a branch in the code repository where the changes are performed in isolation from the production code. If the documentation is text-based and is added to the same repository location as the project code, then the documentation changes that have been made for new features can be handled the same way as the code. This means the process of pushing code to the central repository is similar to the way you will push your changes in the documentation. This makes life easier for a developer as they are already accustomed to this process. The text files for the documentation would be added/changed in the branch without affecting the published documentation, and when the code changes are merged, the corresponding documentation changes would also be tagged.
• Stay focused with fewer context switches: Another way we can make documentation more efficient is by minimizing the context switches during development. Having the corresponding documentation in the same project as the code makes it possible to have a specification in one open tab in the integrated development environment (IDE) or editor while you're coding. This way, you have easy access to documentation while it's also available for modification. This scenario is quite easy to achieve and it doesn't take much effort to modify the document while implementing it. You might, for instance, want to add any missing details that surface during the implementation, adjust for some changes, or correct mistakes that have been identified at this stage.

With that, you have learned about the importance of using Mermaid together with Markdown. This combination sets up a powerful base for achieving efficient documentation since this approach aims at reducing any distractions, staying focused on writing the actual content rather than formatting, and supporting version control. In the next section, we'll look at how this combination can help when you're using a text-based documentation approach, along with your source code.

Blending text-based documentation with your code

If you have come so far as to have your documentation in text format by using Markdown and Mermaid, it could be a beneficial last step to move your documentation so that it resides close to your source code. This allows you to edit the documentation in the same context and environment where you code.

This helps reduce distractions when you're documenting as you wouldn't need to switch to another program; instead, you can continue in the same editor that you use for coding. Nor would you be distracted by a great number of formatting options, since most of the formatting will be handled automatically when you publish the documentation.

This setup also means that the documentation is available to read in your environment when you're writing code. This makes it quick and easy to modify documentation when something in the code has changed that needs to be reflected in the documentation; the threshold to actually perform that update is much lower if you need to perform a full context switch to make the change.

A context switch here would mean switching from your code editor, finding the right document, and updating it. Odds are that you lost the context of what you were doing in the source code before switching the documentation. With the documentation in your code project, you can simply open a tab in your editor that contains the documentation and update the documentation in parallel with the code.

Another example would be if you have the documentation in text form in a folder in your development project. Here, you could include the documentation folder when you are performing refactoring, such as a name change, and correct the documentation at the same time you're changing the code.

Making changes to the documentation in a Markdown file won't be any harder or more time-consuming than updating a code file.

When having the documentation text-based together with the code, it is effortless to practice efficient documentation:

• There are no distractions when you're writing.
• Easy to access when something needs to be created or updated.
• Easy to access when you need to read your documentation or code.
• Easy to see who made a change, what the change was, and when.
• Handles multiple simultaneous versions of the documentation.

With that, you have learned that having the documentation as part of your code project is efficient and makes working on the documentation tie in well with the other development tasks such as coding. In the next section, we will explore why Mermaid fits so well with Markdown.

Advantages of using Mermaid with Markdown

The main advantage of using Mermaid with Markdown is that you are using a readable text format that can generate diagrams. This is very powerful and provides loads of advantages:

• Using diagrams makes your documentation easier to understand, less intimidating, and, in effect, more informative. Having diagrams that can be changed as easily and quickly as your code is even better.
• You are working with text, so, as a developer, you are already a master of editing text.
• You can use your favorite text editor when writing the documentation.
• The combined format is fairly simple and can be picked up by any developer.
• You can keep the documentation in your code project while ensuring that you have efficient documentation, as highlighted in the previous section.
• The documentation in text format is readable in any text editor without being published.
• The process of formatting the documentation is separated from its content. By dodging this complexity, updates are easier to perform.
• The documentation in this form is text-based, which makes revision handling using Git, subversion, or similar very easy.

As you can see, Mermaid fits well with Markdown, and the pair offer many advantages when used together. The simplicity of text provides a productive environment for creating documentation in a similar way to coding. Taking this further and having the documentation adjacent to your code is a great way of making sure the documentation stays updated, as well as readily available, when it's needed during development. This also means that we can have different versions of the documentation in the same way as we have different versions of the code. Also, don't forget that even though we are using text as our format, we can show meaningful and descriptive diagrams to the reader, thanks to Mermaid.

Now, let's look at what we've learned in this section. First, you learned what Mermaid.js is and why it came into existence. You then learned how blending Mermaid.js with Markdown syntax can be a powerful combination for effective and efficient documentation. Finally, you learned about the key benefits of using Mermaid.js in a documentation system, and briefly understood the different ways in which Mermaid.js can be applied.