Draw Diagrams in READMEs using Mermaid

The Markdown format is a blessing for documentation. While many are aware it can create headings, tables, text styles, and lists, not many know about extensions available to the basic Markup language. Today, we'll learn about Mermaid.js. This powerful yet simple diagramming tool speaks to the aspirations of Markdown format.

As a native tool in GitHub.com, any Mermaid syntax is displayed on your READMEs when viewed on the website.

Note: the native VS Code README display tool cannot render Mermaid diagrams. You have to install Yiyi Wang's Markdown Preview Enhanced extension to do so.

Link to examples (GitHub Gist)

https://gist.github.com/farisdurrani/cebe1c0c820dc8cd18501acd4a4a300c

Simple example

Write this on your README, and the following basic flowchart example will show up:

```mermaid
flowchart TD
    A([Start])
    --> B[Task 1]
    --> C[Task 2]
    --> D([End])
```

Standard Flowchart

Here, we make things more complex by adding diverging paths and names on arrows.

Flowchart of git directories

Playing around with shapes and subgraphs... (see the GitHub Gist for full code)

Gitgraph

And a non-flowchart example. Mermaid has tonnes of these.

Official Mermaid Documentation

https://mermaid.js.org

Playground

Use this to test what your Mermaid diagram will look like
https://mermaid.live/edit

Safe harbor statement

The information provided on this channel/article/story is solely intended for informational purposes and cannot be used as a part of any contractual agreement. The content does not guarantee the delivery of any material, code, or functionality, and should not be the sole basis for making purchasing decisions. The postings on this site are my own and do not necessarily reflect the views or work of Oracle or Mythics, LLC.

This work is licensed under a Creative Commons Attribution 4.0 International License.