Summary

Mermaid is an incredibly popular Markdown-inspired syntax used to visualize workflows, software architecture, and abstract concepts in documentation. Support for displaying Mermaid diagrams has appeared on GitHub's top list of feature requests since 2015. In its absence, many developers simply added screenshots to their Markdown. Today, we're excited to add native support for Mermaid wherever Markdown is supported (e.g., issues, repositories, discussions, gists).

Intended Outcome

With this feature, GitHub will support Mermaid diagrams within Markdown fields and files.

How will it work?

Just as language-specific code blocks can be added to Markdown, you'll be able to add a Mermaid diagram using a code block that specifies mermaid as its language identifier. For example:

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

The Markdown code block above uses Mermaid syntax to display this flowchart in the rendered Markdown:

Another example from the Mermaid website shows how straightforward text can be used to create rich diagrams:

```mermaid
sequenceDiagram
    autonumber
    Alice->>John: Hello John, how are you?
    loop Healthcheck
        John->>John: Fight against hypochondria
    end
    Note right of John: Rational thoughts!
    John-->>Alice: Great!
    John->>Bob: How about you?
    Bob-->>John: Jolly good!
```

The Markdown code block above would display this sequence diagram in the rendered Markdown:

For more information about Mermaid, visit its website or its open-source repository.