11.05 Images

11.5Mermaid diagrams

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}

${\large \color{#0050C0}\text{M\ A\ R\ K\ D\ O\ W\ N}}$ 🔽

${\large \color{#B00000}\text{G\ I\ T\ H\ U\ B}\space\ \space\text{O\ U\ T\ P\ U\ T}}$ 🔽

```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}
${\large \color{#0050C0}\text{M\ A\ R\ K\ D\ O\ W\ N}}$ 🔽
```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 ```
${\large \color{#B00000}\text{G\ I\ T\ H\ U\ B}\space\ \space\text{O\ U\ T\ P\ U\ T}}$ 🔽
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 Loading
^{Table 11.19 — Mermaid Gantt chart}

It can do GitHub branch diagrams:

^{Markdown and GitHub output}

${\large \color{#0050C0}\text{M\ A\ R\ K\ D\ O\ W\ N}}$ 🔽

${\large \color{#B00000}\text{G\ I\ T\ H\ U\ B}\space\ \space\text{O\ U\ T\ P\ U\ T}}$ 🔽

```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}
${\large \color{#0050C0}\text{M\ A\ R\ K\ D\ O\ W\ N}}$ 🔽
```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, 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") ```
${\large \color{#B00000}\text{G\ I\ T\ H\ U\ B}\space\ \space\text{O\ U\ T\ P\ U\ T}}$ 🔽
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") Loading
^{Table 11.21 — Mermaid C4 chart}

In fact it supports all the following:

	^{List 11.4 — List of Mermaid Diagram types}
①	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

Yes, I’ve no idea what a sanky diagram or a Kanban is either.

⬆️ Top

11.5.1Inserting a Mermaid diagram

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}

${\large \color{#0050C0}\text{M\ A\ R\ K\ D\ O\ W\ N}}$ 🔽

${\large \color{#B00000}\text{G\ I\ T\ H\ U\ B}\space\ \space\text{O\ U\ T\ P\ U\ T}}$ 🔽

```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

⬆️ Top

11.5.2The rendered Mermaid diagram

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}

⬆️ Top

11.5.3Supported version of Mermaid

The version of Mermaid currently supported by GitHub can be identified by putting the following into a Markdown page:

^{Markdown and GitHub output}
${\large \color{#0050C0}\text{M\ A\ R\ K\ D\ O\ W\ N}}$ 🔽	${\large \color{#B00000}\text{G\ I\ T\ H\ U\ B}\space\ \space\text{O\ U\ T\ P\ U\ T}}$ 🔽
```mermaid info ```	info Loading

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

11.6Interactive maps

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}
${\large \color{#0050C0}\text{M\ A\ R\ K\ D\ O\ W\ N}}$ 🔽
```geojson { "coordinates": [-2.890456668659124,53.19188063886462], "type": "Point" } ```
${\large \color{#B00000}\text{G\ I\ T\ H\ U\ B}\space\ \space\text{O\ U\ T\ P\ U\ T}}$ 🔽
{ "coordinates": [-2.890456668659124,53.19188063886462], "type": "Point" } Loading
^{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}
${\large \color{#0050C0}\text{M\ A\ R\ K\ D\ O\ W\ N}}$ 🔽
```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" } } ] } ```
${\large \color{#B00000}\text{G\ I\ T\ H\ U\ B}\space\ \space\text{O\ U\ T\ P\ U\ T}}$ 🔽
{ "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" } } ] } Loading
^{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.

⬆️ Top

11.73D models

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}
${\large \color{#0050C0}\text{M\ A\ R\ K\ D\ O\ W\ N}}$ 🔽
```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 ```
${\large \color{#B00000}\text{G\ I\ T\ H\ U\ B}\space\ \space\text{O\ U\ T\ P\ U\ T}}$ 🔽
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 Loading
^{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.

⬆️ Top

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.↩