/mermaid-diagrams

Advanced Configuration & Styling

Theming, configuration, custom styling, and troubleshooting for Mermaid diagrams.

Contents

• Configuration — init directive
• Themes and Theme Variables
• Styling — classDef, style, linkStyle
• Layout Engine — ELK renderer
• Security Levels
• Troubleshooting — special characters, debugging
• Frontmatter Configuration
• Directive Reference
• Accessibility
• Performance Tips
• Export Options

Configuration

Init Directive

Configure diagrams using the init directive. It must be immediately followed by a diagram — a directive alone renders nothing:

%%{init: { 'theme': 'dark' } }%%
flowchart LR
    A --> B

Multi-Line Configuration

%%{init: {
  'theme': 'base',
  'themeVariables': {
    'primaryColor': '#3b82f6',
    'primaryTextColor': '#ffffff'
  }
}}%%
flowchart LR
    A --> B --> C

Themes

Built-in Themes

Usage

%%{init: {'theme': 'forest'}}%%
flowchart LR
    A --> B --> C

Theme Variables

Core Variables

Typography

Custom Theme Example

%%{init: {
  'theme': 'base',
  'themeVariables': {
    'primaryColor': '#3b82f6',
    'primaryTextColor': '#ffffff',
    'primaryBorderColor': '#2563eb',
    'secondaryColor': '#10b981',
    'tertiaryColor': '#f1f5f9',
    'lineColor': '#64748b',
    'textColor': '#1e293b',
    'fontSize': '16px',
    'fontFamily': 'Inter, sans-serif'
  }
}}%%
flowchart LR
    A[Start] --> B{Decision}
    B -->|Yes| C[Success]
    B -->|No| D[Failure]

Diagram-Specific Variables

Flowchart

Sequence Diagram

State Diagram

Gantt Chart

Styling

Class-Based Styling

Define Classes

flowchart LR
    A[Start]:::success --> B[Process]:::info --> C[End]:::warning

    classDef success fill:#10b981,stroke:#059669,color:white
    classDef info fill:#3b82f6,stroke:#2563eb,color:white
    classDef warning fill:#f59e0b,stroke:#d97706,color:white

Apply to Multiple Nodes

flowchart LR
    A --> B --> C --> D
    class A,D success
    class B,C info

    classDef success fill:#10b981
    classDef info fill:#3b82f6

Default Class

flowchart LR
    A --> B --> C

    classDef default fill:#f8fafc,stroke:#cbd5e1

Individual Node Styling

flowchart LR
    A --> B --> C

    style A fill:#10b981,stroke:#059669,color:white
    style B fill:#3b82f6,stroke:#2563eb,color:white
    style C fill:#ef4444,stroke:#dc2626,color:white

Style Properties

Link Styling

Individual Links

flowchart LR
    A --> B --> C --> D

    linkStyle 0 stroke:green,stroke-width:2px
    linkStyle 1 stroke:blue,stroke-width:2px
    linkStyle 2 stroke:red,stroke-width:2px,stroke-dasharray:5

All Links

flowchart LR
    A --> B --> C

    linkStyle default stroke:gray,stroke-width:1px

Layout Engine

ELK Renderer

For complex diagrams (v9.4+):

%%{init: {"flowchart": {"defaultRenderer": "elk"}} }%%
flowchart TB
    A --> B & C & D
    B & C & D --> E
    E --> F & G

Benefits:

• Better handling of complex layouts
• More predictable edge routing
• Improved subgraph positioning

Security Levels

Control what Mermaid can do:

%%{init: { 'securityLevel': 'loose' }}%%
flowchart LR
    A --> B
    click A href "https://example.com" _blank

Troubleshooting

Common Issues

Special Characters

Escape with HTML entities or quotes:

flowchart LR
    A["Node with #quot;quotes#quot;"]
    B["Arrow -> symbol"]
    C["Hash #35; symbol"]

HTML Entities

Long Labels

Use markdown strings:

flowchart LR
    A["`This is a very long
    label that wraps
    across multiple lines`"]

Debugging Tips

1. Check Syntax

• Verify diagram type declaration
• Check for unclosed brackets/quotes
• Ensure arrow syntax matches diagram type

2. Test Incrementally

• Start with minimal diagram
• Add elements one at a time
• Identify breaking change

3. Use Live Editor

Test at: https://mermaid.live

4. Platform Differences

• Check target platform support
• Some features are version-specific
• Export to PNG/SVG for guaranteed rendering

Arrow Syntax by Diagram Type

Arrow syntax does not transfer between diagram types — ->> in a flowchart or -.-> in a sequence diagram are parse errors.

Frontmatter Configuration

Alternative to init directive:

---
title: My Diagram
config:
  theme: forest
  flowchart:
    defaultRenderer: elk
---

flowchart LR
    A --> B

Directive Reference

Diagram Directives

Common Init Options

%%{init: {
  'theme': 'default',
  'themeVariables': { ... },
  'flowchart': {
    'defaultRenderer': 'elk',
    'curve': 'basis',
    'padding': 15
  },
  'sequence': {
    'showSequenceNumbers': true,
    'actorMargin': 50,
    'boxMargin': 10
  },
  'gantt': {
    'barHeight': 20,
    'fontSize': 11,
    'sectionFontSize': 14
  }
}}%%

Accessibility

accTitle and accDescr

Mermaid's built-in accessibility fields render as SVG <title>/<desc> for screen readers:

flowchart LR
    accTitle: Login flow
    accDescr: User submits credentials, the app validates them against the auth service
    A[User] --> B[App] --> C[Auth]

Alt Text

Also provide context in prose before diagrams:

The following diagram shows the authentication flow:

```mermaid
sequenceDiagram
    User->>App: Login
    App->>Auth: Validate

## ARIA Labels

When embedding in HTML:

```html
<div class="mermaid" role="img" aria-label="Authentication flow diagram">
  sequenceDiagram
    User->>App: Login
</div>

Performance Tips

1. Limit complexity - Split large diagrams
2. Use ELK for complex layouts
3. Minimize styling - Class-based over inline
4. Cache renders when possible
5. Lazy load in documentation

Export Options

From Live Editor

• PNG (transparent or white background)
• SVG (scalable)
• Markdown

Programmatic

import mermaid from 'mermaid';

const svg = await mermaid.render('id', diagramText);

CLI

# Single diagram file -> SVG (also .png, .pdf)
npx -y @mermaid-js/mermaid-cli -i diagram.mmd -o diagram.svg

# Markdown file: renders every ```mermaid block to an image, rewrites links
npx -y @mermaid-js/mermaid-cli -i input.md -o output.md

The CLI is also the fastest way to validate generated diagrams — a syntax error exits non-zero with a parse message.