Skip to main content
Version: Canary 🚧

Diagrams

Diagrams can be rendered using Mermaid in a code block.

Installation​

npm install --save @docusaurus/theme-mermaid

Enable Mermaid functionality by adding plugin @docusaurus/theme-mermaid and setting markdown.mermaid to true in your docusaurus.config.js.

docusaurus.config.js
export default {
  markdown: {
    mermaid: true,
  },
  themes: ['@docusaurus/theme-mermaid'],
};

Usage​

Add a code block with language mermaid:

Example Mermaid diagram
```mermaid
graph TD;
    A-->B;
    A-->C;
    B-->D;
    C-->D;
```

See the Mermaid syntax documentation for more information on the Mermaid syntax.

Theming​

The diagram dark and light themes can be changed by setting mermaid.theme values in the themeConfig in your docusaurus.config.js. You can set themes for both light and dark mode.

docusaurus.config.js
export default {
  themeConfig: {
    mermaid: {
      theme: {light: 'neutral', dark: 'forest'},
    },
  },
};

See the Mermaid theme documentation for more information on theming Mermaid diagrams.

Styling tooltips​

Mermaid charts support Interactions, which allow you to add hyperlinks to your diagrams. These hyperlinks can include tooltips that appear when hovering over elements in the diagram. Tooltips do not appear by default, but you can enable them by adding a custom .mermaidTooltip CSS class to your site's stylesheet (customize as you see fit).

src/css/custom.css
.mermaidTooltip {
  position: absolute;
  text-align: center;
  max-width: 200px;
  padding: 2px;
  background: var(--ifm-background-color);
  border: 1px solid var(--ifm-color-primary);
  border-radius: 2px;
  pointer-events: none;
  z-index: 100;
}

When a .mermaidTooltip class is defined, tooltips will appear on hover over any diagram elements that include a click directive. For example,

Example Mermaid diagram with clickable elements and tooltips
```mermaid
flowchart TB
    GH[Docusaurus GitHub]
    MI[Mermaid.js Installation]
    SWIZZ[Swizzling Article]
    TTO[Tooltip Only]

    click GH "https://www.github.com/facebook/docusaurus" "Git repo for the Docusaurus project"
    click MI "#installation" "Link to the installation section of this doc"
    click SWIZZ "../swizzling" "Link to the swizzling article"
    click TTO void "This is a tooltip only element and does not link anywhere"
```

Will yield clickable elements with tooltips:

Mermaid Config​

Options in mermaid.options will be passed directly to mermaid.initialize:

docusaurus.config.js
export default {
  themeConfig: {
    mermaid: {
      options: {
        maxTextSize: 50,
      },
    },
  },
};

See the Mermaid config documentation and the Mermaid config types for the available config options.

Dynamic Mermaid Component​

To generate dynamic diagrams, you can use the Mermaid component:

Example of dynamic Mermaid component
import Mermaid from '@theme/Mermaid';

<Mermaid
  value={`graph TD;
    A-->B;
    A-->C;
    B-->D;
    C-->D;`}
/>

Layouts​

Mermaid supports different layout engines:

  • The dagre layout engine is supported by default in Docusaurus.
  • The elk layout engine is heavier and can be enabled by installing the optional @mermaid-js/layout-elk dependency.
```mermaid
---
config:
  layout: elk
---
graph TD;
    A-->B;
    A-->C;
    B-->D;
    C-->D;
```