DEV Community

Cover image for Draw Diagrams in READMEs using Mermaid
Faris Durrani
Faris Durrani

Posted on

2

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




Enter fullscreen mode Exit fullscreen mode

Flowchart basic

Standard Flowchart

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

Code for Standard Example

Standard Flowchart

Flowchart of git directories

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

Flowchart of git directories

Gitgraph

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

Gitgraph

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.

Billboard image

The Next Generation Developer Platform

Coherence is the first Platform-as-a-Service you can control. Unlike "black-box" platforms that are opinionated about the infra you can deploy, Coherence is powered by CNC, the open-source IaC framework, which offers limitless customization.

Learn more

Top comments (0)

A Workflow Copilot. Tailored to You.

Pieces.app image

Our desktop app, with its intelligent copilot, streamlines coding by generating snippets, extracting code from screenshots, and accelerating problem-solving.

Read the docs

👋 Kindness is contagious

Dive into an ocean of knowledge with this thought-provoking post, revered deeply within the supportive DEV Community. Developers of all levels are welcome to join and enhance our collective intelligence.

Saying a simple "thank you" can brighten someone's day. Share your gratitude in the comments below!

On DEV, sharing ideas eases our path and fortifies our community connections. Found this helpful? Sending a quick thanks to the author can be profoundly valued.

Okay