T03: Installing and Setting Up Mermaid

3.1 Installation Philosophy

Mermaid is not a standalone desktop application. It is a JavaScript-based rendering engine that can be:

Embedded in web pages
Used inside Markdown environments
Rendered via CLI
Integrated into documentation pipelines

Before installing, understand your usage model:

Use Case

Recommended Setup

Quick Markdown usage

GitHub / GitLab native support

Local development

VS Code extension

Static site documentation

Mermaid via npm

CI/CD rendering

Mermaid CLI

Web app integration

Mermaid JS library

We will cover all major setups.

3.2 Method 1 — Using Mermaid in GitHub (Zero Installation)

GitHub supports Mermaid natively inside Markdown.

Example

```mermaid
flowchart TD
    A[Start] --> B[Deploy]
    B --> C[Production]
```

Steps:

Create a .md file.
Add the Mermaid code block.
Push to GitHub.
GitHub renders it automatically.

No installation required.

Best for:

README diagrams
Architecture docs
Open-source projects

3.3 Method 2 — Installing Mermaid via npm (Local Setup)

If you want full control locally, install Mermaid via Node.js.

Step 1: Install Node.js

Verify installation:

node -v
npm -v

If not installed, download from: https://nodejs.org

Step 2: Initialize a Project

mkdir mermaid-project
cd mermaid-project
npm init -y

Step 3: Install Mermaid

npm install mermaid

This installs the Mermaid JavaScript library into node_modules.

3.4 Using Mermaid in an HTML Page

Create a file:

touch index.html

Add the following content:

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

<div class="mermaid">
flowchart LR
    A[Client] --> B[Server]
    B --> C[Database]
</div>

</body>
</html>

Open in browser.

Mermaid will render automatically.

3.5 Method 3 — Installing Mermaid CLI (Professional Setup)

Mermaid CLI allows rendering diagrams into SVG/PNG from terminal.

This is critical for:

CI/CD
Automated documentation
Static exports

Step 1: Install CLI Globally

npm install -g @mermaid-js/mermaid-cli

Verify installation:

mmdc -h

Step 2: Create a Mermaid File

Create:

architecture.mmd

Add:

Step 3: Render to SVG

mmdc -i architecture.mmd -o architecture.svg

Output:

architecture.svg

You now have a production-ready diagram.

3.6 Rendering to PNG

mmdc -i architecture.mmd -o architecture.png

3.7 Using Mermaid in VS Code

Install extension:

Search: “Mermaid Markdown Preview”
Install extension
Open .md file
Use Preview mode

Example Markdown:

```mermaid
sequenceDiagram
    User->>Server: Request
    Server-->>User: Response
```

Preview renders live.

3.8 Setting Default Configuration

Mermaid supports configuration options.

Example:

<script type="module">
import mermaid from 'https://cdn.jsdelivr.net/npm/mermaid@10/dist/mermaid.esm.min.mjs';

mermaid.initialize({
  startOnLoad: true,
  theme: 'dark',
  flowchart: {
    curve: 'basis'
  }
});
</script>

Themes available:

default
dark
forest
neutral

3.9 CLI Configuration File

You can create a config file:

config.json

Example:

{
  "theme": "dark",
  "flowchart": {
    "curve": "basis"
  }
}

Use it:

mmdc -i architecture.mmd -o architecture.svg -c config.json

3.10 Production Integration Example

Suppose your documentation build pipeline runs:

mmdc -i diagrams/system.mmd -o docs/assets/system.svg

You can add this to:

GitHub Actions
GitLab CI
Jenkins
Azure DevOps

Example GitHub Action step:

- name: Generate Mermaid Diagrams
  run: |
    npm install -g @mermaid-js/mermaid-cli
    mmdc -i architecture.mmd -o architecture.svg

Now diagrams regenerate automatically on every commit.

3.11 Troubleshooting Common Issues

1. “mmdc: command not found”

Fix:

npm install -g @mermaid-js/mermaid-cli

2. Node Version Too Old

Upgrade Node:

node -v

Mermaid requires modern Node versions.

3. Browser Module Errors

Ensure:

type="module"

is included in <script> tag.

3.12 Hands-On Lab

Exercise 1

Install Mermaid CLI.
Create flow.mmd.
Add:

Render to SVG.
Change direction to TD.
Re-render.

Observe how code change affects output.

3.13 Choosing the Right Setup

Scenario

Recommended Method

README diagrams

GitHub native

Developer workflow

VS Code

Documentation site

npm library

CI rendering

Mermaid CLI

Web product

JS integration

3.14 Key Takeaway

Mermaid installation is flexible because it is:

JavaScript-based
Platform-agnostic
Automation-ready
CI/CD compatible

You do not “install a tool” in the traditional sense.

You integrate a rendering engine into your workflow.

In the next chapter, we will dive into Flowcharts, the most commonly used Mermaid diagram type, and explore their syntax in depth.

PreviousT02: Why Use Diagram-as-Code NextCH02: Flowcharts

Last updated 1 month ago

hashtag3.1 Installation Philosophy

hashtag3.2 Method 1 — Using Mermaid in GitHub (Zero Installation)

hashtagExample

hashtag3.3 Method 2 — Installing Mermaid via npm (Local Setup)

hashtagStep 1: Install Node.js

hashtagStep 2: Initialize a Project

hashtagStep 3: Install Mermaid

hashtag3.4 Using Mermaid in an HTML Page

hashtag3.5 Method 3 — Installing Mermaid CLI (Professional Setup)

hashtagStep 1: Install CLI Globally

hashtagStep 2: Create a Mermaid File

hashtagStep 3: Render to SVG

hashtag3.6 Rendering to PNG

hashtag3.7 Using Mermaid in VS Code

hashtag3.8 Setting Default Configuration

hashtag3.9 CLI Configuration File

hashtag3.10 Production Integration Example

hashtag3.11 Troubleshooting Common Issues

hashtag1. “mmdc: command not found”

hashtag2. Node Version Too Old

hashtag3. Browser Module Errors

hashtag3.12 Hands-On Lab

hashtagExercise 1

hashtag3.13 Choosing the Right Setup

hashtag3.14 Key Takeaway