Mermaid Configuration

In Mermaid, Configuration allows you to globally control how diagrams render, look, and behave. Configurations are passed at the absolute top of a diagram using YAML Front Matter fronted by triple dashes (---), or through a single-line %%{init: ...}%% directive.

Configuration Options

Mermaid configuration can control themes, security, layout, and diagram-specific behavior.

Example:

* * *
theme: dark
securityLevel: loose
gantt:
    axisFormat: '%Y-%m-%d'
* * *

JavaScript Configuration

When Mermaid is used through JavaScript:

mermaid.initialize({
    startOnLoad: true,
    theme: "dark"
});

Try this code ❯

Frontmatter vs Legacy Directives

The source describes older directives such as:

%%{init: {"theme":"dark"}}%%

Example:

%%{init: {"theme": "dark"}}%%
flowchart TD
    A --> B

The source identifies these directives as deprecated and recommends YAML frontmatter or API configuration for modern usage.

Configuration Table

Option	Purpose
`theme`	Controls the diagram theme
`securityLevel`	Controls JavaScript/link security behavior
`startOnLoad`	Controls automatic rendering on page load
`flowchart`	Flowchart-specific configuration
`sequence`	Sequence-diagram configuration
`gantt`	Gantt-specific configuration

Example:

* * *
theme: dark
securityLevel: strict
startOnLoad: true
* * *

1. Basic Configuration

---
config:
  theme: default
---
flowchart TD
    A[Start] --> B[Process]
    B --> C[End]

Try this code ❯

2. Theme Configuration

---
config:
  theme: base
  themeVariables:
    primaryColor: "#E05349"
    primaryTextColor: "#ffffff"
    primaryBorderColor: "#B83E35"
    lineColor: "#555555"
---
flowchart TD
    A[Start] --> B[Process]
    B --> C[End]

Try this code ❯

3. Flowchart Configuration

You can configure the flowchart renderer and spacing:

---
config:
  flowchart:
    defaultRenderer: elk
    nodeSpacing: 50
    rankSpacing: 50
---
flowchart TD
    A[Start] --> B[Process]
    B --> C[End]

Try this code ❯

4. Sequence Diagram Configuration

---
config:
  sequence:
    actorMargin: 50
    messageMargin: 40
    boxMargin: 10
---
sequenceDiagram
    Alice->>Bob: Hello Bob
    Bob-->>Alice: Hello Alice

Try this code ❯

5. Pie Chart Configuration

---
config:
  pie:
    textPosition: 0.75
---
pie
    title Favorite Fruits
    "Apples" : 40
    "Bananas" : 30
    "Oranges" : 20
    "Grapes" : 10

Try this code ❯

6. Multiple Configuration Options

---
config:
  theme: base
  themeVariables:
    primaryColor: "#E05349"
    primaryTextColor: "#ffffff"
  flowchart:
    defaultRenderer: elk
    nodeSpacing: 40
    rankSpacing: 50
---
flowchart TD
    A[Start] --> B[Process]
    B --> C[End]

Try this code ❯

Configuration structure

---
config:
  theme: ...
  themeVariables:
    ...
  flowchart:
    ...
  sequence:
    ...
  pie:
    ...
---

The exact configuration options depend on the Mermaid diagram type.