Skip to content

Latest commit

 

History

History
177 lines (139 loc) · 4.12 KB

mermaid-charts-in-github.md

File metadata and controls

177 lines (139 loc) · 4.12 KB
Raw

Mermaid charts in GitHub

Mermaid charts are SVG charts generated from simple markup. They're super useful for displaying logic visually.

Benefits

  • Visual communication can be clearer and easier to understand than written communication, especially for diverse teams with some language barriers.
  • Adding visuals to a written explanation is an effective summary.
  • Visuals make onboarding much more pleasant.
  • A diagram makes it easy to identify bottlenecks, inefficiencies, or other edge cases in processes and situations.

I've only used them for Sequence Diagrams but it supports many other types of charts like Flow Charts, Class Diagrams, State Diagrams, User Journeys, ER Diagrams, Git Graphs, Gantt Charts, and Pie Charts.

For a Mermaid charts editor, I recommend mermaid.live. It's free and updates in real time. You can create and edit your chart there, then paste it into

There's also a VS Code extension but if you type slowly, it will try to render your unfinished input so the integrated preview will look broken until syntax errors are corrected. It works well after you correct syntax errors.

Use in GitHub

Mermaid charts should be in a Markdown fenced code block with mermaid as the language for syntax highlighting. The output is an SVG.

Syntax:

```mermaid

{diagramType}

{Mermaid chart code}

```

GitHub-flavored Markdown only started supporting Mermaid Charts in 2022. See this article for details.

Sequence Diagrams

sequenceDiagram
  participant User as User
  participant FE as Front End
  participant API as API
    User->>+FE: Submit search query
        FE->>+API: Request search query
        API-->>-FE: Respond with search query results
    FE-->>-User: Show search query results
Loading

Flow Chart

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]
Loading

Class Diagram

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()
    }
Loading

State Diagram

stateDiagram-v2
    [*] --> Still
    Still --> [*]
    Still --> Moving
    Moving --> Still
    Moving --> Crash
    Crash --> [*]
Loading

User Journeys

  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: 3: Me
Loading

ER Diagram

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"
Loading

Git Graph

gitGraph
    commit
    commit
    branch develop
    checkout develop
    branch feat1
    checkout feat1
    commit
    commit
    checkout develop
    merge feat1
    branch feat2
    checkout feat2
    commit
    checkout develop
    merge feat2
    checkout main
    merge develop
    commit
    commit
Loading

Gantt Charts

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
Loading

Pie Chart

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