astro-mermaid

An Astro integration for rendering Mermaid diagrams with automatic theme switching, client-side rendering, and universal compatibility. Works seamlessly with both standalone Astro projects and documentation frameworks like Starlight.

Both demos showcase:

• ✅ All diagram types with live examples
• ✅ Theme switching (light/dark modes)
• ✅ Icon pack integration
• ✅ Responsive design
• ✅ Content collections and direct .astro usage

• 🎨 Universal Theme Detection - Works with both html[data-theme] and body[data-theme] attributes
• 🚀 Dual Plugin System - Remark + Rehype plugins for comprehensive markdown processing
• 📝 Universal File Support - Works with .md, .mdx, and .astro files
• ⚡ Performance Optimized - Conditional loading and client-side rendering
• 🔧 Highly Configurable - Full mermaid.js configuration support
• 🎯 TypeScript Ready - Complete type definitions included
• 🔒 Privacy-Focused - No external dependencies, fully offline-capable
• 📦 Zero Configuration - Works out of the box with sensible defaults
• 🎭 Smooth UX - Loading animations and layout shift prevention
• 🦌 ELK Support - Optionally works with the elk layout (The Eclipse Layout Kernel)

npm install astro-mermaid mermaid

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

export default defineConfig({
  integrations: [
    mermaid({
      theme: 'forest',
      autoTheme: true
    })
  ]
});

```mermaid
graph TD
    A[Start] --> B[Process]
    B --> C[End]
```

To enable the elk layout in Mermaid diagrams, install the @mermaid-js/layout-elk package.

npm install @mermaid-js/layout-elk

Learn more about Mermaid layouts or The Eclipse Layout Kernel.

astro-mermaid works across Astro 4, 5, 6, and 7 — no configuration needed. It detects the active markdown engine at build time and registers its transform the right way for each:

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

When using with Starlight or other markdown-processing integrations, place mermaid first:

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

export default defineConfig({
  integrations: [
    mermaid(), // ⚠️ Must come BEFORE starlight
    starlight({
      title: 'My Docs'
    })
  ]
});

mermaid({
  // Default theme: 'default', 'dark', 'forest', 'neutral', 'base'
  theme: 'forest',

  // Enable automatic theme switching based on data-theme attribute
  autoTheme: true,

  // Enable client-side logging (default: true). Set to false to suppress
  // console.log output in the browser. Errors are always logged.
  enableLog: false,

  // Additional mermaid configuration
  mermaidConfig: {
    flowchart: {
      curve: 'basis'
    }
  },

  // Register icon packs for use in diagrams
  iconPacks: [
    {
      name: 'logos',
      loader: () => fetch('https://unpkg.com/@iconify-json/logos@1/icons.json').then(res => res.json())
    },
    {
      name: 'iconoir',
      loader: () => fetch('https://unpkg.com/@iconify-json/iconoir@1/icons.json').then(res => res.json())
    }
  ]
})

You can register icon packs to use custom icons in your diagrams. There are three ways to provide a pack:

iconPacks: [
  // 1. url — preferred: a JSON endpoint, fetched safely at runtime
  {
    name: 'logos',
    url: 'https://unpkg.com/@iconify-json/logos@1/icons.json'
  },

  // 2. icons — pass icon data directly (e.g. an imported JSON file).
  //    No serialization concerns, so this works with imports and shared data.
  {
    name: 'my-icons',
    icons: myIcons // import myIcons from './my-icons.json'
  },

  // 3. loader — legacy. The function source is inspected for a fetch('...')
  //    URL. Prefer `url` or `icons` instead.
  {
    name: 'iconoir',
    loader: () => fetch('https://unpkg.com/@iconify-json/iconoir@1/icons.json').then(res => res.json())
  }
]

The integration never serializes arbitrary function bodies to the client. A loader is only used to extract its fetch(...) URL; if no URL can be found, the pack is skipped with a warning. Use url or icons for reliable results.

Then use icons in your diagrams:

```mermaid
architecture-beta
  group api(logos:aws-lambda)[API]

  service db(logos:postgresql)[Database] in api
  service disk1(logos:aws-s3)[Storage] in api
  service disk2(logos:cloudflare)[CDN] in api
  service server(logos:docker)[Server] in api

  db:L -- R:server
  disk1:T -- B:server
  disk2:T -- B:db
```

If autoTheme is enabled (default), the integration will automatically switch between themes based on your site's data-theme attribute:

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

This integration uses 100% client-side rendering with zero external dependencies at runtime:

• No Data Transmission: Your diagram content never leaves your browser
• No External Servers: No calls to mermaid.live or any external services
• Offline Capable: Works completely offline after initial page load
• Zero Network Latency: Instant diagram rendering without network delays
• Corporate Firewall Friendly: No external domains need to be whitelisted

1. Build Time: Mermaid code blocks are transformed to <pre class="mermaid"> elements
2. Runtime: The bundled Mermaid JavaScript library renders diagrams locally
3. Output: Pure SVG generated entirely in your browser

// All rendering happens locally - no network calls
import mermaid from 'mermaid';
const { svg } = await mermaid.render(id, diagramDefinition);

Perfect for:

• Corporate environments with strict security policies
• GDPR/privacy-compliant applications
• Air-gapped or restricted network environments
• Applications requiring data sovereignty
• High-security environments where external requests are prohibited

All mermaid diagram types are supported:

• Flowcharts
• Sequence diagrams
• Gantt charts
• Class diagrams
• State diagrams
• Entity Relationship diagrams
• User Journey diagrams
• Git graphs
• Pie charts
• Requirement diagrams
• C4 diagrams
• Mindmaps
• Timeline diagrams
• Quadrant charts
• And more!

See changelog for version history.

Contributions welcome! See our demos for examples.

MIT © Jose Sebastian