Mermaid

2024-11-17 graph mermaid gitlab diagram html javascript class gantt erd packet mindmap

During my recent study of Gitlab documentation on Markdown I noticed it supports diagrams generated from a text. I am big fan of this approach and I’ve been using graphviz for similar tasks for years. Having it embedded in the readmes feels like another step in right direction for me.

First, this is how it looks like:

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

When displayed by Gitlab, it looks like this without any extra effort:

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

I wanted something similar for this web, so I was looking on how to enable it in Github pages. It turns out, it is quite simple. In your main template just add the Mermaid CDN to your page head element and initialize it within a script after the page is loaded:

<!doctype html>
<html lang=en>
<head>
  ...
  <script src="https://cdn.jsdelivr.net/npm/mermaid@11.4.0/dist/mermaid.min.js"></script>
</head>
<body>
</body>
<script>
  mermaid.initialize({ theme: 'base' });
  mermaid_blocks = document.querySelectorAll('.language-mermaid')
  window.mermaid.init(undefined, mermaid_blocks);
  mermaid_blocks.forEach(mb => mb.parentElement.style.backgroundColor = 'transparent')
</script>
</html>

Last line is there because normally I have code block styled with dark background and do not want that for diagrams.

Few examples of what Mermaid can do

Examples below are mostly copied over from Mermaid docs. The list is pretty impressive, here are just few things that I think will use in the future.

Class diagrams

classDiagram
    note "From Duck till Zebra"
    Animal <|-- Duck
    note for Duck "can fly\ncan swim\ncan dive\ncan help in debugging"
    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()
    }

Entity-relationship diagrams (ERD)

erDiagram
    CUSTOMER ||--o{ ORDER : places
    CUSTOMER {
        string name
        string custNumber
        string sector
    }
    ORDER ||--|{ LINE-ITEM : contains
    ORDER {
        int orderNumber
        string deliveryAddress
    }
    LINE-ITEM {
        string productCode
        int quantity
        float pricePerUnit
    }

Gantt chart

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                      :until isadded
    Functionality added                 :milestone, isadded, 2014-01-25, 0d

    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

Mindmap

mindmap
  root((mindmap))
    Origins
      Long history
      Popularisation
        British popular psychology author Tony Buzan
    Research
      On effectiveness<br/>and features
      On Automatic creation
        Uses
            Creative techniques
            Strategic planning
            Argument mapping
    Tools
      Pen and paper
      Mermaid

Packet

packet-beta
0-15: "Source Port"
16-31: "Destination Port"
32-63: "Sequence Number"
64-95: "Acknowledgment Number"
96-99: "Data Offset"
100-105: "Reserved"
106: "URG"
107: "ACK"
108: "PSH"
109: "RST"
110: "SYN"
111: "FIN"
112-127: "Window"
128-143: "Checksum"
144-159: "Urgent Pointer"
160-191: "(Options and Padding)"
192-255: "Data (variable length)"