How to Use Mermaid Diagram Frontmatter for Per-Diagram Configuration Overrides

Mermaid diagram frontmatter lets you override global configuration settings for individual diagrams by adding a YAML block between triple dashes (---) at the top of your diagram source.

The mermaid-js/mermaid repository supports embedding YAML frontmatter directly into diagram definitions to customize themes, layout parameters, and styling without affecting the global mermaid.initialize() configuration. This feature, implemented in src/diagrams/frontMatter.ts, parses per-diagram overrides before rendering begins.

How Mermaid Diagram Frontmatter Works

When Mermaid processes a diagram, it executes a four-stage pipeline to detect and apply frontmatter configuration:

1. Detection – If the first non-blank line is ---, the parser reads subsequent lines until it encounters the closing ---.
2. Parsing – The enclosed content is parsed as YAML and converted to a JavaScript object.
3. Merging – The resulting object is shallow-merged with the global configuration defined in src/config/defaultConfig.ts. Frontmatter keys take precedence over global settings.
4. Scope – Overrides apply only to the current diagram instance. They do not persist to subsequent diagrams or modify the global Mermaid configuration object.

This process occurs early in the rendering pipeline within src/diagrams/diagramAPI.ts, before the specific diagram type (flowchart, sequence, gantt) is instantiated.

Syntax and Structure

Mermaid diagram frontmatter follows standard YAML syntax enclosed by triple-dash delimiters.

Basic YAML Structure

Place the opening --- on the first line of your diagram, followed by YAML key-value pairs, then close with another ---:

---
theme: forest
---
graph TD
    A --> B

Configuration Precedence

The frontmatter object performs a shallow merge with the global configuration. This means nested objects in frontmatter replace entire nested objects in the global config rather than deep-merging individual properties.

Practical Examples of Mermaid Frontmatter Configuration

Override the Default Theme

Change the visual theme for a single diagram without affecting others:

---
theme: forest
---
graph TD
    A[Start] --> B[Process]
    B --> C[End]

Result: This diagram renders with the forest theme regardless of the site-wide default.

Configure Flowchart Curve and Spacing

Adjust diagram-type-specific options using nested YAML structures:

---
flowchart:
  curve: step
  nodeSpacing: 80
---
flowchart LR
    X --> Y
    Y --> Z

Result: The flowchart uses a step curve algorithm and 80-pixel node spacing exclusively for this diagram.

Customize Theme Variables and CSS Classes

Define custom colors and default class styling:

---
config:
  themeVariables:
    primaryColor: "#ff8800"
  class:
    default:
      fill: "#f0f0f0"
---
classDef myClass fill:#f9f,stroke:#333,stroke-width:2px;
class A myClass;
graph LR
    A[Start] --> B[Process]

Result: The orange primary color and light gray default fill apply only within this diagram instance.

Adjust Sequence Diagram Actor Spacing

Modify sequence diagram layout parameters:

---
sequence:
  actorMargin: 100
---
sequenceDiagram
    participant Alice
    participant Bob
    Alice->>Bob: Hello

Result: Alice and Bob render with 100 pixels of margin between them, while other sequence diagrams retain default spacing.

Technical Implementation Details

The frontmatter feature is implemented across three core files in the mermaid-js/mermaid repository:

• src/diagrams/frontMatter.ts – Contains the parser logic that extracts the YAML block and converts it to a configuration object.
• src/config/defaultConfig.ts – Defines the default configuration schema that frontmatter overrides are merged against.
• src/diagrams/diagramAPI.ts – Orchestrates the rendering process, invoking the frontmatter processor before diagram instantiation.

Because parsing occurs before diagram type detection, you can override any configuration key—including those specific to particular diagram types like flowchart.curve or sequence.actorMargin—without calling mermaid.initialize() in your host application.

Summary

• Mermaid diagram frontmatter enables per-diagram configuration using YAML between triple-dash delimiters at the start of your diagram.
• The parser in src/diagrams/frontMatter.ts shallow-merges frontmatter values with global config, giving precedence to frontmatter keys.
• Configuration overrides are scoped to individual diagrams and do not affect global settings or subsequent renders.
• You can override themes, diagram-type-specific options, theme variables, and CSS classes without modifying your page's JavaScript initialization code.

Frequently Asked Questions

Can I use frontmatter in all Mermaid diagram types?

Yes. The frontmatter parser in src/diagrams/frontMatter.ts processes the YAML block before the diagram type is determined, making the feature available for flowcharts, sequence diagrams, Gantt charts, and all other supported diagram types.

Does frontmatter override mermaid.initialize() settings?

Yes. Values specified in the frontmatter YAML take precedence over global settings defined via mermaid.initialize(). However, the merge is shallow, meaning nested configuration objects in frontmatter replace entire default objects rather than merging individual properties deeply.

What YAML syntax is supported in Mermaid frontmatter?

Mermaid supports standard YAML 1.2 syntax including key-value pairs, nested objects (using indentation), and arrays. The parser extracts everything between the opening and closing --- delimiters and converts it to a JavaScript configuration object.

Can frontmatter define custom CSS classes for a single diagram?

Yes. You can define themeVariables and default class properties within the config section of your frontmatter block. These style definitions apply only to the current diagram, allowing you to customize colors, fills, and strokes without affecting the global stylesheet.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}