Mermaid Diagrams in Markdown
Mermaid integrates with markdown through fenced code blocks. The syntax is universal: wrap Mermaid code in triple backticks with 'mermaid' as the language identifier. Many platforms render these blocks natively, and those that don't can use build-time plugins.
Step-by-Step Guide
Basic markdown syntax
The standard way to embed Mermaid in any markdown file. This syntax works in GitHub, GitLab, Notion, Obsidian, and many documentation tools.
```mermaid
flowchart LR
A[Write] --> B[Preview] --> C[Publish]
```Platforms with native support
These platforms render Mermaid code blocks automatically with no configuration: GitHub (READMEs, issues, PRs, wikis), GitLab, Notion, Obsidian, Azure DevOps, Gitea, and VS Code markdown preview.
Static site generators
For Docusaurus, MkDocs, VitePress, and other static site generators, add a Mermaid plugin to your configuration. Docusaurus uses @docusaurus/theme-mermaid, MkDocs uses the pymdownx.superfences extension with a mermaid custom fence.
Build-time rendering with mermaid-cli
For platforms that don't support runtime rendering, use mermaid-cli (mmdc) to pre-render diagrams as SVG/PNG during your build process. This works with any markdown processor.
Tips
- •Keep diagrams simple in markdown — complex ones are better as linked images
- •Test your Mermaid syntax in our editor before committing to documentation
- •Use our 'Share' feature to create editable links to diagrams alongside your docs
- •Some platforms limit Mermaid diagram size or complexity — test rendering on the target platform
Design Your Diagram First
Use our editor with live preview, autocomplete, and theming — then copy-paste into Markdown.
Open Editor