# How Mermaid `%%{initialize: {...}}%%` Directives Work and What Runtime Settings They Configure

> Learn how Mermaid directives like %{initialize: ...}% inject runtime configuration for per-diagram theming logging and layout controls directly into your diagram definitions.

- Repository: [mermaid-js/mermaid](https://github.com/mermaid-js/mermaid)
- Tags: internals
- Published: 2026-02-23

---

**Mermaid directives are special comment blocks that inject runtime configuration directly into diagram definitions, allowing per-diagram theming, logging, and layout controls without modifying global JavaScript settings.**

The mermaid-js/mermaid library supports inline configuration through initialization directives embedded directly in diagram source code. These `%%{initialize: {...}}%%` blocks provide granular control over rendering behavior, security constraints, and layout engines. Understanding how these directives parse, sanitize, and apply settings reveals how to customize individual diagrams while maintaining the integrity of the rendering pipeline.

## How Mermaid Parses Initialization Directives

### Detecting Directive Blocks

When Mermaid processes diagram text, the `detectDirective()` function in [`src/utils.ts`](https://github.com/mermaid-js/mermaid/blob/main/src/utils.ts) (lines 60-90) scans for any `%%{ … }%%` block. This function first strips ordinary comments and normalizes quotes, then executes a global `directiveRegex` to identify valid directives. For initialization specifically, the engine looks for keywords matching `init` or `initialize`, returning an object containing the `type` and parsed JSON-like `args`.

### Building Safe Configurations

The `detectInit()` function, also located in [`src/utils.ts`](https://github.com/mermaid-js/mermaid/blob/main/src/utils.ts) (lines 66-102), handles the heavy lifting of configuration assembly. It invokes `detectDirective()` with the regex `/(?:init\b)|(?:initialize\b)/` to capture initialization-specific blocks. Before processing arguments, `sanitizeDirective()` sanitizes raw inputs to prevent injection attacks. When multiple directives exist in a single diagram, Mermaid merges them using `assignWithDepth`, allowing layered configuration where later directives override earlier ones.

### Mapping to Diagram-Specific Keys

Mermaid stores diagram-specific options under top-level keys matching the diagram type (`flowchart`, `sequence`, `gantt`, etc.). The `detectInit()` function calls `detectType()` from [`src/diagram-api/detectType.ts`](https://github.com/mermaid-js/mermaid/blob/main/src/diagram-api/detectType.ts) (lines 17-34) to infer the diagram type from the remaining text. If the parsed directive contains a `config` property, Mermaid automatically relocates that object to the inferred diagram key (`results[type] = results.config`) and removes the generic `config` field. This ensures that flowchart-specific settings do not leak into sequence diagrams or other chart types.

### Applying Runtime Settings

The resulting plain JavaScript object is passed to `mermaid.initialize()` in [`src/mermaid.ts`](https://github.com/mermaid-js/mermaid/blob/main/src/mermaid.ts) (lines 440-460). This method stores values in the library’s current configuration object (`currentConfig`), which every diagram renderer references during instantiation. Because this process occurs during parsing, directive-based settings affect only the specific diagram containing the directive, leaving global defaults untouched for subsequent renders.

## Runtime Settings Available Through Directives

All keys defined in `MermaidConfig` (generated from the JSON schema at [`src/config.type.ts`](https://github.com/mermaid-js/mermaid/blob/main/src/config.type.ts), lines 58-200) are potentially available. However, the `secure` configuration array (defaulting to `["theme","themeVariables","themeCSS","logLevel",…]`) restricts which keys directives may actually override.

**Theme and Appearance**
- `theme`, `themeVariables`, `themeCSS`: Select built-in themes (`dark`, `neutral`, `forest`) or supply custom CSS and variable overrides.
- `fontFamily`, `fontSize`, `htmlLabels`, `darkMode`: Control font rendering and label processing globally.

**Logging and Behavior**
- `logLevel`: Controls console verbosity (0 for fatal errors up to 5 for debug traces).
- `startOnLoad`: Determines whether diagrams render automatically when the page loads.
- `deterministicIds`, `deterministicIDSeed`: Configure reproducible SVG ID generation for testing.

**Diagram-Specific Configuration**
- `flowchart`, `sequence`, `gantt`, `pie`, `xyChart`, `quadrantChart`, `gitGraph`, `timeline`: Each diagram type accepts its own sub-object of specialized options. The `detectInit()` function automatically routes generic `config` properties to the appropriate diagram key.

**Layout Engines**
- `layout`: Choose between default layout or `elk` for the Eclipse Layout Kernel.
- `elk`: Contains extensive sub-options like `nodePlacementStrategy` when using the ELK engine.

**Security Constraints**
- `secure`: An array of allowed configuration keys that directives may modify. Any key not listed here is ignored unless explicitly added to the array.
- `securityLevel`: Restricts rendering capabilities (e.g., disabling HTML tags).

## Practical Configuration Examples

### Simple Theme and Log Level

```mermaid
%%{init: { "theme": "forest", "logLevel": 2 }}%%
graph TD
    A --> B

```

This directive applies the forest theme and sets logging to info level (2) for this diagram only.

### Diagram-Specific Flowchart Settings

```mermaid
%%{init: { "config": { "flowchart": { "htmlLabels": true, "curve": "basis" } } }}%%
flowchart LR
    A[Start] --> B{Decision}
    B -->|Yes| C[Result]
    B -->|No| D[End]

```

The generic `config` object is automatically relocated under the `flowchart` key, so only flowchart diagrams receive these specific curve and label settings.

### Custom Theme Variables

```mermaid
%%{init: { "theme": "base", "themeVariables": { "primaryColor": "#ff6600", "fontSize": 20 } }}%%
graph LR
    X --> Y

```

This merges custom CSS variables with the base theme, overriding primary colors and font sizes without creating a complete custom theme file.

### ELK Layout Configuration

```mermaid
%%{init: { "layout": "elk", "elk": { "nodePlacementStrategy": "NETWORK_SIMPLEX" } }}%%
flowchart TD
    A --> B
    B --> C
    C --> D

```

This switches the rendering engine to ELK and applies a specific node-placement algorithm for complex hierarchical layouts.

## Summary

- Mermaid directives use the `%%{initialize: {...}}%%` syntax (or `init` shorthand) to embed JSON configuration directly in diagram source code.
- The `detectDirective()` and `detectInit()` functions in [`src/utils.ts`](https://github.com/mermaid-js/mermaid/blob/main/src/utils.ts) parse and sanitize these blocks, while `detectType()` in [`src/diagram-api/detectType.ts`](https://github.com/mermaid-js/mermaid/blob/main/src/diagram-api/detectType.ts) routes diagram-specific settings to the correct configuration key.
- The `secure` array restricts which configuration keys directives may override, preventing unauthorized changes to security-sensitive settings.
- All runtime settings from `MermaidConfig` in [`src/config.type.ts`](https://github.com/mermaid-js/mermaid/blob/main/src/config.type.ts) are available, including themes, logging levels, layout engines, and diagram-type-specific options.
- Settings are applied through `mermaid.initialize()` in [`src/mermaid.ts`](https://github.com/mermaid-js/mermaid/blob/main/src/mermaid.ts), affecting only the diagram containing the directive while leaving global defaults intact.

## Frequently Asked Questions

### What is the difference between `init` and `initialize` in Mermaid directives?

There is no functional difference between `%%{init: {...}}%%` and `%%{initialize: {...}}%%`. The `detectInit()` function in [`src/utils.ts`](https://github.com/mermaid-js/mermaid/blob/main/src/utils.ts) uses the regex `/(?:init\b)|(?:initialize\b)/` to recognize both keywords interchangeably, treating them as identical directives for configuration injection.

### Can I use multiple initialization directives in a single diagram?

Yes, you can include multiple `%%{init: ...}%%` blocks in one diagram. The `detectInit()` function merges them using `assignWithDepth`, where later directives override earlier ones. This allows you to separate concerns—for example, setting the theme in one directive and diagram-specific options in another.

### Why are some of my configuration settings being ignored?

Mermaid ignores directive settings for keys not listed in the `secure` configuration array. By default, this array only includes safe keys like `theme`, `themeVariables`, `themeCSS`, and `logLevel`. To enable additional configuration keys, you must explicitly add them to the `secure` array in your global Mermaid configuration before the directive is processed.

### How do I configure settings for a specific diagram type only?

Place your settings inside a `config` object within the directive. The `detectInit()` function automatically detects the diagram type using `detectType()` and moves the `config` object to the appropriate key (e.g., `flowchart` or `sequence`). For example, `%%{init: {"config": {"flowchart": {"curve": "basis"}}}%%` applies only to flowcharts, while sequence diagrams in the same document remain unaffected.