Mermaid diagrams in GitHub and GitLab

The syntax

In any Markdown file, open a code block with three backticks followed by mermaid, paste the diagram, and close the block:

```mermaid
flowchart LR
  A[Push] --> B[CI tests] --> C{Pass?}
  C -->|Yes| D[Deploy]
  C -->|No| E[Notify author]
```

GitHub has rendered Mermaid blocks since February 2022, in Markdown files, issues, pull requests, discussions and wikis. GitLab renders them in Markdown across the product, including merge requests and wikis.

Where it is most useful

• README: show how the service works, or the main user flow, right on the repository page.
• Architecture decision records: compare the current and proposed flows.
• Pull requests: illustrate a change to a process or an API workflow next to the code that implements it.
• Issues: describe a bug as the path that leads to it.

Keep diagrams up to date

Because the diagram is text in the repository, it can be reviewed and changed in the same pull request as the code. A rule that helps: when a pull request changes a flow, it updates the diagram too.

Troubleshooting

• Shows as code instead of a diagram: check that the block language is exactly mermaid and that the block is properly closed.
• Error message instead of a diagram: a syntax problem, often unquoted parentheses or the word "end"; see the syntax cheat sheet.
• Different rendering from your editor: platforms ship their own Mermaid version, so very recent features may not be available yet. Stick to core flowchart syntax for portability.
• Very large charts become unreadable: split them into several diagrams.

Generate instead of typing

For a process described in words, you can generate the chart with Flowchartio, export it as Mermaid (.mmd), and paste the file content into the code block. Lanes are exported as subgraphs, explained in subgraphs and styling.

Other places Mermaid renders natively are covered in Mermaid in Notion, Obsidian and docs tools.