Mermaid diagrams now render natively in GitHub Markdown

Documentation has long had a blind spot: keeping diagrams in sync with the text they illustrate. Inline images go stale fast, and ASCII art is only legible to the person who drew it. GitHub is addressing that by wiring Mermaid, the JavaScript diagramming tool, directly into its Markdown rendering pipeline.

Mermaid, maintained by Knut Sveidqvist, turns Markdown-inspired text into browser-rendered charts. It covers the standard developer diagram types: flowcharts, UML, Git graphs, user journeys, and Gantt charts. The syntax lives in fenced code blocks with the mermaid language tag:

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

In rendered Markdown, that raw block becomes an interactive diagram rather than a code snippet:

rendered diagram example

Rendering is split between the HTML pipeline and Viewscreen

The implementation is a two-part process. GitHub's HTML pipeline first scans for pre tags carrying the mermaid language designation and swaps them for a template placeholder. The template is progressive: clients that don't run JavaScript—API consumers, for instance—receive the original Mermaid source code, not an empty frame.

For JavaScript-enabled sessions, the pipeline injects an iframe whose src points at Viewscreen, GitHub's internal file rendering service. That separation buys three things:

  • The Mermaid library is served from an external service, keeping the main Rails-rendered JavaScript payload lean.
  • Chart rendering happens asynchronously, so a page containing many diagrams doesn't add render time to the initial ERB compile.
  • User-supplied diagram code is isolated inside an iframe, reducing its ability to interfere with the host GitHub page.

The result is vector-based, editable diagrams that live inline with the prose they document—no image export step, no version drift between diagram and text.

Built with the Mermaid community

GitHub worked with Sveidqvist and the CommonMark community on the feature. Mermaid's contributor base has grown alongside its adoption; for syntax details, the Mermaid site and Sveidqvist's book on the tool are the primary references.