November 16, 2022
November 1, 2022
Code Documentation is anything you write in addition to your code to help others understand how it works. A good example of technical documentation I was inspired by is the Rails README file.
Providing coherent and concise code documentation with your GitHub project is not only good for knowledge transfer but also supports troubleshooting issues and makes future management easier in case of additional integrations.
When you write a code document to explain a codebase structure or a project architecture, you need to use diagrams to illustrate it. In this article, I would like to introduce Mermaid - a helpful diagram tool in your Markdown README file.
.png)
A diagram tells a thousand words. Normally, I would draw mine using draw.io and embed those images into Markdown files. They explain the code structures just fine, but sometimes I would prefer if my diagrams could:
If you find yourself struggling with the same problem, I have just an alternative tool for your diagrams - Mermaid.
Mermaid is a JavaScript-based diagramming and charting tool that takes Markdown-inspired text definitions and creates diagrams dynamically in the browser. It supports a bunch of different common diagram types for software projects, including flowcharts, UML, Git graphs, user journey diagrams, and even the dreaded Gantt chart.
Therefore, you don’t have to draw anything, just write down what you want to see! For example:
This is how we do it with Mermaid
And this is the result:
One advantage of using Mermaid is that when you want to keep your diagrams up to date with your change, you can easily edit them by changing the Mermaid codes instead of re-drawing images and embedding them again into the README file.
You can now embed Mermaid code in your README.md and other markdown files. If you do, GitHub will render those codes into a diagram.
Mermaid code uses a simple syntax with mermaid that describes the individual parts of each diagram in plain text. Here’s a closer look at each type of Mermaid chart.
.png)
The start graph TD indicates the orientation of the graph: top-down as opposed to LR (left-right), RL (right-left), or BT (bottom-top).
You can specify nodes by a short identifier (A, B, C, etc.) here and indicate what shape and text they should have with the brackets following it. You can specify many shapes, including circles, rhombus, or trapezoids.
To specify the arrows from one box to another, you just type the two node IDs joined by an arrow, depending on what arrow type you want. You can add text to the arrows with the |<text>| before the destination node.
You will see this pie chart in the markdown file:
Another chart type is Gantt, commonly used for project management.
Mermaid also supports the following types of diagrams:
Some editors support Mermaid, including Atom, VIM and VS Code. Using VS Code, and the extension Markdown Preview Mermaid Support is very helpful in rendering the graphs in the markdown previews.
This is the simplest way to try out Mermaid, using their online tool. You can start with a template, and verify how your changes affect the final result. You can also try another powerful online Markdown editor Stackedit https://stackedit.io/app#
Mermaid diagrams are a useful addition to GitHub/GitLab by default in its Markdown, particularly since they encourage better documentation, saving you so much time and effort to create diagrams. They’re what our team at FABA use along with our code documentation to explain our projects in a more coherent and direct way.
.png)