Mermaid Diagram Widget


Activate a GitPitch Paid Plan to unlock UML Diagram Widget support.

This guide describes the @mermaid widget. This widget is a simple markdown syntax that can be used to render Mermaid Diagrams and Flowcharts on any slide.

MERMAID

Mermaid Widget Usage Conventions

Each diagram is defined using a simple text-based syntax within a dedicated description file. The exact syntax is defined by the Mermaid Project .

The following conventions for GitPitch Mermaid diagrams are in use:

  1. Mermaid diagram descriptions must be defined in a file within your local repository.
  2. These Mermaid diagram description files must have a .mmd extension.
  3. Diagram descriptions must adhere to valid Mermaid syntax.

If you follow these conventions you can then use the following @mermaid syntax to render a diagram on any slide:


@mermaid[props, style...](path/to/diagram.mmd)

The props value accepts a comma-separated list of valid image manipulation properties . The CSS style… list can be used to activate custom styles or build-in styles on the rendered image.

Mermaid Diagrams Built-In Themes

Mermaid supports the following set of built-in themes for native diagrams:

  • default
  • dark
  • forest
  • neutral

These themes can be activated on your diagram using the theme property on the @mermaid widget. The following markdown snippet demontrates the use of each of these theme values on a sample flowchart:

@snap[north-west span-50 text-center]
@mermaid[height=290, theme=default](src/mermaid/flow.mmd)
@snapend

@snap[north-east span-50 text-center]
@mermaid[height=290, theme=forest](src/mermaid/flow.mmd)
@snapend

@snap[south-east span-50 text-center]
@mermaid[height=290, theme=dark](src/mermaid/flow.mmd)
@snapend

@snap[south-west span-50 text-center]
@mermaid[height=290, theme=neutral](src/mermaid/flow.mmd)
@snapend

Results in the rendering of the following slide:

MERMAID DIAGRAM THEMES

Mermaid Diagrams Image Manipulations

The full set of GitPitch supported inline image manipulation properties can be activated on your Mermaid diagrams. For example, the following markdown snippet:

@mermaid[width=900, rotate=-25](src/mermaid/journey.mmd)

Results in the rendering of the following slide:

MERMAID DIAGRAM IMAGE MANIPULATIONS

These manipulations include image sizing, opacity controls, filters, transformations, behaviors, and more. For details see the Inline Image Manipulations Guide .

Mermaid Diagrams Background Colors

A custom background color can be activated for any Mermaid diagram using the bg property on the @mermaid widget. The following markdown snippet demontrates the use of custom backgrounds on a sample sequence diagram::

@snap[north-west span-55 text-center]
@mermaid[bg=transparent](src/mermaid/sequence.mmd)
@snapend

@snap[south-east span-55 text-center]
@mermaid[bg=#77DD77](src/mermaid/sequence.mmd)
@snapend

Results in the rendering of the following slide:

MERMAID DIAGRAM BACKGROUND COLORS

The bg property can take any value that is valid on the background-color css property . By default, Mermaid diagrams are rendered using a transparent background.

Mermaid Diagrams Layout Orientation

You can control the layout orientation of any Mermaid diagram by specifying one of the following orientation flags on the opening graph declaration in your diagram description file.

  • TB - top to bottom
  • BT - bottom to top
  • LR - left to right
  • RL - right to left
  • TD - same as TB

For example, the following snippet demonstrates a Mermaid graph with a top-to-bottom layout orientation:

graph TB
    Start --> Stop

The following screenshot demonstrates a Mermaid graph being rendered using different layout orientations on a sample GitPitch slide:

MERMAID DIAGRAM DIRECTION CONTROLS

Given the aspect ratio of GitPitch slides is 16:9 there are times when activating an LR or RL layout for your diagrams makes sense. Doing so lets you to take advantage of the full width of your slides.

Learn By Example - Flowchart

This Mermaid flowchart diagram syntax:

graph TB
    c1-->a2
    subgraph one
    a1-->a2
    end
    subgraph two
    b1-->b2
    end
    subgraph three
    c1-->c2
    end

Used by the following PITCHME.md markdown snippet:

@mermaid[width=800](src/mermaid/flowchart.mmd)

Results in the rendering of the following slide:

MERMAID FLOWCHART

Learn By Example - Flowchart Styling

This Mermaid flowchart with styling diagram syntax:

graph TB
    sq[Square shape] --> ci((Circle shape))

    subgraph A
        od>Odd shape]-- Two line<br/>edge comment --> ro
        di{Diamond with <br/> line break} -.-> ro(Rounded<br>square<br>shape)
        di==>ro2(Rounded square shape)
    end

    %% Notice that no text in shape are added here instead that is appended further down
    e --> od3>Really long text with linebreak<br>in an Odd shape]

    %% Comments after double percent signs
    e((Inner / circle<br>and some odd <br>special characters)) --> f(,.?!+-*ز)

    cyr[Cyrillic]-->cyr2((Circle shape Начало));

     classDef green fill:#9f6,stroke:#333,stroke-width:2px;
     classDef orange fill:#f96,stroke:#333,stroke-width:4px;
     class sq,e green
     class di orange

Used by the following PITCHME.md markdown snippet:

@mermaid[](src/mermaid/flowchart-styling.mmd)

Results in the rendering of the following slide:

MERMAID FLOWCHART STYLING

Learn By Example - Sequence Diagram

This Mermaid sequence diagram syntax:

sequenceDiagram
    Alice ->> Bob: Hello Bob, how are you?
    Bob-->>John: How about you John?
    Bob--x Alice: I am good thanks!
    Bob-x John: I am good thanks!
    Note right of John: Bob thinks a long<br/>long time, so long<br/>that the text does<br/>not fit on a row.

    Bob-->Alice: Checking with John...
    Alice->John: Yes... John, how are you?

Used by the following PITCHME.md markdown snippet:

@mermaid[](src/mermaid/sequence.mmd)

Results in the rendering of the following slide:

MERMAID SEQUENCE DIAGRAM

More Examples in the Mermaid Docs

Mermaid supports a wide range of flowchart and diagram types. You can learn further details and see numerous examples of each diagram type in the official Mermaid guides: