What is Mermaid JS?

Although design programs are a primary option for requirements such as flowcharts, sequence diagrams, class diagrams, Gantt charts, and Git graphs, operations can also be performed through various applications and/or programming languages. Thanks to these solutions, the relevant graphs can be output dynamically and/or statically. However, of course, we can benefit from these capabilities within their own dependencies and limitations. Mermaid, developed with the JavaScript language, is one of these options. What sets Mermaid JS apart from others is its ability to be easily adapted to different environments and its Markdown-like (markdownish) syntax that allows us to easily create flowcharts, sequence diagrams, class diagrams, Gantt charts, and Git graphs. Of course, there are other options besides mermaid, such as PlantUML¹ and Kroki².

Mermaid JS

Mermaid-js is an open-source, JavaScript-based diagram and graph tool that allows us to easily create flowcharts, sequence diagrams, class diagrams, Gantt charts, and Git graphs through writing rules similar to markdown syntax³.

Through basic formatting definitions, complex diagrams can be created and modified quickly and dynamically. You can apply and edit the examples below quickly using the Mermaid Live Editor⁴.

Let's proceed by creating an example flowchart.

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

In the example above, the graph indicates that the expressions we specify should be considered in a flowchart format. TD shows how the relevant format should be oriented⁵. A, B, C, and D denote the relevant points, while --> defines the relationship between these points. In summary, the above mermaid definition is interpreted (rendered) and presented to us in SVG format⁶. You can see the output of the above example in Figure 1 (a).

%%{init: { 'theme': 'dark' } }%%
graph LR;
    A[/Lorem/]-.->|X| B(Ipsum);
    A--> C[Dolor];
    B-->D[fa:fa-car Sit Amet];
    C==>|Y| D;

%%{init: {'theme':'base'}}%%
flowchart TB;
    A(Lorem)-.->|X| B(Ipsum);
    A--xC(Dolor);
    B--oD((fa:fa-car Sit Amet));
    C<==>|Y| B & D;
subgraph section
            B
            C
          end

You can see the outputs of the two mermaid definitions above in Figure 1 (b) and Figure 1 (c) respectively. graph can essentially be considered a simpler use of flowchart. flowchart can be preferred in cases where more detailed definitions are required.

It carries parameters such as security definitions for the interpretation process, theme definitions, and log operations. Its most basic use is as follows:

%%{init: { <argümanlar> }}%%

For more comprehensive usage, you can view and update the following example with the Mermaid Live Editor.

graph LR
A[Campaign]
B[LP: lp-1]
C[LP: lp-2]
D[Order Form: bp-1]
E[Order Form: bp-2]
F[Order Form: of-1]
G[Order Form: of-2]
H[Up-sell 1]
I[Up-sell 2]
J[Order Completed]

A --> B & C

subgraph s11 [split testing - 1]
B & C
end

subgraph st2 [split testing - 2]
    B-->|%50|D & E
    C-->|%50|E & D
end

subgraph st3 [split testing - 3]
    D-->|%70|F & G
    E-->|%30|G & F
end

F & G --> H
H --> I
I --> J

It is worth mentioning that we can also make interactions with mermaid diagrams. However, this feature cannot be used in the securityLevel='strict' definition. Therefore, the security definition needs to be edited as securityLevel='loose'⁸.

var callback = function(){
    alert('A callback was triggered');
}

graph LR;
    A-->B;
    B-->C;
    C-->D;
    click A callback "Tooltip for a callback"
    click B "http://www.github.com" "This is a tooltip for a link"
    click A call callback() "Tooltip for a callback"
    click B href "http://www.github.com" "This is a tooltip for a link"

Of course, the formats we can use with Mermaid are not limited to flowchart and graph.

We can create sequence diagrams using sequenceDiagram. sequenceDiagram can also be considered as a simple level Unified Modelling Language (UML) solution that determines and explains how business systems can be modeled⁹.

Dialogues between individuals or requests and responses between services can be given as examples for the sequence flow.

sequenceDiagram
    participant John
    participant Alice
    participant Ela
    Alice->>John: Hello John, how are you?
    Alice->>Ela: Hi
    John-->>Alice: Great!
    Ela ->> John: Hello!

We can enrich the above sequence flow with notes and loops. You can see the code snippet below to visualize the changes in the diagram using the Mermaid Live Editor ⁴.

sequenceDiagram
    participant John
    participant Alice
    participant Ela
    Alice->>John: Hello John, how are you?
    Note right of John: Text in note
    Alice->>Ela: Hi
    John-->>Ela: Fine!
    loop Every minute
        John->>Alice: Great!
    end
    Ela ->> John: Hello!

As mentioned on the relevant Wikipedia page, class diagrams are a type of static structural diagram in the Unified Modeling Language (UML) that define the structure of a system by showing its classes, attributes, operations (or methods), and the relationships between objects in software engineering¹⁰.

We can start formatting with class to create a class diagram, which is the main building block of object-oriented modeling. Let's create a class diagram for animals to visualize their different types and actions¹¹.

classDiagram
      Animal <|-- Duck
      Animal <|-- Fish
      Animal <|-- Zebra
      Animal : +int age
      Animal : +String gender
      Animal: +isMammal()
      Animal: +mate()
      class Duck{
          +String beakColor
          +swim()
          +quack()
      }
      class Fish{
          -int sizeInFeet
          -canEat()
      }
      class Zebra{
          +bool is_wild
          +run()
      }

State diagrams are commonly used to define a limited number of states related to system behaviors. We can define a state diagram using stateDiagram-v2 through Mermaid. Two special states can be used to represent the start and stop of the diagram, respectively. These expressions are written with the [*] syntax, and the direction of the transition defines it as a start or stop state.

stateDiagram-v2
    [*] --> s1
    s1 --> [*]

We can create nested flows with it as following.

stateDiagram-v2
    [*] --> First
    First --> Second
    First --> Third
    First --> Fourth

    state First {
        [*] --> fir
        fir --> [*]
    }
    state Second {
        [*] --> sec
        sec --> [*]
    }
    state Third {
        [*] --> thi
        thi --> [*]
    }

    state Fourth {
        [*] --> Sixth

        state Fifth {
            [*] --> Sixth
            second --> Third

            state Sixth {
                [*] --> third
                third --> [*]
            }
        }
    }

Entity-relationship (ER) diagrams explain related topics in a specific scope of information. They are often used to create databases. For example, we can handle order and address definitions in the context of customer data using an entity-relationship diagram. A basic ER model consists of entity types (which classify things of interest) and specifies the relationships (instances of these entity types) that can exist between entities¹².

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

User journey diagrams are a type of diagram that allows us to track the steps users take to reach a defined goal in a system, application, or website. For example, we can interpret all the steps from the cart to the payment result page for an e-commerce site using this type of diagram. We can create such diagrams using journey.

journey
    title My working day
    section Go to work
      Make tea: 5: Me
      Go upstairs: 3: Me
      Do work: 1: Me, Cat
    section Go home
      Go downstairs: 5: Me
      Sit down: 5: Me

As mentioned in the article "What is TeamGantt?", I provided basic information about Gantt charts in the context of TeamGantt. Gantt charts are a type of bar chart that shows the flow of a project and the time required to complete it. Mermaid allows us to create such a diagram using gantt¹³.

gantt
    dateFormat  YYYY-MM-DD
    title       Adding GANTT diagram functionality to mermaid
    excludes    weekends
    %% (`excludes` accepts specific dates in YYYY-MM-DD format, days of the week ("sunday") or "weekends", but not the word "weekdays".)

    section A section
    Completed task            :done,    des1, 2014-01-06,2014-01-08
    Active task               :active,  des2, 2014-01-09, 3d
    Future task               :         des3, after des2, 5d
    Future task2              :         des4, after des3, 5d

    section Critical tasks
    Completed task in the critical line :crit, done, 2014-01-06,24h
    Implement parser and jison          :crit, done, after des1, 2d
    Create tests for parser             :crit, active, 3d
    Future task in critical line        :crit, 5d
    Create tests for renderer           :2d
    Add to mermaid                      :1d

    section Documentation
    Describe gantt syntax               :active, a1, after des1, 3d
    Add gantt diagram to demo page      :after a1  , 20h
    Add another diagram to demo page    :doc1, after a1  , 48h

    section Last section
    Describe gantt syntax               :after doc1, 3d
    Add gantt diagram to demo page      :20h
    Add another diagram to demo page    :48h

Pie charts are a type of graph used to show the ratio between related numerical values. In a pie chart, the length of each slice (and thus its central angle and area) represents the amount it corresponds to. Mermaid allows us to create such graphs using pie. They contain much more basic features compared to other diagrams.

pie title Pets adopted by volunteers
    "Dogs" : 386
    "Cats" : 85
    "Rats" : 15

Git graphs (experimental) are a type of diagram that is presented experimentally and continues to be developed to visualize changes in a Git repository. They can be created using gitGraph³.

gitGraph:
options
{
    "nodeSpacing": 150,
    "nodeRadius": 10
}
end
commit
branch newbranch
checkout newbranch
commit
commit
checkout master
commit
commit
merge newbranch

As mentioned in the introduction of the article, diagrams are presented in SVG format, which allows for many customization options either directly or indirectly. When configuration definitions expressed with init are insufficient, we can manipulate the styles with CSS. Below, you can see the code for the diagram I created to summarize the new theme transition process with the purpose of illustrating how we can use CSS to adjust the background and label padding values¹⁴.

div.mermaid {
    background: #1c2230;
}
div.mermaid .edgeLabel,
div.mermaid .label {
    padding: 15px 10px;
}

%%{
    init: {
        'theme': 'base',
        'themeVariables': {
            'primaryColor': '#48556d',
            'primaryBorderColor': '#151920',
            'lineColor': '#135cff',
            'edgeLabelBackground':'#135cff',
            'tertiaryColor': '#151920',
            'nodeTextColor': '#ffffff',
            'arrowheadColor': '#ffffff'
        }
    }
}%%

graph TD
A(WordPress v.1)  -- CMS ve Tema Değişikliği --> B(Grav CMS)
B ==>|Light| C(v.2 Gliese 667 Cb)
B --> |Dark| D(v.3 HD 189733 b)

subgraph Geliştirmeler
    B
    C
end

C ==>|Modüller| D
C -- Geri Bildirimler --> E[A/B Testi]
C -- Online Ürünler --> F[MVT]
E -- Sayfa İçi Özellikler --> C

subgraph Testler
    B
    C
    E
    F
end

E ==>|UI Geliştirme| D
F ==>|Modüler Sayfalar| D

linkStyle 0 stroke-width:2px,fill:none,stroke:blue;
linkStyle 1 stroke-width:2px,fill:none,stroke:green;
linkStyle 2 stroke-width:2px,fill:none,stroke:yellow;
linkStyle 3 stroke-width:2px,fill:none,stroke:pink;
linkStyle default stroke-width:2px,fill:none,stroke:red;

As seen, we can customize the styles of directives with linkStyle and also define general theme-related configurations with init. The background and label padding value are achieved through CSS¹⁵.

Platforms such as GitHub and GitLab currently do not support Mermaid. However, developments in this area are being closely monitored by the community¹⁶¹⁷. On the other hand, it is possible to benefit from various plugins for this process¹⁸. Additionally, various plugins are available for static site tools such as Jekyll¹⁹.

If you use Notion, you can easily include Mermaid diagrams in your content^{20 21}.

As I continue to learn more about Mermaid, which I have encountered recently and used many times in a short period of time, I will make additions related to different writing styles and customizations.

Conclusion

In conclusion, while design programs such as Adobe Illustrator or Sketch are frequently used for creating diagrams, various tools and libraries that enable the creation of diagrams in various formats using programming languages and simple text-based syntaxes exist. One of these options is Mermaid JS, which is a versatile and easily adaptable tool for creating diagrams such as flowcharts, sequence diagrams, class diagrams, Gantt charts, and Git graphs. Additionally, there are other options such as PlantUML and Kroki. Ultimately, selecting a tool or library depends on the specific requirements of the project and the individual's familiarity with programming languages and syntaxes.