Skip to main content
Mermaid provides multiple ways to configure diagrams, from site-wide settings to diagram-specific customization. Understanding the configuration hierarchy helps you control how your diagrams render.

​
Configuration hierarchy

When Mermaid renders a diagram, configuration is applied in the following order:
  1. Default configuration - Built-in defaults for all options
  2. Site configuration - Set via mermaid.initialize() and applied to all diagrams
  3. Frontmatter - Diagram-level configuration in YAML format (v10.5.0+)
  4. Directives - Deprecated diagram-level configuration
The final render configuration is the result of merging these sources, with later sources overriding earlier ones.

​
Site configuration with initialize

The initialize() method sets site-wide configuration that applies to all diagrams. This should be called once when your application loads. 
import mermaid from 'mermaid';

mermaid.initialize({
  startOnLoad: true,
  theme: 'forest',
  logLevel: 'error',
  securityLevel: 'loose',
  flowchart: {
    useMaxWidth: true,
    htmlLabels: true,
    curve: 'basis'
  }
});
The initialize() call is applied only once. Subsequent calls will not override the initial configuration.

​
Frontmatter configuration

Frontmatter allows diagram authors to override configuration for individual diagrams. The frontmatter is a YAML block at the top of the diagram. The config key can contain any configuration option except secure options (like securityLevel).

​
Available frontmatter options

  • title - Set an accessible title for the diagram
  • config - Override any non-secure configuration options
  • theme - Change the theme (default, base, dark, forest, neutral)
  • themeVariables - Customize theme colors and styles

​
Common configuration options

​
Top-level options

These options apply to all diagram types:
OptionTypeDefaultDescription
themestring'default'Visual theme (default, base, dark, forest, neutral)
fontFamilystring'"trebuchet ms", verdana, arial, sans-serif'Font family for all text
logLevelnumber5Logging level (1=debug, 5=fatal)
securityLevelstring'strict'Security level (strict, loose, antiscript, sandbox)
startOnLoadbooleantrueAutomatically render diagrams on page load
htmlLabelsbooleantrueEnable HTML in labels
maxTextSizenumber50000Maximum text size for diagrams
maxEdgesnumber500Maximum number of edges in a diagram

​
Diagram-specific options

Each diagram type has its own configuration namespace: 
flowchart: {
  curve: 'basis',          // Curve style (basis, linear, cardinal)
  diagramPadding: 8,       // Padding around diagram
  useMaxWidth: true,       // Fit to container width
  defaultRenderer: 'elk'   // Layout engine (dagre, elk)
}

​
Resetting configuration

The reset() method resets the current configuration back to the site configuration: 
import { configApi } from 'mermaid';

// Reset to site config
configApi.reset();

// Reset to default config
configApi.reset(configApi.defaultConfig);

​
Security considerations

Certain configuration options cannot be overridden by diagram authors for security reasons. These secure options include:
  • securityLevel
  • secure (the list of secure keys itself)
  • Any keys listed in siteConfig.secure
Attempts to modify secure keys via frontmatter or directives will be ignored and logged as warnings.

​
Configuration flow

​
Best practices

  • Use initialize for site-wide settings - Set common options once instead of repeating them
  • Use frontmatter for diagram-specific changes - Override only what’s needed per diagram
  • Avoid directive syntax - Directives are deprecated; use frontmatter instead
  • Store config in variables - Avoid calling getConfig() repeatedly
  • Validate your configuration - Invalid options will be silently ignored

​
Next steps

Directives

Learn about the deprecated directive syntax

Accessibility

Configure accessibility features

Build docs developers (and LLMs) love

Get started for freeTalk to us