Mermaid.js: A Complete Guide

What Is Mermaid.js?

Mermaid.js is a JavaScript library that provides an easy-to-use syntax for creating various types of diagrams and flowcharts. Its versatility makes it suitable for use in technical writing, software development, and other professional contexts where visualizing complex information is necessary.

With Mermaid, users can create diagrams such as flowcharts, sequence diagrams, Gantt charts, and class diagrams, and easily integrate them into websites, blogs, and documentation. This open-source tool is available for both personal and commercial use, making it a flexible solution for a wide range of applications.

This is part of an extensive series of guides about software development.

7 key features of Mermaid.js

Mermaid.js is a versatile and feature-rich JavaScript library for creating diagrams and flowcharts using simple markdown-like text syntax. Here are some of the key features of Mermaid.js:

1. Simple syntax: Mermaid.js uses a simple and easy-to-learn syntax for defining diagrams and flowcharts, similar to Markdown syntax. This makes it accessible to developers, technical writers, and other users without prior experience in graphic design or diagramming.
2. Multiple diagram types: Mermaid.js supports a wide range of diagrams and flowcharts, including sequence diagrams, Gantt charts, class diagrams, state diagrams, and flowcharts.
3. Customizable styling: Mermaid.js allows users to customize the styling of diagrams and flowcharts using CSS, including the colors, fonts, and sizes of nodes, edges, and other elements.
4. Dynamic rendering: Mermaid.js can generate diagrams and flowcharts dynamically in web applications or static documentation pages without needing to draw them manually.
5. Integration with other frameworks: Mermaid.js can be integrated with popular web frameworks, such as React, Angular, and Vue.js, using the appropriate bindings or plugins.
6. Export to different formats: Mermaid.js allows users to export diagrams and flowcharts in various image formats, such as SVG, PNG, and PDF.

How to get started with Mermaid.js

There are four main ways to use Mermaid.js:

• The Mermaid Live Editor: This is an online tool that allows you to experiment with and learn how to use Mermaid. You can create diagrams using a simple syntax and preview them in real-time.
• Plugins: Mermaid can be used with editor plugins such as Visual Studio Code, Atom, and Sublime Text, which provide syntax highlighting, code completion, and other helpful features.
• The Mermaid.js API: The Mermaid.js API allows you to integrate Mermaid into your own applications and projects.
• Deployment as a dependency: Mermaid can be installed as a dependency using Node.js or another package manager such as npm or yarn. This approach is recommended for production use.

Working with the Mermaid Live Editor

To use the editor, simply go to the Mermaid website and click on the Live Editor tab.

The editor has several sections, including:

• The Code section: This is where you can write and edit raw code. The syntax is simple and easy to learn, and the editor provides helpful suggestions and error messages as you work.
• The Preview section: This section shows you a real-time preview of your diagram as you write code. You can adjust the size and zoom level of the preview to suit your needs.
• The Configuration section: This section allows you to customize the look and feel of your diagram, including font size, color, and shape.
• The History section: Your code is automatically saved every minute, but you can also save it manually to the History section. This makes it easy to revisit previous versions of your diagram and track your progress over time.

Working with a Mermaid Plugin

Mermaid.js plugins are add-ons that allow you to integrate with different web frameworks and extend the functionality of the Mermaid library. They can be used to enhance the user experience, add new features and customization options, and improve performance.

Some examples of Mermaid plugins include syntax highlighting plugins for text editors, integration plugins for popular content management systems, and charting plugins for data visualization.

Working with the API

You can call the Mermaid JavaScript API directly in your code. The API allows you to create and render diagrams programmatically, without needing to use the Mermaid syntax. You can pass diagram data to the API as a string, and the API will generate an SVG or HTML representation of the diagram. This allows you to integrate Mermaid into your own applications and workflows, and provides more control over the diagram creation and rendering process.

To generate HTML files, you need to use a text editor such as Notepad++, which can be deployed by your web browser (Chrome, Firefox, or Safari).

Adding Mermaid.js as a dependency

To add Mermaid.js as a dependency in your project, you can use Node.js or a package manager such as npm or yarn. Here’s how to do it using yarn:

1. Install yarn if you haven’t already.
2. Navigate to your project directory in the command line.
3. Run the command yarn add mermaid to install Mermaid as a dependency.
4. Optionally, you can also add Mermaid as a dev dependency by running the command yarn add -D mermaid.
5. Import the Mermaid library in your project code as needed.

This approach allows you to use Mermaid in your project without relying on external scripts or online tools.

Mermaid.js syntax and configuration

Mermaid has a syntax for building diagrams. For example, every diagram has a definition beginning with the diagram type, followed by the description of the diagram’s contents. This element tells the parser what type of diagram is meant to be generated.

To signal you’re writing a Mermaid diagram, wrap your code block in a pair of triple backticks (“`) followed by the keyword “mermaid” to indicate that the block should be interpreted as a Mermaid.js diagram.

The basic syntax elements in Mermaid.js include:

• Node: Represents an entity in the diagram. Nodes are created by providing a unique identifier followed by a pair of square brackets containing the node’s label. Example: A[Node A]
• Link: Connects nodes with arrows or lines. Example: A–>B (arrow), A—B (line)
• Direction: Defines the layout direction using ‘graph’. Example: graph TB (top-to-bottom), graph LR (left-to-right)
• Subgraph: Groups related nodes together. Example: subgraph Title, end
• Styling: Customize the appearance of nodes, links, and text using CSS-like styles. Example: A[Node A] {stroke: #333; fill: #FFF}

Sequence diagrams, Gantt charts, and other diagram types have their specific syntax elements (described in Mermaid’s documentation), but the principles remain the same: simple, human-readable text that generates visually appealing diagrams. With Mermaid.js, you can create complex diagrams while maintaining version control and collaboration.

Here is an example of the code for an entity relationship diagram (erDiagram) declaration. 

To configure Mermaid.js, use the mermaid.initialize() function, which accepts a configuration object with various properties for customizing the appearance and behavior of diagrams. The configuration object allows you to set themes, alter arrow markers, modify font styles, and more.

Here’s an example of how to set a custom configuration:

mermaid.initialize({

  startOnLoad: true,

  theme: ‘forest’,

  sequence: {

    diagramMarginX: 50,

    diagramMarginY: 10,

    actorMargin: 50,

    width: 150,

    height: 65,

    boxMargin: 10,

    boxTextMargin: 5,

    messageMargin: 35,

    mirrorActors: true,

  },

  flowchart: {

    htmlLabels: false,

    curve: ‘linear’,

  },

});

In this example, we set the theme to ‘forest’, define sequence diagram properties such as margins, and adjust flowchart settings. The initialize function should be called before rendering diagrams to ensure the configuration is applied.

Mermaid.js alternatives

PlantUML

PlantUML is a diagramming tool that enables users to generate diagrams through a simple syntax. It has the following features:

• Text-based diagram generation: PlantUML allows users to create diagrams using plain text, which simplifies collaboration, version control, and integration with other text-based tools.
• Open-source: It provides users with free access to its vast range of diagram types, including flowcharts, sequence diagrams, activity diagrams, and class diagrams.
• Smart layouts: PlantUML’s smart layout algorithms automatically organize and align diagram elements, ensuring that the resulting diagrams are professional-looking and easy to comprehend.
• Customizability: Users can adjust their diagrams’ appearance, including font size, color, and shape, using a variety of configuration options. This feature enables users to create diagrams that meet their projects’ specific requirements and match their visual style.

Graphviz

Graphviz is a widely-used open-source tool that allows users to visualize data and information through automated diagrams and graphs. Here are some key features of Graphviz:

• Graph generation: It provides a simple way to generate graphs and networks programmatically, allowing users to create complex diagrams quickly and efficiently.
• Input file format: It uses a plain text input file to define graphs and their properties, including nodes, edges, labels, and styles.
• Output formats: It generates diagrams in a range of formats, including PDF, SVG, and PNG, making it easy to incorporate diagrams into various documents and applications.
• Wide usage: It is popular in scientific research, engineering, and other technical fields where the visualization of large amounts of data is necessary for understanding and analyzing complex systems.

Kroki

Kroki is an open-source project that provides a unified API for generating diagrams and charts using simple text-based commands. It is designed to simplify the process of creating diagrams and charts by allowing users to focus on the content rather than the layout and styling.

Kroki supports a wide range of diagram and chart types, including UML diagrams, flowcharts, sequence diagrams, Gantt charts, and more. The diagrams and charts are generated dynamically on the server-side and returned as SVG, PNG, or PDF images.

Kroki provides a simple RESTful API for generating diagrams and charts using text-based commands. You can send a request to the Kroki API with a diagram definition in the request body, and Kroki will generate the diagram and return it as an image.

Draw.io

Diagrams.net, formerly known as Draw.io, is a free online diagramming tool that offers a variety of features for creating professional-looking diagrams quickly and easily. Key features include:

• Diagram types: It provides a wide range of diagram types, including flowcharts, network diagrams, mind maps, and more.
• Availability: It is available both online and offline, as a cross-browser web application or desktop app, making it convenient to use on various platforms.
• Integration: It can integrate with popular cloud storage services, including Dropbox, Google Drive, and GitHub, allowing users to save and view their diagrams easily from different locations.

Draw.io’s user-friendly interface, wide range of diagram types, and integration with cloud storage services make it a versatile and convenient tool for both personal and professional use.

How do Mermaid.js alternatives compare?

The following table shows how the four alternative tools we reviewed above compare to Mermaid.js.

Tool	Diagram Types	Syntax Simplicity	Customization Options	Output Formats	Integration Capabilities
Mermaid.js	Flowcharts, sequence diagrams, Gantt charts, etc.	High	Colors, fonts, themes	SVG, PNG	GitHub, GitLab, Markdown editors, JavaScript apps
PlantUML	Flowcharts, sequence diagrams, class diagrams, etc.	High	Colors, fonts, shapes	SVG, PNG, ASCII, etc.	GitHub, GitLab, IDEs, text-based tools
Graphviz	Graphs, networks, hierarchical layouts	Medium	Colors, fonts, styles, labels	PDF, SVG, PNG, etc.	Command-line interface, various programming APIs
Kroki	UML diagrams, flowcharts, Gantt charts, etc.	High	Depends on the diagram source syntax	SVG, PNG, PDF	RESTful API, server-side integration
Draw.io	Flowcharts, network diagrams, mind maps, etc.	N/A (GUI-based)	Colors, fonts, styles, shapes	PNG, JPEG, SVG, PDF	Dropbox, Google Drive, GitHub, browser extensions

Mermaid.js with Swimm

Without a doubt, Mermaid.js is an excellent tool for visualizing code, the output of which is not just developer-friendly, but truly easy to understand. That said, at Swimm, in homage to the old saying, if a visualization is made, but no one can find it, is it really there?

Hyperbole aside, Mermaid.js’s diagrams are often integral and necessary parts of code documentation. When new team members need to get up to speed, visualizations can be far more efficient in terms of education tools than simple text descriptions, particularly in the case of more visual learners. And yet, we repeat our previous question.

With Swimm, let your docs come to you – not the other way around – the moment they’re required. The act of documentation might be a hassle, but Swimm docs can live in the IDE & CI/CD, wherever they’re needed most – saving you time and money, particularly when it comes to arduous onboarding processes.

Learn more about Swimm today!

See Additional Guides on Key Software Development Topics

Together with our content partners, we have authored in-depth guides on several other topics that can also be useful as you explore the world of software development.

Code Documentation

Authored by Swimm

• Agile Documentation: Benefits and Best Practices 
• Documentation as Code: Why You Need It & How to Get Started
• What Is Code Documentation and How To Write It? 

Technical Documentation

Authored by Swimm

• What is Technical Documentation and How to Create it? 
• Get started with technical documentation writing best practices 
• Essential Resources for Technical Documentation Templates

Dotenv

Authored by Configu

• Managing Environment Variables With dotenv 
• Using Py Dotenv (python-dotenv) Package to Manage Env Variables –
• Using npm dotenv Package to Manage Node.js Environment Variables –