11.05 Images - practicalseries/GitHub-Wiki-Design-and-Implementation GitHub Wiki
This is a bit of an odd thing and it is entirely GitHub Markdown (rather than Markdown in general).
GitHub has built in support for something called Mermaid diagrams๐ 1, these allow various types of flowchart and planning diagrams to be coded directly in the Markdown file.
Mermaid diagrams are quite astonishing (thereโs a lot of them), they range from simple flow charts:
Markdown and GitHub output | |
---|---|
|
|
```mermaid flowchart TB A[Hard] -->|Text| B(Rounded) B --> C{Decision} C -->|One| D([Stadium]) C -->|Two| E[(Database)] C -->|Three| F((Circle)) ```
|
flowchart TB
A[Hard] -->|Text| B(Rounded)
B --> C{Decision}
C -->|One| D([Stadium])
C -->|Two| E[(Database)]
C -->|Three| F((Circle))
|
Table 11.18 โ Mermaid flowchart |
To Gantt charts:
Markdown and GitHub output |
---|
|
```mermaid 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 :after a1 , 20h Add another diagram to demo :doc1, after a1 , 48h section Last section Describe gantt syntax :after doc1, 3d Add gantt diagram to demo :20h Add another diagram to demo :48h ```
|
|
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 :after a1 , 20h
Add another diagram to demo :doc1, after a1 , 48h
section Last section
Describe gantt syntax :after doc1, 3d
Add gantt diagram to demo :20h
Add another diagram to demo :48h
|
Table 11.19 โ Mermaid Gantt chart |
It can do GitHub branch diagrams:
Markdown and GitHub output | |
---|---|
|
|
```mermaid gitGraph commit commit branch develop checkout develop commit commit checkout main merge develop commit commit ```
|
gitGraph
commit
commit
branch develop
checkout develop
commit
commit
checkout main
merge develop
commit
commit
|
Table 11.20 โ Mermaid Git diagram |
And complicated structural C4 (context, containers, components, and code) models:
Markdown and GitHub output |
---|
|
```mermaid C4Context title System Context diagram for Internet Banking System Person(customerA, "Banking Customer A", "A customer of the bank, with personal bank accounts.") Person(customerB, "Banking Customer B") Person_Ext(customerC, "Banking Customer C") System(SystemAA, "Internet Banking System", "Allows customers to view information about their bank accounts, and make payments.") Person(customerD, "Banking Customer D", "A customer of the bank,
|
|
C4Context
title System Context diagram for Internet Banking System
Person(customerA, "Banking Customer A", "A customer of the bank, with personal bank accounts.")
Person(customerB, "Banking Customer B")
Person_Ext(customerC, "Banking Customer C")
System(SystemAA, "Internet Banking System", "Allows customers to view information about their bank accounts, and make payments.")
Person(customerD, "Banking Customer D", "A customer of the bank, <br/> with personal bank accounts.")
Enterprise_Boundary(b1, "BankBoundary") {
SystemDb_Ext(SystemE, "Mainframe Banking System", "Stores all of the core banking information about customers, accounts, transactions, etc.")
System_Boundary(b2, "BankBoundary2") {
System(SystemA, "Banking System A")
System(SystemB, "Banking System B", "A system of the bank, with personal bank accounts.")
}
System_Ext(SystemC, "E-mail system", "The internal Microsoft Exchange e-mail system.")
SystemDb(SystemD, "Banking System D Database", "A system of the bank, with personal bank accounts.")
Boundary(b3, "BankBoundary3", "boundary") {
SystemQueue(SystemF, "Banking System F Queue", "A system of the bank, with personal bank accounts.")
SystemQueue_Ext(SystemG, "Banking System G Queue", "A system of the bank, with personal bank accounts.")
}
}
BiRel(customerA, SystemAA, "Uses")
BiRel(SystemAA, SystemE, "Uses")
Rel(SystemAA, SystemC, "Sends e-mails", "SMTP")
Rel(SystemC, customerA, "Sends e-mails to")
|
Table 11.21 โ Mermaid C4 chart |
In fact it supports all the following:
โ | Sequence Diagram |
โก | Class Diagram |
โข | State Diagram |
โฃ | Entity Relationship Diagram |
โค | User Journey |
โฅ | Gantt |
โฆ | Pie Chart |
โง | Quadrant Chart |
โจ | Requirement Diagram |
โฉ | Gitgraph (Git) Diagram |
โช | C4 Diagram |
โซ | Mindmaps |
โฌ | Timeline |
โญ | ZenUML |
โฎ | Sankey |
โฏ | XY Chart |
โฐ | Block Diagram |
โฑ | Packet |
โฒ | Kanban |
โณ | Architecture |
List 11.4 โ List of Mermaid Diagram types |
---|
Yes, Iโve no idea what a sanky diagram or a Kanban is either.
Mermaid diagrams are created using a fenced code block (these are covered in detail in section 13.2). These begin with three backticks (```
) followed by the word mermaid
:
โโโ```mermaid
And end with three more backticks:
โโโ```
The Mermaid configuration syntax fits in between the two:
Markdown and GitHub output | |
---|---|
|
|
```mermaid flowchart TB A[Hard] -->|Text| B(Rounded) B --> C{Decision} C -->|One| D([Stadium]) C -->|Two| E[(Database)] C -->|Three| F((Circle)) ```
|
flowchart TB
A[Hard] -->|Text| B(Rounded)
B --> C{Decision}
C -->|One| D([Stadium])
C -->|Two| E[(Database)]
C -->|Three| F((Circle))
|
The above renders as a top to bottom flow chart.
The full Mermaid language syntax is beyond the scope of this document (it isnโt that difficult to understand, just that there is a lot of it). The Mermaid site contains a full set of documentation and tutorials, itโs available here:
โโโhttps://mermaid.js.org/intro/
Itโs very comprehensive.
The website looks like this:
![]() |
Figure 11.8 โ Mermaid documentation website |
---|
To find out how to render any of the diagrams highlighted, just click the link on the left and it will show the syntax, examples and all the options for that particular type of diagram (I particularly recommend trying the Sankey diagram, shown below).
sankey-beta
Agricultural 'waste',Bio-conversion,124.729
Bio-conversion,Liquid,0.597
Bio-conversion,Losses,26.862
Bio-conversion,Solid,280.322
Bio-conversion,Gas,81.144
Biofuel imports,Liquid,35
Biomass imports,Solid,35
Coal imports,Coal,11.606
Coal reserves,Coal,63.965
Coal,Solid,75.571
District heating,Industry,10.639
District heating,Heating and cooling - commercial,22.505
District heating,Heating and cooling - homes,46.184
Electricity grid,Over generation / exports,104.453
Electricity grid,Heating and cooling - homes,113.726
Electricity grid,H2 conversion,27.14
Electricity grid,Industry,342.165
Electricity grid,Road transport,37.797
Electricity grid,Agriculture,4.412
Electricity grid,Heating and cooling - commercial,40.858
Electricity grid,Losses,56.691
Electricity grid,Rail transport,7.863
Electricity grid,Lighting & appliances - commercial,90.008
Electricity grid,Lighting & appliances - homes,93.494
Gas imports,Ngas,40.719
Gas reserves,Ngas,82.233
Gas,Heating and cooling - commercial,0.129
Gas,Losses,1.401
Gas,Thermal generation,151.891
Gas,Agriculture,2.096
Gas,Industry,48.58
Geothermal,Electricity grid,7.013
H2 conversion,H2,20.897
H2 conversion,Losses,6.242
H2,Road transport,20.897
Hydro,Electricity grid,6.995
Liquid,Industry,121.066
Liquid,International shipping,128.69
Liquid,Road transport,135.835
Liquid,Domestic aviation,14.458
Liquid,International aviation,206.267
Liquid,Agriculture,3.64
Liquid,National navigation,33.218
Liquid,Rail transport,4.413
Marine algae,Bio-conversion,4.375
Ngas,Gas,122.952
Nuclear,Thermal generation,839.978
Oil imports,Oil,504.287
Oil reserves,Oil,107.703
Oil,Liquid,611.99
Other waste,Solid,56.587
Other waste,Bio-conversion,77.81
Pumped heat,Heating and cooling - homes,193.026
Pumped heat,Heating and cooling - commercial,70.672
Solar PV,Electricity grid,59.901
Solar Thermal,Heating and cooling - homes,19.263
Solar,Solar Thermal,19.263
Solar,Solar PV,59.901
Solid,Agriculture,0.882
Solid,Thermal generation,400.12
Solid,Industry,46.477
Thermal generation,Electricity grid,525.531
Thermal generation,Losses,787.129
Thermal generation,District heating,79.329
Tidal,Electricity grid,9.452
UK land based bioenergy,Bio-conversion,182.01
Wave,Electricity grid,19.013
Wind,Electricity grid,289.366
The rendered diagram on the GitHub looks like this:
![]() |
Figure 11.9 โ Mermaid diagram controls |
---|
The controls (highlighted) allow the graphic to be manipulated as follows:
Symbol | Function |
---|---|
![]() |
Opens the diagram in an enlarged floating window |
![]() |
Copies the Markdown code behind the diagram |
![]() |
Zoom in/out |
![]() |
Scroll left, right, up or down |
![]() |
Reset the image to its original state (size) |
Table 1122 โ Mermaid display controls |
The version of Mermaid currently supported by GitHub can be identified by putting the following into a Markdown page:
Markdown and GitHub output | |
---|---|
|
|
```mermaid info ```
|
info
|
This will display the current version on the rendered page. At the time of writing, GitHub was at version 11.3.0 of Mermaid; Mermaid itself was at version 11.4.1 so GitHub is a few revisions behind (two to be exact).
The Mermaid project is actually a repository on GitHub and can be accessed here:
โโโhttps://github.com/mermaid-js/mermaid
GitHub supports two types of interactive maps, the first is called GeoJSON and the second TopoJSON.
Iโm going to ignore TopoJSON, itโs just too difficult to understand and work with.
This is a GeoJSON map of Chester (Chester cathedral to be exact):
Markdown and GitHub output |
---|
|
```geojson { "coordinates": [-2.890456668659124,53.19188063886462], "type": "Point" } ```
|
|
{
"coordinates": [-2.890456668659124,53.19188063886462],
"type": "Point"
}
|
Table 11.23 โ GeoJSON map |
The syntax involved in both the GeoJSON and TopoJSON applications can be complicated (the example above is deceivingly simple). The syntax for TopoJSON was impenetrable and I ran out of patience with it.
GeoJSON does have a saving grace, it has its own website with a full map of the world that you can manipulate (zoom in, zoom out, drop points, mark areas &c.) and it will automatically generate the GeoJSON code that you can paste directly into your Markdown (thatโs how I got the Map of Chester).
The website is:
โโโhttps://geojson.io/
It looks like this:
![]() |
Figure 11.10 โ GeoJSON interactive map website |
---|
The area on the right contains the GeoJSON code for the current view.
Zooming into a particular area and then using the toolbar in the main area to select an area (with polygons, squares &c.) or drop points will produce code in the right-hand column.
In the following example, Iโve drawn a polygon area around Chester, the GeoJSON code for it can be seen in the right area.
![]() |
Figure 11.11 โ Cheser defined as an area |
---|
To use this in GitHub Markdown, simply copy everything in the right-hand area and paste it into the Markdown file.
The code must be preceeded with ```geojson
and followed with three backticks ```
.
Markdown and GitHub output |
---|
|
```geojson { "type": "FeatureCollection", "features": [ { "type": "Feature", "properties": {}, "geometry": { "coordinates": [ [ [ -2.894016844090686, 53.22606316381487 ], [ -2.943029960491174, 53.20339794394624 ], [ -2.9408566337193633, 53.175461291545616 ], [ -2.8704974571575974, 53.16529453461672 ], [ -2.8466077121183275, 53.2009158858929 ], [ -2.894016844090686, 53.22606316381487 ] ] ], "type": "Polygon" } } ] } ```
|
|
{
"type": "FeatureCollection",
"features": [
{
"type": "Feature",
"properties": {},
"geometry": {
"coordinates": [
[
[
-2.894016844090686,
53.22606316381487
],
[
-2.943029960491174,
53.20339794394624
],
[
-2.9408566337193633,
53.175461291545616
],
[
-2.8704974571575974,
53.16529453461672
],
[
-2.8466077121183275,
53.2009158858929
],
[
-2.894016844090686,
53.22606316381487
]
]
],
"type": "Polygon"
}
}
]
}
|
Table 11.24 โ GeoJSON script copied from the website |
Note
The same website can produce TopoJSON scripts too, instead of copying the code in the right window, click Save
(top left) and select TopoJSON
from the dropdown, it will save the code in a file for you.
Paste the contents of the file into a Markdown file, but this time precede it with: ```topojson
.
This, I think, is also a bit peculiar (the things GitHub want to include, we can have rotating 3D models, but we canโt change the font colour).
For whatever reason, GitHub supports the rendering of 3D models, these can be embedded into a Wiki page between ```stl
and followed with three backticks ```
, in a similar way to interactive maps and the Mermaid diagrams covered in the previous two sections.
The model itself is created in ASCII STL๐ 2 which is a format often used by 3D printers. ASCII STL is text based, but STL files can be generated as binary files (this is the more common approach). Binary STL files can be converted to ASCII STL using an online converter such as this:
โโโhttps://www.meshconvert.com/
The following is the ASCII STL for a cube:
Markdown and GitHub output |
---|
|
```stl solid AssimpScene facet normal 0 0 1 outer loop vertex -35 60 20 vertex -55 60 20 vertex -35 40 20 endloop endfacet facet normal 0 0 1 outer loop vertex -35 40 20 vertex -55 60 20 vertex -55 40 20 endloop endfacet facet normal 0 0 -1 outer loop vertex -35 40 0 vertex -55 40 0 vertex -35 60 0 endloop endfacet facet normal 0 0 -1 outer loop vertex -35 60 0 vertex -55 40 0 vertex -55 60 0 endloop endfacet facet normal 0 -1 0 outer loop vertex -55 40 20 vertex -55 40 0 vertex -35 40 20 endloop endfacet facet normal 0 -1 0 outer loop vertex -35 40 20 vertex -55 40 0 vertex -35 40 0 endloop endfacet facet normal -1 0 0 outer loop vertex -55 60 20 vertex -55 60 0 vertex -55 40 20 endloop endfacet facet normal -1 0 0 outer loop vertex -55 40 20 vertex -55 60 0 vertex -55 40 0 endloop endfacet facet normal 0 1 0 outer loop vertex -35 60 20 vertex -35 60 0 vertex -55 60 20 endloop endfacet facet normal 0 1 0 outer loop vertex -55 60 20 vertex -35 60 0 vertex -55 60 0 endloop endfacet facet normal 1 0 0 outer loop vertex -35 40 20 vertex -35 40 0 vertex -35 60 20 endloop endfacet facet normal 1 0 0 outer loop vertex -35 60 20 vertex -35 40 0 vertex -35 60 0 endloop endfacet endsolid AssimpScene ```
|
|
solid AssimpScene
facet normal 0 0 1
outer loop
vertex -35 60 20
vertex -55 60 20
vertex -35 40 20
endloop
endfacet
facet normal 0 0 1
outer loop
vertex -35 40 20
vertex -55 60 20
vertex -55 40 20
endloop
endfacet
facet normal 0 0 -1
outer loop
vertex -35 40 0
vertex -55 40 0
vertex -35 60 0
endloop
endfacet
facet normal 0 0 -1
outer loop
vertex -35 60 0
vertex -55 40 0
vertex -55 60 0
endloop
endfacet
facet normal 0 -1 0
outer loop
vertex -55 40 20
vertex -55 40 0
vertex -35 40 20
endloop
endfacet
facet normal 0 -1 0
outer loop
vertex -35 40 20
vertex -55 40 0
vertex -35 40 0
endloop
endfacet
facet normal -1 0 0
outer loop
vertex -55 60 20
vertex -55 60 0
vertex -55 40 20
endloop
endfacet
facet normal -1 0 0
outer loop
vertex -55 40 20
vertex -55 60 0
vertex -55 40 0
endloop
endfacet
facet normal 0 1 0
outer loop
vertex -35 60 20
vertex -35 60 0
vertex -55 60 20
endloop
endfacet
facet normal 0 1 0
outer loop
vertex -55 60 20
vertex -35 60 0
vertex -55 60 0
endloop
endfacet
facet normal 1 0 0
outer loop
vertex -35 40 20
vertex -35 40 0
vertex -35 60 20
endloop
endfacet
facet normal 1 0 0
outer loop
vertex -35 60 20
vertex -35 40 0
vertex -35 60 0
endloop
endfacet
endsolid AssimpScene
|
Table 11.25 โ ASCII STL 3D model of a cube |
The cube can be re-oriented by clicking and dragging with a mouse, it will also automatically begin to rotate along the horizontal plane if left alone.
The Wireframe, Surface Angle and Solid options show the object as either its component wire frame, individual surfaces or a shaded solid.
Appendix D contains the code for a Sierpinski cube (a fractal derivation of a cube), there is a lot of it.
Footnotes:โโโโโ
Note
๐ 1โMermaid is a Markdown based tool developed by Knut Sveidqvist (apparently, he named it Mermaid because his children were watching The Little Mermaid when he started the project) that generates various type of diagrams: flowcharts, sequence diagrams, Gantt charts, class ar-rangements, Git branch diagrams, quadrants, pie charts &c.โฉ
Note
๐ 2โSTL stands for STereo Lithography and is a plain text mechanism for describing (and render-ing) the surface of an object as a mesh of triangles.โฉ