A Mermaid User-Guide for Beginners (2024)

Mermaid is composed of three parts: Deployment, Syntax and Configuration.

This section talks about the different ways to deploy Mermaid. Learning the Syntax would be of great help to the beginner.

Generally the live editor is enough for most general uses of mermaid, and is a good place to start learning.

Absolute beginners are advised to view the Video Tutorials on the Live Editor, to gain a better understanding of mermaid.

Four ways of using mermaid: #

  1. Using the Mermaid Live Editor at mermaid.live.
  2. Using mermaid plugins with programs you are familiar with.
  3. Calling the Mermaid JavaScript API.
  4. Deploying Mermaid as a dependency.

Note: It is our recommendation that you review all approaches, and choose the one that is best for your project.

More in depth information can be found at Usage.

1. Using the Live Editor #

Available at mermaid.live

null

In the Code section one can write or edit raw mermaid code, and instantly Preview the rendered result on the panel beside it.

The Configuration Section is for changing the appearance and behavior of mermaid diagrams. An easy introduction to mermaid configuration is found in the Advanced usage section. A complete configuration reference cataloging the default values can be found on the mermaidAPI page.

A Mermaid User-Guide for Beginners (1)

Editing History #

Your code will be autosaved every minute into the Timeline tab of History which shows the most recent 30 items.

You can manually save code by clicking the Save icon in the History section. It can also be accessed in the Saved tab. This is stored in the browser storage only.

Saving a Diagram: #

You may choose any of the methods below, to save it

We recommend that you save your diagram code on top of any method you choose, in order to make edits and modifications further down the line.

A Mermaid User-Guide for Beginners (2)

Editing your diagrams #

Editing is as easy as pasting your Diagram code, into the code section of the Live Editor.

Loading from Gists #

The Gist you create should have a code.mmd file and optionally a config.json. Example

To load a gist into the Editor, you can use https://mermaid.live/edit?gist=https://gist.github.com/sidharthv96/6268a23e673a533dcb198f241fd7012a

and to View, https://mermaid.live/view?gist=https://gist.github.com/sidharthv96/6268a23e673a533dcb198f241fd7012a

2. Using Mermaid Plugins: #

You can generate mermaid diagrams from within popular applications using plug-ins. It can be done in the same way, you would use the Live Editor. Here's a list of Mermaid Plugins.

This is covered in greater detail in the Usage section

3. Calling the JavaScript API #

This method can be used with any common web server like Apache, IIS, nginx, node express.

You will also need a text editing tool like Notepad++ to generate a .html file. It is then deployed by a web browser (such as Firefox, Chrome, Safari, but not Internet Explorer).

The API works by pulling rendering instructions from the source mermaid.js in order to render diagrams on the page.

Requirements for the Mermaid API. #

When writing the .html file, we give two instructions inside the html code to the web browser:

a. The mermaid code for the diagram we want to create.

b. The importing of mermaid library through the mermaid.esm.js or mermaid.esm.min.mjs and the mermaid.initialize() call, which dictates the appearance of diagrams and also starts the rendering process .

a. The embedded mermaid diagram definition inside a <pre class="mermaid">:

html

<body> Here is a mermaid diagram: <pre class="mermaid"> graph TD  A[Client] --> B[Load Balancer]  B --> C[Server01]  B --> D[Server02] </pre></body>

Notes: Every Mermaid chart/graph/diagram definition, should have separate <pre> tags.

b. The import of mermaid and the mermaid.initialize() call.

mermaid.initialize() call takes all the definitions contained in all the <pre class="mermaid"> tags that it finds in the html body and renders them into diagrams. Example:

html

<body> <script type="module"> import mermaid from 'https://cdn.jsdelivr.net/npm/mermaid@<MERMAID_VERSION>/dist/mermaid.esm.min.mjs'; mermaid.initialize({ startOnLoad: true }); </script></body>

Notes: Rendering in Mermaid is initialized by mermaid.initialize() call. You can place mermaid.initialize() inside mermaid.min.js for brevity. However, doing the opposite lets you control when it starts looking for <div>tags inside the web page with mermaid.initialize(). This is useful when you think that not all <div> tags may have loaded on the execution of mermaid.min.js file.

startOnLoad is one of the parameters that can be defined by mermaid.initialize()

ParameterDescriptionTypeValues
startOnLoadToggle for Rendering upon loadingBooleantrue, false

Working Examples #

Here is a full working example of the mermaidAPI being called through the CDN:

html

<html> <body> Here is one mermaid diagram: <pre class="mermaid"> graph TD  A[Client] --> B[Load Balancer]  B --> C[Server1]  B --> D[Server2] </pre> And here is another: <pre class="mermaid"> graph TD  A[Client] -->|tcp_123| B B(Load Balancer)  B -->|tcp_456| C[Server1]  B -->|tcp_456| D[Server2] </pre> <script type="module"> import mermaid from 'https://cdn.jsdelivr.net/npm/mermaid@<MERMAID_VERSION>/dist/mermaid.esm.min.mjs'; mermaid.initialize({ startOnLoad: true }); </script> </body></html>

Another Option: In this example mermaid.js is referenced in src as a separate JavaScript file, in an example Path.

html

<html lang="en"> <head> <meta charset="utf-8" /> </head> <body> <pre class="mermaid"> graph LR  A --- B  B-->C[fa:fa-ban forbidden]  B-->D(fa:fa-spinner); </pre> <pre class="mermaid"> graph TD  A[Client] --> B[Load Balancer]  B --> C[Server1]  B --> D[Server2] </pre> <script type="module"> import mermaid from 'The/Path/In/Your/Package/mermaid.esm.mjs'; mermaid.initialize({ startOnLoad: true }); </script> </body></html>

4. Adding Mermaid as a dependency. #

  1. install node v16, which would have npm

  2. download yarn using npm by entering the command below: npm install -g yarn

  3. After yarn installs, enter the following command: yarn add mermaid

  4. To add Mermaid as a Dev Dependency yarn add --dev mermaid

Comments from Knut Sveidqvist, creator of mermaid:

  • In early versions of mermaid, the <script> tag was invoked in the <head> part of the web page. Nowadays we can place it in the <body> as seen above. Older parts of the documentation frequently reflects the previous way which still works.
A Mermaid User-Guide for Beginners (2024)

FAQs

What is a Mermaid code? ›

Mermaid diagrams are code-based diagrams that represent structures and processes, generated using Markdown-inspired text definitions that are easy to write and modify.

Where can I paste a Mermaid code? ›

To edit your diagram, you can copy paste existing Mermaid diagram code into the Code section of the Live Editor . Or: create a new diagram from scratch.

Is Mermaid free to use? ›

MERMAID is free (as in both speech and beer) and its code is open source, and is based on a core set of open-source components, which are themselves based on open and standardized languages and platforms (Python, R, Debian, nginx, gunicorn, JavaScript, etc.).

Is Mermaid.js good? ›

Overall, Mermaid. js is fairly easy to use (once the platform supports the definition) if a bit more limiting than a more powerful tool like Google Slides. It'll more than likely become my go-to approach for creating diagrams and I'll resort to my old methods if I need something very specific.

What is the mermaid script? ›

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: Simple syntax: Mermaid.

Is mermaid a coding language? ›

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.

What can I use instead of Mermaid code? ›

Top Mermaid. js Alternatives
  • PlantUML. PlantUML is a text-based diagram generation tool that allows users to generate various types of diagrams using a simple syntax. ...
  • Graphviz. ...
  • Kroki. ...
  • D2. ...
  • Draw.io.

How to generate a diagram from a Mermaid code? ›

To create a Mermaid diagram, add Mermaid syntax inside a fenced code block with the mermaid language identifier. For more information about creating code blocks, see "Creating and highlighting code blocks." For example, you can create a flow chart by specifying values and arrows.

What is the code for the Mermaid emoji? ›

Mermaid Emoji (U+1F9DC, U+200D, U+2640, U+FE0F)

What is a mermaid editor? ›

Mermaid lets you create diagrams and visualizations using text and code. It is a JavaScript based diagramming and charting tool that renders Markdown-inspired text definitions to create and modify diagrams dynamically. If you are familiar with Markdown you should have no problem learning Mermaid's Syntax.

What is mermaid AI? ›

Mermaid Chart works by allowing you to create diagrams using text. You can create a wide range of diagrams including flowcharts, sequence diagrams, git graphs, and more.

Is the mermaid editor free? ›

Free - A free plan that includes five diagrams. Pro - A paid plan that includes unlimited diagrams, access to the collaboration feature, and more. Enterprise - A paid plan for enterprise use that includes all Pro features, and more.

What is mermaid syntax? ›

Mermaid is a syntax similar to Markdown where you can use text to describe and automatically generate diagrams.

Is mermaid better than PlantUML? ›

In terms of setup, Mermaid is the simplest as you don't need to set up any external applications or servers. Winner: Mermaid. In terms of customisation, PlantUML has been around far longer and supports advanced diagram customisation. Mermaids support is more limited.

How do I download a diagram from Mermaid? ›

Mermaid Chart support multiple export formats🔗

You can export your diagram to PNG, SVG, or MMD. From the Export dropdown, select the format you want to export your diagram to.

What does the mermaid symbol mean? ›

In some cultures, the mermaid signifies life and fertility within the ocean. In others, she embodies the destructive nature of the water, luring sailors to their deaths — serving as an omen for storms, unruly seas and disaster.

How does a mermaid chart work? ›

Mermaid lets you create diagrams and visualizations using text and code. It is a JavaScript based diagramming and charting tool that renders Markdown-inspired text definitions to create and modify diagrams dynamically. If you are familiar with Markdown you should have no problem learning Mermaid's Syntax.

What is the code for the mermaid emoji? ›

Mermaid Emoji (U+1F9DC, U+200D, U+2640, U+FE0F)

How to generate a diagram from a mermaid code? ›

To create a Mermaid diagram, add Mermaid syntax inside a fenced code block with the mermaid language identifier. For more information about creating code blocks, see "Creating and highlighting code blocks." For example, you can create a flow chart by specifying values and arrows.

Top Articles
Latest Posts
Recommended Articles
Article information

Author: Tyson Zemlak

Last Updated:

Views: 6031

Rating: 4.2 / 5 (43 voted)

Reviews: 82% of readers found this page helpful

Author information

Name: Tyson Zemlak

Birthday: 1992-03-17

Address: Apt. 662 96191 Quigley Dam, Kubview, MA 42013

Phone: +441678032891

Job: Community-Services Orchestrator

Hobby: Coffee roasting, Calligraphy, Metalworking, Fashion, Vehicle restoration, Shopping, Photography

Introduction: My name is Tyson Zemlak, I am a excited, light, sparkling, super, open, fair, magnificent person who loves writing and wants to share my knowledge and understanding with you.