How to Natively Embed Mermaid Diagrams in Markdown

The killer feature of Mermaid.js isn't just its syntax; it's the fact that major platforms now support it natively. You don't need to export PNGs and upload them to your repository anymore.

Markdown Code Blocks

In standard Markdown, you use triple backticks to create a code block. To tell the parser that the block contains Mermaid syntax, you simply use the language identifier mermaid.

```mermaid
pie title Pets Adopted
  "Dogs" : 386
  "Cats" : 85
  "Rabbits" : 15
```
  

Where Does This Work?

• GitHub: Natively supports Mermaid in Issues, Pull Requests, and README files.
• GitLab: Offers full support across their entire platform.
• Notion: You can create a code block, set language to Mermaid, and toggle the view to "Preview".
• Obsidian: The popular personal knowledge management tool has Mermaid built right in.

The Workflow

When drafting complex diagrams, writing them directly in GitHub can be tedious because you have to constantly preview the file. A better workflow is to use a dedicated live editor like Mermaid Preview. Draft your diagram, see the real-time result, and when you're happy, copy the code and paste it into your Markdown file.

Recommended README Workflow

For repository documentation, keep the Mermaid block close to the paragraph it explains. A diagram that appears three screens away from the related explanation is harder to maintain and easier to ignore during review.

• Draft the diagram in Mermaid Preview until the layout is readable.
• Copy only the Mermaid source, not an exported image, when the target platform supports Mermaid.
• Commit the Markdown change with the code or architecture change it describes.
• Ask reviewers to check whether service names, arrows, and error paths match the implementation.

When to Export Instead

Native Mermaid blocks are ideal for developer platforms, but exported SVG or PNG files still make sense for slide decks, PDFs, product docs, or CMS tools that do not support Mermaid rendering. SVG is usually best for text-heavy diagrams because it remains crisp when zoomed. PNG is safer when the destination strips SVG files or when you need a simple image upload.

Common Markdown Mistakes

• Missing the language identifier: use ```mermaid, not a plain code block.
• Using unsupported syntax on a platform: preview the diagram where it will be published, because Mermaid versions can differ.
• Forgetting to update diagrams in pull requests: treat diagram source as part of the feature or bug fix.
• Creating huge diagrams: split large system maps into focused flowcharts, sequence diagrams, or ER diagrams.

Related Resources

• Mermaid diagram examples
• Mermaid flowchart tutorial
• Mermaid sequence diagram tutorial