Everyone is welcome, everyone can contribute, everyone is unique and these are your strengths too!

GitLab Flavored Markdown: Mermaid

GitLab Flavored Markdown is a really powerful language. You can easily write text in your GitLab issue or merge request. But there are some features which you maybe don’t know about which can make your experience with GitLab much better.

NOTE: If you want to find out more about GitLab Flavored Markdown, just click on the Markdown link in the bottom left corner of every markdown text field in GitLab or checkout the documentation of GitLab Flavored Markdown.

mermaid

mermaid is an awesome library to create diagrams and flowcharts. It’s designed very similar as markdown itself (in spirit) and is really easy to use. You can just write your mermaid code and generate beautiful diagrams out of it.

sequenceDiagram
  Michael->>+Mario: Hello mario, how are you?
  Mario->>+Michael: Fine

will be rendered to

  sequenceDiagram
  Michael->>+Mario: Hello mario, how are you?
  Mario->>+Michael: Fine

Checkout the mermaid live editor to play around with the different types of diagrams.

mermaid in GitLab

mermaid is directly supported in GitLab, out of the box, anywhere you can type markdown.

This includes

  • issue description
  • issue comments
  • merge request description
  • merge request comments
  • markdown files in a repo with f.e. a .md extension

You can use normal markdown code fences to code your diagram. Our mermaid code example from above would be used in GitLab Flavored Markdown with the following code …


```mermaid
  sequenceDiagram
  Michael->>+Mario: Hello mario, how are you?
  Mario->>+Michael: Fine
```

and will be rendered to

  sequenceDiagram
  Michael->>+Mario: Hello mario, how are you?
  Mario->>+Michael: Fine

In GitLab 13.0 mermaid 8.4.8 is bundled with GitLab itself, so most features of mermaid are available.

But why should you use mermaid in GitLab?

Do you know the phrase “A picture is worth a thousand words”. In many situations a picture of something transport your idea/message much more then plain text. But creating pictures always require external applications and afterwards you need to copy that picture back to GitLab. When you need a change you hopefully have the original file with all your picture layers like in Photoshop. In short a terrible workflow. Here is where mermaid comes into play. Just write your “simple” mermaid code and you get beautiful diagrams and flowcharts and if you need to change something just edit your f.e. issue like regular text.

Pros:

  • easy to write/create (you don’t need to be a graphic designer)
  • easy to edit
  • create vector graphics instead of pixel based images
  • often much smaller in size then pixel based images

Cons:

  • you need to learn mermaid syntax
  • really complex diagrams maybe not possible (but sometimes you can just split your diagram into multiple ones to overcome this issue)

GitLab mermaid examples

You can use one of the following mermaid types in your next GitLab issue/merge request/comment.

  • Flow chart
    ```mermaid
    graph TD
    A[Christmas] -->|Get money| B(Go shopping)
    B --> C{Let me think}
    C -->|One| D[Laptop]
    C -->|Two| E[iPhone]
    C -->|Three| F[fa:fa-car Car]
    ```
    
    graph TD
    A[Christmas] -->|Get money| B(Go shopping)
    B --> C{Let me think}
    C -->|One| D[Laptop]
    C -->|Two| E[iPhone]
    C -->|Three| F[fa:fa-car Car]
    
  • Sequence Diagram
    ```mermaid
    sequenceDiagram
      Michael->>+Mario: Hello mario, how are you?
      Mario->>+Michael: Fine
    ```
    
    sequenceDiagram
    Michael->>+Mario: Hello mario, how are you?
    Mario->>+Michael: Fine
    
  • Class diagram
    ```mermaid
    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()
      }
    ```
    
    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 diagram
    ```mermaid
    stateDiagram
    [*] --> Still
    Still --> [*]
    
    Still --> Moving
    Moving --> Still
    Moving --> Crash
    Crash --> [*]
    ```
    
    stateDiagram
    [*] --> Still
    Still --> [*]
    
    Still --> Moving
    Moving --> Still
    Moving --> Crash
    Crash --> [*]
    
  • Gantt chart
    ```mermaid
    gantt
    title A Gantt Diagram
    dateFormat  YYYY-MM-DD
    section Section
    A task           :a1, 2014-01-01, 30d
    Another task     :after a1  , 20d
    section Another
    Task in sec      :2014-01-12  , 12d
    another task      : 24d
    ```
    
    gantt
    title A Gantt Diagram
    dateFormat  YYYY-MM-DD
    section Section
    A task           :a1, 2014-01-01, 30d
    Another task     :after a1  , 20d
    section Another
    Task in sec      :2014-01-12  , 12d
    another task      : 24d
    
  • Pie chart
    ```mermaid
    pie title Pets adopted by volunteers
    "Dogs" : 386
    "Cats" : 85
    "Rats" : 15
    ```
    
    pie title Pets adopted by volunteers
    "Dogs" : 386
    "Cats" : 85
    "Rats" : 15
    
  • Git graph ⚠️ experimental ⚠️
    ```mermaid
    gitGraph:
    options
    {
        "nodeSpacing": 70,
        "nodeRadius": 10
    }
    end
    commit
    branch newbranch
    checkout newbranch
    commit
    commit
    checkout master
    commit
    commit
    merge newbranch
    ```
    
    gitGraph:
    options
    {
        "nodeSpacing": 70,
        "nodeRadius": 10
    }
    end
    commit
    branch newbranch
    checkout newbranch
    commit
    commit
    checkout master
    commit
    commit
    merge newbranch
    
  • ER diagram ⚠️ experimental ⚠️
    ```mermaid
    erDiagram
      CUSTOMER }|..|{ DELIVERY-ADDRESS : has
      CUSTOMER ||--o{ ORDER : places
      CUSTOMER ||--o{ INVOICE : "liable for"
      DELIVERY-ADDRESS ||--o{ ORDER : receives
      INVOICE ||--|{ ORDER : covers
      ORDER ||--|{ ORDER-ITEM : includes
      PRODUCT-CATEGORY ||--|{ PRODUCT : contains
      PRODUCT ||--o{ ORDER-ITEM : "ordered in"
    ```
    
    erDiagram
      CUSTOMER }|..|{ DELIVERY-ADDRESS : has
      CUSTOMER ||--o{ ORDER : places
      CUSTOMER ||--o{ INVOICE : "liable for"
      DELIVERY-ADDRESS ||--o{ ORDER : receives
      INVOICE ||--|{ ORDER : covers
      ORDER ||--|{ ORDER-ITEM : includes
      PRODUCT-CATEGORY ||--|{ PRODUCT : contains
      PRODUCT ||--o{ ORDER-ITEM : "ordered in"
    
Date published: June 5, 2020