Mermaid Integration

Mermaid is a tool that lets you generate flow charts, sequence diagrams, gantt charts, class diagrams and vcs graphs from a simple markup language. This allows charts and diagrams to be embedded and edited directly in the documentation source files rather than creating them as images using some external tool and checking the images into the tree.

To add a diagram, simply put something like this into your page:

.. mermaid::

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

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

The result will be:

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

Or

.rst

.. mermaid::

     sequenceDiagram
         participant Alice
         participant Bob
         Alice->>John: Hello John, how are you?
         loop Healthcheck
             John->>John: Fight against hypochondria
         end
         Note right of John: Rational thoughts <br/>prevail!
         John-->>Alice: Great!
         John->>Bob: How about you?
         Bob-->>John: Jolly good!

.md

```{mermaid}
sequenceDiagram
    participant Alice
    participant Bob
    Alice->>John: Hello John, how are you?
    loop Healthcheck
        John->>John: Fight against hypochondria
    end
    Note right of John: Rational thoughts <br/>prevail!
    John-->>Alice: Great!
    John->>Bob: How about you?
    Bob-->>John: Jolly good!
```

will show:

        sequenceDiagram
    participant Alice
    participant Bob
    Alice->>John: Hello John, how are you?
    loop Healthcheck
        John->>John: Fight against hypochondria
    end
    Note right of John: Rational thoughts <br/>prevail!
    John-->>Alice: Great!
    John->>Bob: How about you?
    Bob-->>John: Jolly good!
    

Colors

A diagram follows the page’s color scheme. A node you do not style takes the theme’s default fill, pale in light mode and near-black in dark mode, so prose cannot identify a node by that color.

A node you style with an explicit fill: keeps that color in both schemes. Give it an explicit color: too, or its label takes the theme’s own label color and comes out grey on a light fill in dark mode:

classDef offstrip fill:#fef3c7,stroke:#92400e,color:#1a1a1a;

Do not let color be the only thing that identifies a node in prose. Pair it with the shape or the label, since color alone does not reach a reader who cannot tell the colors apart.

See Mermaid’s official docs for more details on the syntax, and use the Mermaid Live Editor to experiment with creating your own diagrams.