Configuration

Configuration options for astro-mermaid

Configuration Options

The astro-mermaid integration accepts the following options:

theme

The default Mermaid theme to use.

• Type: 'default' | 'dark' | 'forest' | 'neutral' | 'base'
• Default: 'default'

mermaid({
  theme: 'forest'
})

autoTheme

Enable automatic theme switching based on the data-theme attribute on the document root.

• Type: boolean
• Default: true

When enabled:

• data-theme="light" → uses ‘default’ mermaid theme
• data-theme="dark" → uses ‘dark’ mermaid theme

mermaid({
  autoTheme: false // Disable auto theme switching
})

mermaidConfig

Additional Mermaid configuration options. See the Mermaid configuration documentation for all available options.

• Type: object
• Default: {}

mermaid({
  mermaidConfig: {
    startOnLoad: false,
    flowchart: {
      curve: 'basis',
      padding: 15
    },
    sequence: {
      diagramMarginX: 50,
      diagramMarginY: 10
    },
    gantt: {
      fontSize: 12,
      numberSectionStyles: 4
    }
  }
})

Example Configurations

Minimal Setup

import { defineConfig } from 'astro/config';
import mermaid from 'astro-mermaid';

export default defineConfig({
  integrations: [mermaid()]
});

Dark Theme with Custom Flowchart

import { defineConfig } from 'astro/config';
import mermaid from 'astro-mermaid';

export default defineConfig({
  integrations: [
    mermaid({
      theme: 'dark',
      autoTheme: false,
      mermaidConfig: {
        flowchart: {
          curve: 'linear',
          nodeSpacing: 50,
          rankSpacing: 50
        }
      }
    })
  ]
});

Production Optimized

import { defineConfig } from 'astro/config';
import mermaid from 'astro-mermaid';

export default defineConfig({
  integrations: [
    mermaid({
      theme: 'neutral',
      autoTheme: true,
      mermaidConfig: {
        startOnLoad: false,
        logLevel: 'error',
        securityLevel: 'strict'
      }
    })
  ]
});

Markdown Processor (Astro version support)

astro-mermaid works on Astro 4, 5, 6, and 7 with no extra configuration. It detects which markdown engine Astro is using at build time and registers its transform the right way for each:

You normally don’t set markdown.processor at all — Astro picks a default and mermaid follows it. On Astro 7 the default is Sätteri, the faster engine and the recommended choice. This standalone demo uses that default.

Choosing a processor explicitly

Both processors are fully supported, and diagrams render identically on either:

import { defineConfig } from 'astro/config';
import mermaid from 'astro-mermaid';
import { satteri } from '@astrojs/markdown-satteri';
// import { unified } from '@astrojs/markdown-remark';

export default defineConfig({
  markdown: {
    // Preferred on Astro 7 — the default, faster engine.
    processor: satteri(),
    // Legacy alternative — mermaid works here too:
    // processor: unified(),
  },
  integrations: [
    mermaid({ theme: 'forest', autoTheme: true })
  ]
});

Tip: If you previously pinned markdown.processor: unified() purely to keep mermaid working after upgrading to Astro 7, you can drop that workaround and let Astro use its default Sätteri processor.