Mermaid
Rendering diagrams in your docs
Setup
Fumadocs doesn't have a built-in Mermaid wrapper provided, we recommend using mermaid directly.
You can decide the Mermaid renderer to configure:
Official Renderer
Install the required dependencies, next-themes is used with Fumadocs to manage the light/dark mode.
npm install mermaid next-themesCreate the Mermaid component:
'use client';
import React , { use, useEffect, useId, useState } from 'react';
import { useTheme } from 'next-themes';
export function Mermaid({ chart }: { chart: string }) {
const [mounted, setMounted] = useState(false);
useEffect(() => {
setMounted(true);
}, []);
if (!mounted) return;
return <MermaidContent chart={chart} />;
}
const cache = new Map<string, Promise<unknown>>();
function cachePromise<T>(key: string, setPromise: () => Promise<T>): Promise<T> {
const cached = cache.get(key);
if (cached) return cached as Promise<T>;
const promise = setPromise();
cache.set(key, promise);
return promise;
}
function MermaidContent({ chart }: { chart: string }) {
const id = useId();
const { resolvedTheme } = useTheme();
const { default: mermaid } = use(cachePromise('mermaid', () => import('mermaid')));
mermaid.initialize({
startOnLoad: false,
securityLevel: 'loose',
fontFamily: 'inherit',
themeCSS: 'margin: 1.5rem auto 0;',
theme: resolvedTheme === 'dark' ? 'dark' : 'default',
});
const { svg, bindFunctions } = use(
cachePromise(`${chart}-${resolvedTheme}`, () => {
return mermaid.render(id, chart.replaceAll('\\n', '\n'));
}),
);
return (
<div
ref={(container) => {
if (container) bindFunctions?.(container);
}}
dangerouslySetInnerHTML={{ __html: svg }}
/>
);
}
Beautiful Mermaid
beautiful-mermaid is a 3rd party Mermaid renderer.
npm install beautiful-mermaidimport { CodeBlock, Pre } from 'fumadocs-ui/components/codeblock';
import { renderMermaidSVG } from 'beautiful-mermaid';
export async function Mermaid({ chart }: { chart: string }) {
try {
const svg = renderMermaidSVG(chart, {
bg: 'var(--color-fd-background)',
fg: 'var(--color-fd-foreground)',
interactive: true,
transparent: true,
});
return <div dangerouslySetInnerHTML={{ __html: svg }} />;
} catch {
return (
<CodeBlock title="Mermaid">
<Pre>{chart}</Pre>
</CodeBlock>
);
}
}Usage
Add the component as a MDX component:
import defaultMdxComponents from 'fumadocs-ui/mdx';
import { Mermaid } from '@/components/mdx/mermaid';
import type { MDXComponents } from 'mdx/types';
export function getMDXComponents(components?: MDXComponents) {
return {
...defaultMdxComponents,
Mermaid,
...components,
} satisfies MDXComponents;
}Then, use it in MDX files.
<Mermaid
chart="
graph TD;
subgraph AA [Consumers]
A[Mobile app];
B[Web app];
C[Node.js client];
end
subgraph BB [Services]
E[REST API];
F[GraphQL API];
G[SOAP API];
end
Z[GraphQL API];
A --> Z;
B --> Z;
C --> Z;
Z --> E;
Z --> F;
Z --> G;"
/>As CodeBlock
You can convert mermaid codeblocks into the MDX usage with the remarkMdxMermaid remark plugin.
import { remarkMdxMermaid } from 'fumadocs-core/mdx-plugins';
import { defineConfig } from 'fumadocs-mdx/config';
export default defineConfig({
mdxOptions: {
remarkPlugins: [remarkMdxMermaid],
},
});```mermaid
graph TD;
A-->B;
A-->C;
```How is this guide?