Mermaid User Guide | Mermaid (2024)

Mermaid is composed of three parts ​

1. Deployment
2. Syntax
3. Configuration

This section talks about the different ways to deploy Mermaid.

If you are a beginner:

• Check out the Diagram Syntax page
• Check out the Tutorials page

Ways to use Mermaid ​

1. Using the Mermaid Live Editor
2. Using the Mermaid Chart Editor
3. Using Mermaid Plugins and Integrations
4. Calling the Mermaid JavaScript API
5. Adding Mermaid as a dependency

To learn more, visit the Usage page.

1. Using the Mermaid Live Editor ​

Available at the Mermaid Live Editor website.

Features ​

• Diagram Code ​

In the Code panel, write or edit Mermaid code, and instantly Preview the rendered result in the diagram panel.

Here is an example of Mermaid code and its rendered result:

• Configurations ​

Configuration options are available in the Configuration panel. The options are applied to the diagram in the Preview panel.

To learn more, visit the Configuration Reference page

• Editing History ​

Your code will be autosaved and appear in the Timeline tab of the History section. Edits are saved every minute and only the last 30 edits are viewable.

Alternatively, you can manually save code by clicking on the Save icon from the History section.

• Saving a diagram ​

There are multiple ways of saving your diagram from the Actions section:

• export PNG
• export SVG
• export as Markdown

• Editing your diagrams ​

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
• use a Sample Diagram from the Sample Diagrams section

• Loading from Gists ​

The Gist you create should have a code.mmd file and optionally a config.json, similar to this example.

Once you have created a Gist, copy paste the Gist URL into the respective field in the Actions section and click on the Load Gist button.

Here is an example of a Gist being loaded into the Editor:

https://mermaid.live/edit?gist=https://gist.github.com/sidharthv96/6268a23e673a533dcb198f241fd7012a

And, here is the diagram view from the above example:

https://mermaid.live/view?gist=https://gist.github.com/sidharthv96/6268a23e673a533dcb198f241fd7012a

2. Using the Mermaid Chart Editor ​

Available at the Mermaid Chart website.

Mermaid Chart is a web-based diagram editor that allows you to create and edit diagrams in your browser. It is built by the team behind Mermaid.

Features include:

• AI diagramming
• Collaboration & multi-user editing
• Storage
• and more

To learn more, visit the Mermaid Chart page in the Ecosystem section of the documentation.

Or go to the Mermaid Chart website to sign up for a Free account.

3. Using Mermaid Plugins ​

Mermaid Plugins ​

You can generate Mermaid diagrams from within popular applications using plug-ins.

For a list of Mermaid Plugins and Integrations, visit the Integrations page.

Mermaid Chart Plugins ​

Mermaid Chart plugins are available for:

• ChatGPT
• JetBrains IDE
• Microsoft PowerPoint
• Microsoft Word
• Visual Studio Code

To learn more, visit the Mermaid Chart Plugins page.

Native Mermaid Support ​

For apps that support markdown (e.g. GitHub and GitLab), you can add Mermaid diagrams by making a mermaid code block.

The following code-block will be rendered as a Mermaid diagram:```mermaidflowchart LR A --> B```

4. Calling the Mermaid JavaScript API ​

This method can be used with any common web server like Apache, IIS, Nginx, and Node Express.

You will also need a text editing tool like Notepad++ to generate an html file. It is then deployed by a web browser, i.e. Firefox, Chrome, Safari.

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 the Mermaid library through the mermaid.esm.mjs or mermaid.esm.min.mjs, and the mermaid.initialize() call, which dictates the appearance of diagrams and also starts the rendering process.

Examples ​

• This is an example of an embedded Mermaid diagram definition inside a <pre class="mermaid">:

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

• This is an example of a Mermaid import and the mermaid.initialize() call.

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

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

In this example, the mermaidAPI is being called through the CDN:

<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@11/dist/mermaid.esm.min.mjs'; mermaid.initialize({ startOnLoad: true }); </script> </body></html>

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

<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>

5. Adding Mermaid as a dependency ​

Below are the steps for adding Mermaid as a dependency:

1. Install node v16

1. Install yarn using npm with this command:

   npm install -g yarn

2. After yarn installs, enter this command:

   yarn add mermaid

3. To add Mermaid as a dev dependency, enter this command:

   yarn add --dev mermaid

Closing note ​