Include diagrams in your Markdown files with Mermaid

A picture tells a thousand words, but up until now the only way to include pictures and diagrams in your Markdown files on GitHub has been to embed an image. We added Mermaid syntax, for example:

```mermaid
  graph TD;
      A-->B;
      A-->C;
      B-->D;
      C-->D;
```

The raw code block above will appear as this diagram in the rendered Markdown:

HTML pipeline and Viewscreen, our internal file rendering service.

First, we add a filter to the HTML pipeline that looks for raw pre tags with the mermaid language designation and substitutes it with a template that works progressively, such that clients requesting content with embedded Mermaid in a non-JavaScript environment (such as an API request) will see the original Markdown code.

Next, assuming the content is viewed in a JavaScript-enabled environment, we inject an iframe into the page, pointing the src attribute to the Viewscreen service. This has several advantages:

• It offloads the library to an external service, keeping the JavaScript payload we need to serve from Rails smaller.
• Rendering the charts asynchronously helps eliminate the overhead of potentially rendering several charts before sending the compiled ERB view to the client.
• User-supplied content is locked away in an iframe, where it has less potential to cause mischief on the GitHub page that the chart is loaded into.

The net result is fast, easily editable, and vector-based diagrams right in your documentation where you need them.

Mermaid has been getting increasingly popular with developers and has a Mermaid book.

Written by

Martin Woodward

@martinwoodward

VP of Developer Relations

Adam Biagianti

@el-mapache