All of these diagrams are dynamically rendered during html display by Github, the images generated from text inside the Github-Flavored Markdown. None are static images. Mermaid support was released for Github on 2022-02-14
Pros & Cons:
- Pro: You don't need to care about the layout.
- Con: You cannot control the layout.
Notes:
- Not all the features of Mermaid (in particular symbols
B-->C[fa:fa-ban forbidden], hyperlink and tooltips) are supported by Github. - A number of other Markdown features don't work within Mermaid labels but don't break it:
:grinning:=😀,*italic*=italic, mathjaxn<sup>2</sup>=n2. - Many characters, in paricular emoji
😀& some extended ASCII†¶(but oddly, not extended ASCII²), break Mermaid with errors. - Some embed GitHub gists and pages into other pages, and this doesn't seem to work (yet).
Docs & Tools:
- Mermaid Docs
- Mermaid Live Editor (Also supports copy from Github gists and saving to
.svg.png) - Mermaid Cheat Sheet
Some real-world examples of Mermaid Diagrams in Github:
graph LR;
A-->B;
A-->C;
B-->D;
C-->D;
flowchart LR
a[Chapter 1] --> b[Chapter 2] --> c[Chapter 3]
c-->d[Using Ledger]
c-->e[Using Trezor]
d-->f[Chapter 4]
e-->f
graph TD;
A-->B;
A-->C;
B-->D;
C-->D;
graph TB
A & B--> C & D
graph TB
A((1))-->B((2))
A-->C((3))
B-->D((4))
B-->E((5))
C-->F((6))
C-->G((7))
D-->H((8))
D-->I((9))
E-->J((10))
graph LR
A[Square Rect] -- Link text --> B((Circle))
A --> C(Round Rect)
B --> D{Rhombus}
C --> D
graph TB
A[Start] ==> B{Is it?};
B -->|Yes| C[OK];
C --> D[Rethink];
D -.-> B;
B ---->|No| E[End];
graph TD
A(Coffee machine <br>not working) --> B{Machine has power?}
B -->|No| H(Plug in and turn on)
B -->|Yes| C{Out of beans or water?} -->|Yes| G(Refill beans and water)
C -->|No| D{Filter warning?} -->|Yes| I(Replace or clean filter)
D -->|No| F(Send for repair)
- Hyperlinks in Github Mermaid are not by default visually different.
- I've tried adding a non-emoji unicode symbols, and even extended ASCII B† to signify a hyperlinks, they do not work. (See issues mermaid-js/mermaid#2869 & mermaid-js/mermaid#2870 )
- Note that tooltips feature of Mermaid does not seem to function.
- TBD: Create a better example and document how Mermaid hyperlinks function better with what GitHub supports, and come up some work-arounds for best practices (maybe some Mermaid styling trick).
flowchart 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"
flowchart LR;
A[CI MULTI CHAPTCHA]-->B{Select captcha service by developer?};
classDef green color:#022e1f,fill:#00f500;
classDef red color:#022e1f,fill:#f11111;
classDef white color:#022e1f,fill:#fff;
classDef black color:#fff,fill:#000;
B--YES-->C[How to use?]:::green;
C-->U[I choose recaptcha.]:::green;
U--Views-->Q["echo CIMC_JS('recaptcha');\n echo CIMC_HTML(['captcha_name'=>'recaptcha']);"]:::green;
U--Controller-->W["CIMC_RULE('recaptcha');"]:::green;
C-->I[I choose arcaptcha.]:::white;
I--Views-->O["echo CIMC_JS('arcaptcha');\n echo CIMC_HTML(['captcha_name'=>'arcaptcha']);"]:::white;
I--Controller-->P["CIMC_RULE('arcaptcha');"]:::white;
C-->X[I choose bibot.]:::red;
X--Views-->V["echo CIMC_JS('bibot');\n echo CIMC_HTML(['captcha_name'=>'bibot']);"]:::red;
X--Controller-->N["CIMC_RULE('bibot');"]:::red;
B--NO-->D[How to use?]:::black;
D---Views:::black-->F["echo CIMC_JS('randomcaptcha');\n echo CIMC_HTML(['captcha_name'=>'randomcaptcha']);"]:::black;
D---Controller:::black-->T["CIMC_RULE('archaptcha,recaptcha,bibot');"]:::black;
graph TB
c1-->a2
subgraph one
a1-->a2
end
subgraph two
b1-->b2
end
subgraph three
c1-->c2
end
graph TB
sq[Square shape] --> ci((Circle shape))
subgraph A
od>Odd shape]-- Two line<br/>edge comment --> ro
di{Diamond with <br/> line break} -.-> ro(Rounded<br>square<br>shape)
di==>ro2(Rounded square shape)
end
%% Notice that no text in shape are added here instead that is appended further down
e --> od3>Really long text with linebreak<br>in an Odd shape]
%% Comments after double percent signs
e((Inner / circle<br>and some odd <br>special characters)) --> f(,.?!+-*ز)
cyr[Cyrillic]-->cyr2((Circle shape Начало));
classDef green fill:#9f6,stroke:#333,stroke-width:2px;
classDef orange fill:#f96,stroke:#333,stroke-width:4px;
class sq,e green
class di orange
From Com Powys-Lybbe's blog, this examples shows some best practices of comments to seperate nodes, links, and styles.
graph TD%% Adding a title to the flowchart using the SubGraph feature
subgraph SGTitle ["WHAT IS THE ROOT CAUSE OF THE PROBLEM? ____"]
%% Nodes
0[Key Variable<br>Target: 100, Actual: 80]
1[Top Variable 1<br>Tgt: 20, Act: 20]
2[Top Variable 2<br>Tgt: 30, Act: 30]
3[Top Variable 3<br>Tgt: 50, Act: 30]
31[Sub Variable 1<br>Tgt: 25, Act: 25]
32[Sub Variable 2<br>Tgt: 25, Act: 5]
321[Element 1<br>Tgt: 20, Act: 1]
322[Element 2<br>Tgt: 5, Act: 4]
%% Close title subgraph
end
%% Links
0 --- 1
0 --- 2
0 --- 3
3 --- 31
3 --- 32
32 --- 321
32 --- 322
%% Defining node styles
classDef Red fill:#FF9999;
classDef Amber fill:#FFDEAD;
classDef Green fill:#BDFFA4;
%% Assigning styles to nodes
class 3,32,321 Red;
class 322 Amber;
class 1,2,31 Green;
%% Changing color of links [NOTE: Link arrows will remain black]
linkStyle default fill: none, stroke: grey;
%% Styling the title subgraph
classDef Title fill:#FF99FF00, stroke-width:0, color:grey, font-weight:bold, font-size: 17px;
class SGTitle Title;
sequenceDiagram
Alice ->> Bob: Hello Bob, how are you?
Bob-->>John: How about you John?
Bob--x Alice: I am good thanks!
Bob-x John: I am good thanks!
Note right of John: Bob thinks a long<br/>long time, so long<br/>that the text does<br/>not fit on a row.
Bob-->Alice: Checking with John...
Alice->John: Yes... John, how are you?
sequenceDiagram
participant c as Client
participant s as Server
c->>s: SYN
note over c, s: SEQ1 = 100<br>ACK1 not set
s->>c: SYN+ACK
note over c, s: SEQ2 = 300<br>ACK2 = 100+1 = 101
c->>s: ACK
note over c, s: SEQ3 = 101<br>ACK3 = 300+1 = 301
sequenceDiagram
A->> B: Query
B->> C: Forward query
Note right of C: Thinking...
C->> B: Response
B->> A: Forward response
sequenceDiagram
participant dotcom
participant iframe
participant viewscreen
dotcom->>iframe: loads html w/ iframe url
iframe->>viewscreen: request template
viewscreen->>iframe: html & javascript
iframe->>dotcom: iframe ready
dotcom->>iframe: set mermaid data on iframe
iframe->>iframe: render mermaid
sequenceDiagram
autonumber
Student->>Admin: Can I enrol this semester?
loop enrolmentCheck
Admin->>Admin: Check previous results
end
Note right of Admin: Exam results may <br> be delayed
Admin-->>Student: Enrolment success
Admin->>Professor: Assign student to tutor
Professor-->>Admin: Student is assigned
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()
}
stateDiagram-v2
[*] --> Still
Still --> [*]
Still --> Moving
Moving --> Still
Moving --> Crash
Crash --> [*]
stateDiagram-v2
[*] --> Unwritten
Unwritten --> Open: Open
Unwritten --> Void: Void
Open --> Void: Void
Open --> Cancelled: Cancel
Open --> Closed: Close
Open --> Open: Update
Closed --> Open: Open
stateDiagram-v2
[*] --> First
state First {
[*] --> second
second --> [*]
}
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
State1: The state with a note
note right of State1
Important information! You can write
notes.
end note
State1 --> State2
note left of State2 : This is the note to the left.
stateDiagram-v2
direction LR
[*] --> Initialed
Initialed --> SellerSent
SellerSent --> Transported
Transported --> BuyerPicked
BuyerPicked --> Delivered
Delivered --> [*]
BuyerPicked --> BuyerSent
BuyerSent --> ReturnTransported
ReturnTransported --> SellerPicked
SellerPicked --> [*]
Transported --> ReturnTransported: buyer doesn'y pick up the item after 1 week
gantt
title Example Gantt diagram
dateFormat YYYY-MM-DD
section Team 1
Research & requirements :done, a1, 2020-03-08, 2020-04-10
Review & documentation : after a1, 20d
section Team 2
Implementation :crit, active, 2020-03-25 , 20d
Testing :crit, 20d
gantt
dateFormat YYYY-MM-DD
title Adding GANTT diagram to mermaid
excludes weekdays 2014-01-10
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
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
}
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"
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
pie title Pets adopted by volunteers
"Dogs" : 386
"Cats" : 85
"Rats" : 15
requirementDiagram
requirement test_req {
id: 1
text: the test text.
risk: high
verifymethod: test
}
element test_entity {
type: simulation
}
test_entity - satisfies -> test_req
This does not seem to be documented, see [mermaid-js/mermaid#2011].
gitGraph:
options
{
"nodeSpacing": 150,
"nodeRadius": 10
}
end
commit
branch newbranch
checkout newbranch
commit
commit
checkout master
commit
commit
merge newbranch