Markdown Mermaid Diagram
How to embed Mermaid diagrams in markdown for flowcharts, sequence diagrams, Gantt charts, and more. GitHub native support.
What is markdown mermaid diagram?
Mermaid is a JavaScript-based diagram tool that uses text syntax to generate flowcharts, sequence diagrams, Gantt charts, entity-relationship diagrams, and more. In markdown, a fenced code block with the mermaid language identifier tells the renderer to parse and render the Mermaid syntax as an SVG diagram.
Syntax
Flowchart
TD = top-down. Use LR for left-right. Nodes in [] are rectangles, {} are diamonds (decisions).
Sequence diagram
->> is a solid arrow, -->> is a dashed arrow.
Gantt chart
Gantt charts show project timelines with task dependencies.
Platform support
| Platform | Supported | Notes |
|---|---|---|
| GitHub | Yes | Native rendering since 2022 |
| GitLab | Yes | — |
| Obsidian | Yes | Native rendering |
| Notion | No | — |
| Discord | No | Renders as code block |
| Slack | No | — |
Common mistakes
Using mermaid without the language identifier
```mermaid (not just ```)
The block must be tagged with mermaid as the language. Without it, the content renders as a plain code block.
Tips for mermaid diagram
Use mermaid.live to build and test diagrams before pasting into your markdown file. The editor gives instant visual feedback.
Complex diagrams with many nodes become unreadable. Break large diagrams into multiple focused ones.
Frequently asked questions
Everything you need to know.
How do I add a diagram to a GitHub README?
Use a fenced code block with mermaid as the language: ```mermaid followed by your diagram syntax. GitHub has rendered Mermaid natively since 2022.
Related elements
Code Block
Markdown supports two types of code formatting: inline code with single backticks (`) for short snippets, and fenced code blocks with triple backticks (```) for multi-line code with optional syntax highlighting.
HTML Block
Most markdown parsers allow you to embed raw HTML directly in your markdown file. HTML blocks let you use elements not supported by markdown — custom divs, details/summary, colored text, form elements, and more. HTML support depends on the platform — some sanitize or strip it entirely.
Image
Images in markdown use the same syntax as links but with an exclamation mark prefix: . The alt text describes the image for screen readers and when the image fails to load.
Try it in the editor
Paste your markdown and see mermaid diagram rendered instantly with professional themes.