@opencenter-cloud/docusaurus-theme-beautiful-mermaid

Build-time Mermaid rendering for Docusaurus.

This package replaces client-side Mermaid execution with build-time SVG generation. Mermaid code fences are transformed by a remark plugin and rendered by the theme as inline SVG, so pages ship pre-rendered diagrams instead of a browser-side Mermaid runtime.

What it provides

• A Docusaurus theme that supplies @theme/Mermaid
• A remark plugin that converts Mermaid fences into inline SVG during the build
• Build-time error policies for unsupported, invalid, or oversized diagrams
• SVG postprocessing before injection into generated output

Requirements

• Node >=20
• Docusaurus peer dependency range ^3.9.2
• React ^18

Install

pnpm add @opencenter-cloud/docusaurus-theme-beautiful-mermaid

or

npm install @opencenter-cloud/docusaurus-theme-beautiful-mermaid

Configure Docusaurus

import type {Config} from '@docusaurus/types';
import {remarkBeautifulMermaid} from '@opencenter-cloud/docusaurus-theme-beautiful-mermaid/remark';

const mermaidRemarkPlugin = [
  remarkBeautifulMermaid,
  {
    colors: {
      bg: 'var(--ifm-background-color)',
      fg: 'var(--ifm-font-color-base)',
      accent: 'var(--ifm-color-primary)',
    },
    render: {
      transparent: true,
      padding: 40,
    },
    build: {
      onError: 'throw',
      sanitizeSvg: true,
      maxSourceLength: 20_000,
    },
  },
] as const;

const config: Config = {
  title: 'My Site',
  url: 'https://example.com',
  baseUrl: '/',
  markdown: {
    mermaid: false,
  },
  themes: ['@opencenter-cloud/docusaurus-theme-beautiful-mermaid'],
  presets: [
    [
      'classic',
      {
        docs: {
          beforeDefaultRemarkPlugins: [mermaidRemarkPlugin],
        },
        blog: {
          beforeDefaultRemarkPlugins: [mermaidRemarkPlugin],
        },
        pages: {
          beforeDefaultRemarkPlugins: [mermaidRemarkPlugin],
        },
      },
    ],
  ],
};

export default config;

Supported options

| Option | Default | Notes | |---|---|---| | colors | Docusaurus CSS variable defaults | Passed to the renderer and preserved in the SVG output | | render | { transparent: true, padding: 40, thoroughness: 3, interactive: false } | Controls layout and render behavior | | build.onError | 'throw' | Also supports 'warn-and-code' and 'warn-and-placeholder' | | build.sanitizeSvg | true | Enables SVG postprocessing before caching and injection | | build.maxSourceLength | 20000 | Rejects pathologically large Mermaid sources before rendering; null disables the guard | | languages | ['mermaid'] | Adds code-fence aliases such as mmd |

Current constraints

• Configuration is remark-plugin driven. themeConfig.beautifulMermaid is not supported.
• Runtime Mermaid fallback is not supported.
• Docusaurus built-in Mermaid processing should be disabled with markdown.mermaid: false.
• Remark-plugin instances are isolated per content pipeline.
• The theme plugin itself is still singleton-shaped and is not modeled as a separate multi-instance configurable plugin.

Security notes

• Mermaid is rendered on Node at build time.
• SVG output is postprocessed before embedding.
• Disallowed SVG elements and attributes are removed.
• External and executable URL forms are stripped.
• Remote CSS imports are removed from the emitted SVG.
• Hostile-source fixture coverage exercises the real renderer-to-output path.

Keep build.sanitizeSvg enabled for untrusted or multi-author content.

Tested support

• CI verifies a locked Docusaurus 3.9.2 lane and a rolling @docusaurus/*@latest v3 lane.
• Fixture coverage includes unversioned docs, versioned docs, and a non-English locale build.

Links

• GA Readiness
• Support Policy
• SVG Security Policy
• Release Process
• Migration Guide
• Supported Syntax
• Changelog

License

MIT