@bdocs/plugin-mermaid

Installation & Quick Start

Get started by adding the plugin package to your documentation project.

1. Install the package

pnpm add @bdocs/plugin-mermaid

2. Register the plugin

Add the plugin to the plugins array in your configuration file:

import { defineConfig } from 'boltdocs'
import mermaidPlugin from '@bdocs/plugin-mermaid'

export default defineConfig({
  plugins: [mermaidPlugin()],
})

Concepts & Architecture

The Mermaid plugin uses a hybrid compilation pipeline to keep your documentation fast:

graph LR
    A[Markdown Source] -->|Remark Transform| B[MDX Component Prep]
    B -->|SSG compilation| C[Light HTML Skeleton]
    C -->|Lazy Client Import| D[Interactive SVG Render]

1. Build-Time Transformation: When Boltdocs parses your markdown files, the plugin's Remark compiler finds code blocks marked as mermaid. It compiles them into standard <Mermaid /> React components and injects the raw diagram text as a prop.
2. Dynamic Client-Side Rendering: To prevent huge JavaScript bundle sizes in your static pages, the Mermaid.js engine is dynamically loaded only when a diagram enters the user's viewport. If a page does not contain diagrams, zero Mermaid code is sent to the client.

API Reference

MermaidPluginOptions

Configuration passed to the mermaidPlugin() initializer.

MermaidThemes

Custom configurations for light and dark visualization modes.

MermaidThemeVariables

Complete list of available color variables to customize the diagram node styling.

Mermaid Component Props

Properties supported when using the <Mermaid /> React component directly in MDX.

Detailed Examples

Custom Theming

You can customize themes by passing variable overrides directly:

import { defineConfig } from 'boltdocs'
import mermaidPlugin from '@bdocs/plugin-mermaid'

export default defineConfig({
  plugins: [
    mermaidPlugin({
      themes: {
        light: {
          primaryColor: '#e0f2fe',
          primaryTextColor: '#0369a1',
          primaryBorderColor: '#bae6fd',
          lineColor: '#0284c7',
        },
        dark: {
          primaryColor: '#0c4a6e',
          primaryTextColor: '#e0f2fe',
          primaryBorderColor: '#0284c7',
          lineColor: '#38bdf8',
        },
      },
    }),
  ],
})

Component Syntax

For advanced layouts, you can invoke the JSX component directly:

<Mermaid chart={`
  flowchart LR
    A[Start] --> B[Process]
    B --> C[End]
`} />

Troubleshooting

Diagrams fail to render

• Verify Configuration: Ensure mermaidPlugin() is registered in your boltdocs.config.ts plugins array.
• Verify Language Identifier: The opening of your markdown code block must be exactly ```mermaid.
• Check Syntax: Check your web browser console for syntax errors raised by the Mermaid compiler (e.g. unclosed parentheses or typos in node connections).

Themes do not sync

The plugin hooks into the site's dark mode provider. If themes are mismatched:

• Ensure your custom layouts consume the useTheme() hook exported by boltdocs/client to stay in sync with the global app settings.

Large diagrams are cut off

By default, Boltdocs surrounds diagrams in a scrollable, responsive container. If you need diagrams to scale to fit the parent container instead, add the following to your custom global CSS stylesheet:

.mermaid-container svg {
  max-width: 100%;
  height: auto;
}