Mermaid diagrams¶

Note

This feature provides an alternative to Graphviz for including diagrams.

The mkdocs-material theme is equipped to make use of diagrams generated (during page load time) with mermaid.js. Although, its implementation relies on a markdown extension that does not get used by this sphinx-immaterial theme. Thus, the sphinx-immaterial theme provides an optional directive that exposes the underlying implementation in mkdocs-material theme.

.. md-mermaid::¶

:class: (string)¶

A space delimited list of qualified names that get used as the HTML element’s class attribute.

Hint

You can use this option to specify text-align property via the following CSS classes:

align-right sets the text-align property to right.
align-left sets the text-align property to left.
align-center sets the text-align property to center.

:name: (string)¶

A qualified name that get used as the HTML element’s id attribute.

Use the ref role to reference the element by name.

The md-mermaid directive’s :class: and :name: options can be used as respective class and id specifiers in custom CSS.

This theme comes with CSS styling that conforms to the chosen primary & accent colors (based on the selected scheme).

Failure

While all mermaid.js features should work out-of-the-box, this theme will currently only adjust the fonts and colors for the following types of diagrams:

References linking directly to a diagram’s :name:¶

- `flowcharts`_
- `sequence diagrams <sequence-diagrams>`
- `class diagrams <class-diagrams>`
- `state diagrams <state-diagrams>`
- `entity-relationship diagrams <entity-relationship-diagrams>`

flowcharts
sequence diagrams
class diagrams
state diagrams
entity-relationship diagrams

Using flowcharts¶

.. md-mermaid::
    :name: flowcharts

    graph LR
        A[Start] --> B{Error?};
        B -->|Yes| C[Hmm...];
        C --> D[Debug];
        D --> B;
        B ---->|No| E[Yay!];

graph LR
    A[Start] --> B{Error?};
    B -->|Yes| C[Hmm...];
    C --> D[Debug];
    D --> B;
    B ---->|No| E[Yay!];

Using sequence diagrams¶

.. md-mermaid::
    :name: sequence-diagrams

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

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

Using state diagrams¶

.. md-mermaid::
    :name: state-diagrams

    stateDiagram-v2
        state fork_state <<fork>>
            [*] --> fork_state
            fork_state --> State2
            fork_state --> State3

            state join_state <<join>>
            State2 --> join_state
            State3 --> join_state
            join_state --> State4
            State4 --> [*]

stateDiagram-v2
    state fork_state <<fork>>
        [*] --> fork_state
        fork_state --> State2
        fork_state --> State3

        state join_state <<join>>
        State2 --> join_state
        State3 --> join_state
        join_state --> State4
        State4 --> [*]

Using class diagrams¶

.. md-mermaid::
    :name: class-diagrams

    classDiagram
        Person <|-- Student
        Person <|-- Professor
        Person : +String name
        Person : +String phoneNumber
        Person : +String emailAddress
        Person: +purchaseParkingPass()
        Address "1" <-- "0..1" Person:lives at
        class Student{
            +int studentNumber
            +int averageMark
            +isEligibleToEnrol()
            +getSeminarsTaken()
        }
        class Professor{
            +int salary
        }
        class Address{
            +String street
            +String city
            +String state
            +int postalCode
            +String country
            -validate()
            +outputAsLabel()
        }

classDiagram
    Person <|-- Student
    Person <|-- Professor
    Person : +String name
    Person : +String phoneNumber
    Person : +String emailAddress
    Person: +purchaseParkingPass()
    Address "1" <-- "0..1" Person:lives at
    class Student{
        +int studentNumber
        +int averageMark
        +isEligibleToEnrol()
        +getSeminarsTaken()
    }
    class Professor{
        +int salary
    }
    class Address{
        +String street
        +String city
        +String state
        +int postalCode
        +String country
        -validate()
        +outputAsLabel()
    }

Using entity-relationship diagrams¶

.. md-mermaid::
    :name: entity-relationship-diagrams

    erDiagram
        CUSTOMER ||--o{ ORDER : places
        ORDER ||--|{ LINE-ITEM : contains
        CUSTOMER }|..|{ DELIVERY-ADDRESS : uses

erDiagram
    CUSTOMER ||--o{ ORDER : places
    ORDER ||--|{ LINE-ITEM : contains
    CUSTOMER }|..|{ DELIVERY-ADDRESS : uses

Last update: Dec 16, 2024