npm package: @opencenter-cloud/docusaurus-theme-beautiful-mermaid
Description: Docusaurus v3.9 theme that replaces @docusaurus/theme-mermaid with build-time SVG rendering via @dev-x/beautiful-mermaid
Latest version: 0.1.0

# `@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

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

or

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

## Configure Docusaurus

```ts
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](../../docs/ga-readiness.md)
- [Support Policy](../../docs/support-policy.md)
- [SVG Security Policy](../../docs/svg-security-policy.md)
- [Release Process](../../docs/release-process.md)
- [Migration Guide](../../docs/migration-guide.md)
- [Supported Syntax](../../docs/supported-syntax.md)
- [Changelog](./CHANGELOG.md)

## License

MIT