Skip to main content

Mermaid JS Integration

Docusaurus provides a built-in theme for Mermaid.js, allowing you to create diagrams and visualizations directly in your documentation using text.

1. Installation​

To enable Mermaid support, you must install the official theme package. Since we are using Docker, we run this command inside the container:

sudo docker exec docusaurus npm install @docusaurus/theme-mermaid

2. Configuration​

After installing the package, update your docusaurus.config.js to enable the plugin and configured theme.

Step 1: Enable Mermaid Markdown​

Add the markdown object to your configuration:

docusaurus.config.js
module.exports = {
  // ... other configs
  markdown: {
    mermaid: true, // Enables mermaid parsing
  },
  // ...
};

Step 2: Add the Mermaid Theme​

Add the theme to the themes array:

docusaurus.config.js
module.exports = {
  // ...
  themes: ['@docusaurus/theme-mermaid'],
  // ...
};

3. Usage​

You can now create diagrams using the mermaid code block identifier.

Basic Flowchart Example​

```mermaid
graph TD;
    A[Start] --> B{Is it working?};
    B -- Yes --> C[Celebrate];
    B -- No --> D[Debug];
    D --> B;
```

Result​

4. Troubleshooting​

502 Bad Gateway after Restart​

If you receive a 502 error after restarting Docusaurus to apply these changes:

  1. Wait for Build: Mermaid increases build time. Check logs: 
    sudo docker logs -f docusaurus
  2. Stale DNS Cache: If Docusaurus is healthy but the site is still 502, restart the Cloudflare Tunnel to refresh the connection: 
    sudo docker restart cloudflared

Mermaid not rendering​

Ensure you have both markdown: { mermaid: true } and themes: ['@docusaurus/theme-mermaid'] in your config. One without the other will cause rendering issues or build failures.