Now, Github allows diagrams and flowcharts in markdown files

Github will allow developers to include diagrams and flowcharts generated using Mermaid–a JavaScript-based diagramming and charting tool–in markdown files. Developers see about 50% productivity boost with easy-to-source documentation.

Earlier, developers used to embed an image on Github in their markdown files and keeping the diagrams up to date was a major challenge.

Mermaid creates diagrams automatically in the browser. Flowcharts, UML, Git graphs, user journey diagrams, and even the dreaded Gantt chart can be built on Mermaid.

How Mermaid works

Github generates an iframe when it encounters the code blocks marked as Mermaid.  The iframe takes the raw Mermaid syntax and passes it to Mermaid.js, which in turn turns the code into a diagram in the local browser. Github follows a two-stage process - GitHub’s HTML pipeline and Viewscreen, Github’s internal file rendering service.

Visual representation of Mermaid’s pipeline:

Mermaid helps developers to produce vector-based diagrams that can be easily embedded into the documentation. Mermaid is becoming popular with developers and has a huge community of contributors. Knut Sveidqvist maintains the Mermaid project.