GitHub’s flavor of markdown already handles images, task lists, and emoji short codes. With support for common diagrams, GitHub is doing its bit for more informative, useful documentation.
What’s New With GitHub?
You can now embed Mermaid code in your README.md and other markdown files. If you do, GitHub will render a diagram described by that code. Mermaid code uses a simple syntax that describes the individual parts of each diagram in plain text.
See also: What Is GitHub? An Introduction to Its Basic Features
How Do You Include Diagrams?
Either choose an existing markdown file or create a new one to add to your repository. Use either . md or . markdown extensions. Add some Mermaid code to that file. Exactly what code is up to you; here’s a simple example to get started: graph TD; A–>B; A–>C; B–>D; C–>D; View the file on GitHub. You should see a nice rendering of your diagram.
Now you just need to learn the wealth of diagrams that Mermaid has available. Or you can simply refer to the Mermaid documentation as and when you need a diagram.
What Kinds of Diagrams Can I Use?
Mermaid supports the following types of diagrams:
Flowchart Sequence Class State Entity Relationship User Journey Gantt Pie Requirement
See also: Gantt Chart vs. PERT Chart: What Are the Differences?
Each has its own syntax, to reflect the type of data that the diagram displays. For example, here’s the code for a simple sequence diagram:
Which looks like this when rendered:
And here’s the code for a basic state diagram:
Which renders as such:
Add Value to Your GitHub Projects With Mermaid Diagrams
Mermaid diagrams are a useful addition to GitHub, particularly since we believe they encourage better documentation. Many projects could be enhanced with some visual explainers right in their documentation or README files.
GitHub is now such a popular service, its features and changes affect many developers around the world. Thankfully, support for Mermaid diagrams is there if you need it, and invisible if you don’t. But, hopefully, you’ll start seeing some nicer documentation at the very least.
