Using Mermaid in Markdown: Platform Compatibility Guide

The Rise of Diagrams-as-Code

The ability to embed diagrams directly in Markdown files has transformed how developers document their systems. Instead of maintaining separate diagram files in tools like Lucidchart or draw.io, you can write diagram definitions right alongside your prose. The diagrams live in version control, are reviewable in pull requests, and update automatically when the text changes. Mermaid has become the dominant standard for this approach, and support is now built into most platforms that developers use daily.

This guide covers how to use Mermaid diagrams in every major platform, including the specific syntax each platform expects, rendering differences you should be aware of, and workarounds for common issues. If you want to preview your diagrams before committing them, use our Mermaid Diagram Renderer to see exactly how they will look.

GitHub

GitHub added native Mermaid rendering in February 2022, making it the most widely used platform for Mermaid diagrams. Any Markdown file rendered by GitHub, including README files, issues, pull request descriptions, comments, and wiki pages, supports Mermaid.

Syntax

Wrap your Mermaid code in a fenced code block with the mermaid language identifier:

```mermaid
flowchart LR
    A[Write Code] --> B[Open PR]
    B --> C{Review}
    C -->|Approved| D[Merge]
    C -->|Changes| A
```

GitHub renders this directly in the browser. The diagram appears inline where the code block is placed, replacing the raw text with a rendered SVG graphic. There is no configuration needed and no special setup required.

GitHub-Specific Considerations

• Mermaid version: GitHub uses a specific version of mermaid.js, which may lag behind the latest release. Newer diagram types (like architecture diagrams) may not be available on GitHub yet.
• Theme: GitHub renders diagrams using a neutral theme that respects the viewer's light/dark mode setting. You cannot override the theme on GitHub.
• Interactive features: Click events, tooltips, and other interactive Mermaid features do not work on GitHub for security reasons.
• Size limits: Very large diagrams may not render. GitHub imposes a maximum Mermaid code size of approximately 50KB per block.
• Accessibility: GitHub generates an accessible SVG with a text description derived from the diagram code. Screen readers will announce the diagram type and content.

Best Practices for GitHub

When adding Mermaid diagrams to GitHub README files, keep these guidelines in mind. First, always preview your diagram locally before pushing. Our Mermaid renderer uses the same mermaid.js library and will show you the result instantly. Second, add a brief text description before or after the diagram for users who have images disabled or use screen readers. Third, keep diagrams focused on a single concept rather than trying to show everything in one diagram.

GitLab

GitLab has supported Mermaid rendering since version 10.3. The syntax is identical to GitHub: use a fenced code block with the mermaid language identifier.

```mermaid
sequenceDiagram
    Client->>API: POST /login
    API->>DB: Validate credentials
    DB-->>API: User record
    API-->>Client: JWT token
```

GitLab-Specific Features

• Wiki support: Mermaid works in GitLab wikis, making it ideal for internal documentation that includes architecture diagrams.
• Epics and issues: Mermaid renders in epic descriptions, issue descriptions, and comments.
• Merge request descriptions: Use Mermaid to illustrate the flow your MR implements, making code review easier.
• Version alignment: GitLab typically stays closer to the latest Mermaid release than GitHub does.

Notion

Notion added Mermaid support as a native code block type. To create a Mermaid diagram in Notion, type /code to insert a code block, then select "Mermaid" from the language dropdown. The diagram renders inline when you click outside the code block.

Notion-Specific Notes

• Editing experience: Notion shows the raw code while editing and the rendered diagram when viewing. Click the diagram to switch back to edit mode.
• Export: When exporting Notion pages to Markdown, Mermaid blocks are preserved as fenced code blocks with the mermaid language tag.
• Limitations: Very large diagrams may render slowly in Notion. If you notice performance issues, consider splitting the diagram into multiple smaller diagrams.
• Theming: Notion uses its own styling for Mermaid diagrams, which may look different from how the same diagram appears on GitHub or in our renderer.

Docusaurus

Docusaurus, the popular static site generator for documentation, supports Mermaid through the @docusaurus/theme-mermaid package. Once configured, Mermaid blocks in your Markdown documentation files are rendered automatically.

Setup

npm install @docusaurus/theme-mermaid

// docusaurus.config.js
module.exports = {
  markdown: {
    mermaid: true,
  },
  themes: ['@docusaurus/theme-mermaid'],
};

Usage in MDX

After configuration, Mermaid code blocks work automatically in both .md and .mdx files:

```mermaid
erDiagram
    USER ||--o{ POST : writes
    POST ||--|{ COMMENT : has
    USER ||--o{ COMMENT : writes
```

Docusaurus supports Mermaid theming through the mermaid key in your themeConfig. You can specify different themes for light and dark modes, ensuring diagrams look correct in both color schemes.

VS Code

Visual Studio Code does not render Mermaid natively in its built-in Markdown preview, but the ecosystem provides excellent extensions that make it seamless.

Recommended Extension

Install the Markdown Preview Mermaid Support extension (bierner.markdown-mermaid). This extension adds Mermaid rendering to VS Code's built-in Markdown preview panel. After installation, any mermaid code block in your Markdown files will render as a diagram in the preview pane.

Alternative: Mermaid Editor Extension

For a more dedicated experience, the Mermaid Editor extension provides a side-by-side editor with live preview specifically for .mmd files. This is useful when you are building complex diagrams and want rapid feedback.

Obsidian

Obsidian has native Mermaid support with no plugins required. The syntax follows the standard fenced code block pattern. Mermaid diagrams render in Obsidian's reading view and live preview mode.

```mermaid
mindmap
    root((Project))
        Planning
            Requirements
            Timeline
        Development
            Frontend
            Backend
        Testing
            Unit Tests
            E2E Tests
```

Obsidian-Specific Tips

• Live preview: In Obsidian's live preview mode, Mermaid diagrams render inline as you type. This provides the fastest feedback loop of any Markdown editor.
• Themes: Obsidian's Mermaid rendering respects the app's current theme (light or dark), ensuring diagrams look consistent with the rest of your notes.
• Community plugins: The "Mermaid Tools" community plugin adds a toolbar for inserting Mermaid snippets and a dedicated panel for editing diagrams.
• Export: When publishing Obsidian notes (via Obsidian Publish or third-party tools), Mermaid diagrams are rendered as SVG in the published output.

Other Platforms

Confluence

Atlassian Confluence does not have native Mermaid support, but the Mermaid Diagrams for Confluence marketplace app adds it. Once installed, you can use the Mermaid macro to embed diagrams in any Confluence page.

Jupyter Notebooks

Jupyter notebooks can render Mermaid diagrams using the mermaid magic command provided by packages like nb-mermaid or by rendering in Markdown cells on platforms that support it (JupyterLab with the appropriate extension).

Slack

Slack does not render Mermaid natively. The recommended workflow is to render your diagram using our Mermaid Renderer, export it as SVG or PNG, and share the image file in Slack.

Common Pitfalls and Solutions

Even with widespread platform support, there are common issues that trip up developers when using Mermaid in Markdown. Here are the most frequent problems and their solutions:

• Diagram not rendering, shows raw code instead. Ensure the language identifier is exactly mermaid (lowercase, no spaces). Some editors auto-capitalize it to Mermaid, which may not be recognized.
• Diagram renders on GitHub but not locally. Your local Markdown preview tool may not support Mermaid. Install a Mermaid preview extension for your editor, or use our web-based renderer.
• Different appearance across platforms. Each platform uses its own Mermaid version and theme configuration. If visual consistency is critical, render the diagram once and embed it as an image instead of relying on platform rendering.
• Diagram too large to render. Most platforms impose size limits on Mermaid blocks. If your diagram exceeds them, break it into smaller, focused diagrams. A good rule of thumb: if a diagram has more than 20-25 nodes, it should probably be split.
• Special characters breaking syntax. Characters like parentheses, brackets, and quotes in node labels can confuse the parser. Wrap the entire label in double quotes: A["Process (Step 1)"].
• Newlines in code blocks. Some Markdown processors strip or modify whitespace inside code blocks. If your diagram breaks when pasted, check that all newlines are preserved.

The Markdown + Mermaid Workflow

The most effective workflow for creating Mermaid diagrams in Markdown combines a fast preview tool with version-controlled documentation. Here is the recommended approach:

1. Draft in a live renderer. Use our Mermaid Diagram Renderer to iterate on your diagram with instant visual feedback. Try different layouts, node arrangements, and styling until you are satisfied.
2. Copy into your Markdown file. Wrap the final diagram code in a mermaid fenced code block and paste it into your document.
3. Add context. Write a brief text description before the diagram explaining what it shows. This helps readers who cannot see the rendered diagram and improves accessibility.
4. Commit and review. When the Markdown file is committed, diagram changes are visible in the diff. Reviewers can see exactly what changed in the diagram, just as they would for any code change.
5. Iterate. When the system changes, update the diagram text. No need to open a separate diagramming tool, re-export, and update image files.

This approach, where diagrams are text that lives alongside documentation, is why Mermaid has become the default choice for developer documentation. Combined with the Markdown Preview tool for editing your surrounding documentation, you have everything you need to create comprehensive, well-illustrated technical documents entirely in your browser.