Skip to content

Enable Mermaid

Mermaid is a powerful tool for creating diagrams and visualizations in Markdown. With MkDocs Material, integrating Mermaid diagrams is straightforward and enhances your documentation. This guide will walk you through the steps to enable and use Mermaid diagrams in your MkDocs Material site.

Prerequisites

Ensure you have MkDocs Material and the necessary plugins installed:

pip install mkdocs-material mkdocs-mermaid2-plugin pymdown-extensions

Configuration

Update your mkdocs.yml file with the following configuration to enable Mermaid diagrams.

Theme and Features

Define the theme and features for your site:

site_name: "OVI-GC Knowledge Base"
theme:
  name: material
  features:
    - navigation.instant
    - navigation.instant.prefetch
    - navigation.tabs
    - navigation.sections
    - toc.integrate
    - navigation.top
    - search.suggest
    - search.highlight
    - content.tabs.link
    - content.code.annotation
    - content.code.copy
  palette:
    primary: deep-orange  # Deeper Orange
    accent: deep-purple   # Medium to Dark Purple

Markdown Extensions

Enable the necessary Markdown extensions, including pymdownx.superfences for custom fences:

markdown_extensions:
  - admonition
  - codehilite
  - footnotes
  - meta
  - toc
  - pymdownx.superfences:
      custom_fences:
        - name: mermaid
          class: mermaid
          format: !!python/name:pymdownx.superfences.fence_code_format

Plugins

Add the search and mermaid2 plugins:

plugins:
  - search
  - mermaid2:
      arguments:
        config: '{"theme":"forest"}'
        javascript: 'https://unpkg.com/mermaid@10.4.0/dist/mermaid.min.js'

Extra JavaScript

Include the initialization script for Mermaid:

extra_javascript:
  - js/mermaid-init.js

Initialization Script

Create a directory named js within your docs directory and add a file named mermaid-init.js with the following content:

document.addEventListener('DOMContentLoaded', function () {
    if (typeof mermaid !== 'undefined') {
        mermaid.initialize({ startOnLoad: true });
    }
});

Ensure your directory structure looks like this:

project-root/
├── docs/
│   ├── js/
│   │   └── mermaid-init.js
│   ├── index.md
│   └── ... (other markdown files)
├── mkdocs.yml
└── ... (other project files)

Example Usage

You can now use Mermaid diagrams in your Markdown files. Here’s an example:

# Example Mermaid Diagram

```mermaid
graph TD;
    A-->B;
    A-->C;
    B-->D;
    C-->D;

## Serving the Site

Run the following command to serve your MkDocs site locally:

```bash
python -m mkdocs serve

Here is an example of a working diagram:

graph TD;
    A-->B;
    A-->C;
    B-->D;
    C-->D;

Open your browser and navigate to http://127.0.0.1:8000/ to see your Mermaid diagrams in action.