Creation of diagrams in GitHub for better documentation

In this post we are going to see how we can add diagrams to our readme files inside GitHub.

For the last few years, Github have support for different syntaxes inside markdown files to create diagrams and this is huge!
Not only flowcharts, which we usually use when designing systems, but also geolocation and 3D models.

1 - Create diagrams on GitHub

To create diagrams we will use the mermaid library, which has extensive documentation on how to make these diagrams and what types it supports

Among them we can find flowcharts, sequence diagrams, class diagrams, git graph trees or even entity relationship diagrams.

To enable these diagrams we must create a code block in our markdown file and specify mermaid  as the language indicator.

We already know that when we write code and specify the language, it gets "painted" with keywords and so on, but in this case it becomes an image.

For example, with the following code:

```mermaid 
graph LR; 
 orderDb[(ordersDb)] 
 productWriteDb[(product write store)] 
 productReadDb[(Product read store)] 
 PublicApi-->CreateProduct; 
 PublicApi-->UpdateProduct; 
 PublicApi--> CreateOrder; 
 PublicApi-->GetOrder; 
 UpdateProduct-->|CQRS| ProductMs; 
 CreateProduct-->|CQRS| ProductMs; 
 SubscriptionMs-->EmailMs; 
 CreateOrder-->|Event sourcing|OrderMs; 
 GetOrder-->OrderMs; 
 OrderMs-->ProductMs; 
 OrderMs-->EmailMs; 
 PrivateApi-->Reports; 
 Reports-->OrderMs; 
 ProductMs-.->|Eventual Consistency|OrderMs; 
 OrderMs-->orderDb; 
 ProductMs-->productWriteDb; 
 ProductMs-->productReadDb; 

We will get the following diagram:

2 - Create maps on GitHub

We can use geojson or topojson to create maps and within these maps highlight areas, include the typical point indicating a place, etc. 

To do this, just like before, we must include either topojson or geojson as the syntax identifier in our markdown file

This is an example with geojson:

```geojson { "type": "FeatureCollection", "features": [ { "type": "Feature", "id": 1, "properties": { "ID": 0 }, "geometry": { "type": "Polygon", "coordinates": [ [ [-5.5,55.5], [-10.5,55.5], [-10.5,51], [-5.5,51], [-5.5,55.5] ] ] } } ] } ```

Which gives us Ireland:

As we can see, this only generates a square, but we have more complex ones, as complex as we want. In the codeforgermany/click_that_hood repository we can find detailed maps of each country: 

• Note: the maps are interactive.

3 - Create 3D models on GitHub

Finally, the last of GitHub's improvements for diagrams is the possibility of creating 3D objects inside markdown files. To do this we will use the stl syntax identifier.

```stl solid cube_corner facet normal 0.0 -1.0 0.0 outer loop vertex 0.0 0.0 0.0 vertex 1.0 0.0 0.0 vertex 0.0 0.0 1.0 endloop endfacet facet normal 0.0 0.0 -1.0 outer loop vertex 0.0 0.0 0.0 vertex 0.0 1.0 0.0 vertex 1.0 0.0 0.0 endloop endfacet facet normal -1.0 0.0 0.0 outer loop vertex 0.0 0.0 0.0 vertex 0.0 0.0 1.0 vertex 0.0 1.0 0.0 endloop endfacet facet normal 0.577 0.577 0.577 outer loop vertex 1.0 0.0 0.0 vertex 0.0 1.0 0.0 vertex 0.0 0.0 1.0 endloop endfacet endsolid ```

With the following result:

If you access the repository, you will be able to see that the area where the triangle is located is interactive and we can rotate it to view it from different perspectives, etc.