How to Use Mermaid Diagrams in Obsidian

Introduction

Obsidian is one of the most popular knowledge management tools, and one of its best features is native Mermaid.js support. You don't need any plugins — Mermaid diagrams render directly in your notes out of the box.

This makes Obsidian an incredibly powerful tool for developers and knowledge workers who want to combine written notes with visual diagrams. In this guide, you'll learn everything about using Mermaid in Obsidian, from basic setup to advanced tips.

Enabling Mermaid in Obsidian

Great news: there's nothing to enable. Obsidian supports Mermaid natively since version 0.15. Simply create a code block with the mermaid language identifier, and Obsidian will render it automatically in Reading View and Live Preview.

If you're on an older version of Obsidian, update to the latest version to get Mermaid support. The latest versions of Obsidian typically ship with a recent version of Mermaid.js, giving you access to most diagram types.

Creating Your First Diagram

In any Obsidian note, type:

graph TD
    A[Idea] --> B[Research]
    B --> C[Draft]
    C --> D[Review]
    D --> E[Publish]

Switch to Reading View (or use Live Preview) and you'll see the diagram rendered inline with your notes. It's that simple.

Supported Diagram Types

Obsidian supports all major Mermaid diagram types:

• Flowcharts — Process flows, decision trees
• Sequence Diagrams — API calls, interactions
• Gantt Charts — Project timelines
• Class Diagrams — UML modeling
• State Diagrams — State machines, workflows
• ER Diagrams — Database schemas
• Pie Charts — Data distribution
• Mind Maps — Brainstorming, topic hierarchies
• Git Graphs — Branch visualization
• Timeline — Historical events, roadmaps

The exact feature support depends on which version of Mermaid is bundled with your Obsidian version.

Practical Examples for Obsidian Notes

Project Planning Note

Combine text and diagrams in a single note:

# Project Alpha — Planning

## Overview
Project Alpha aims to rebuild our authentication system with OAuth 2.0 support.

## Architecture

graph TB

subgraph Frontend

React[React App] --> AuthSDK[Auth SDK]

end

subgraph Backend

API[API Server] --> AuthService[Auth Service]

AuthService --> UserDB[(User DB)]

AuthService --> Redis[(Session Store)]

end

AuthSDK --> API

## Timeline

gantt

title Project Alpha Timeline

dateFormat YYYY-MM-DD

section Phase 1

Research & Design :a1, 2025-01-06, 10d

section Phase 2

Implementation :a2, after a1, 20d

section Phase 3

Testing & Launch :a3, after a2, 10d

Daily Notes with Diagrams

Add quick process diagrams to your daily notes:

sequenceDiagram
    participant Me
    participant PM
    participant Design

    Me->>PM: Proposed API changes
    PM->>Design: Request UI review
    Design-->>PM: Approved with changes
    PM-->>Me: Go ahead with modifications

Knowledge Base Entries

Document systems with ER diagrams:

erDiagram
    NOTE ||--o{ TAG : has
    NOTE ||--o{ LINK : links_to
    NOTE {
        string title
        text content
        date created
        date modified
    }
    TAG {
        string name
    }
    LINK {
        string source_id
        string target_id
    }

Tips for Mermaid in Obsidian

1. Use Live Preview

Obsidian's Live Preview mode renders Mermaid diagrams inline as you type. This gives you instant feedback without switching between edit and reading modes.

2. Keep Diagrams Small

Large Mermaid diagrams can slow down Obsidian's rendering, especially with many notes open. Aim for diagrams with fewer than 20-30 nodes. If you need a complex diagram, consider putting it in its own note and linking to it.

3. Use Obsidian Linking with Diagrams

While you can't make diagram nodes clickable links in Obsidian, you can place diagrams alongside [[wiki links]] to create a powerful combination of visual and textual navigation.

4. Theming

Obsidian applies its own CSS theme to Mermaid diagrams. If you're using a dark theme, diagrams will automatically adjust. However, if you use explicit colors in your Mermaid code (via classDef or style), make sure they work with both light and dark themes.

You can also use Mermaid's built-in theming:

%%{init: {'theme': 'dark'}}%%
graph TD
    A --> B --> C

5. CSS Snippets for Custom Styling

Obsidian allows CSS snippets that can style Mermaid diagrams. Create a CSS file in your vault's .obsidian/snippets/ folder:

.mermaid svg {
    max-width: 100%;
    font-family: var(--font-text);
}
.mermaid .node rect {
    rx: 8px;
    ry: 8px;
}

6. Templates

Create Obsidian templates with pre-built Mermaid diagrams. For example, a "Meeting Notes" template could include:

# Meeting: {{title}}
Date: {{date}}

## Action Items

graph LR

A[Action 1] --> B[Owner: TBD]

C[Action 2] --> D[Owner: TBD]

Obsidian Publish Compatibility

If you use Obsidian Publish to share your notes as a website, Mermaid diagrams are fully supported. They render on published pages just as they do in the app.

This makes it easy to create documentation sites with embedded diagrams — no extra build steps or plugins needed. Your readers see the same rendered diagrams you see in your vault.

Tips for Published Diagrams

- Test your diagrams in Reading View before publishing — what you see is what your readers get.

- Keep diagram complexity reasonable for mobile readers.

- Use descriptive text alongside diagrams since some readers may have rendering issues on older browsers.

Community Plugins

While native Mermaid support is sufficient for most use cases, there are community plugins that extend the experience:

• Mermaid Tools — Adds a toolbar for inserting Mermaid templates.
• Obsidian Enhancing Export — Exports notes with rendered Mermaid diagrams to PDF.
• Diagrams — Provides an alternative rendering engine with additional options.

Search for these in Obsidian's community plugin browser (Settings → Community Plugins → Browse).

Common Issues

Diagram Not Rendering

- Make sure you're using mermaid (lowercase) as the code fence language.

- Switch to Reading View or Live Preview — Source mode shows raw code.

- Check for syntax errors in your Mermaid code.

Diagram Looks Different Than Expected

- Obsidian may use a slightly different version of Mermaid than the latest release. Some newer features might not work.

- Your theme's CSS might affect colors and fonts. Try switching to a default theme to test.

Performance Issues

- Large diagrams (30+ nodes) can slow down rendering.

- Many diagrams on a single page can cause lag. Consider splitting into linked notes.

Best Practices

1. One diagram per concept. Don't try to show everything in one diagram.
2. Label your diagrams. Add a heading above each diagram explaining what it shows.
3. Use consistent notation. Pick a direction (TD or LR) and stick with it in your vault.
4. Keep the source readable. Even in code blocks, format your Mermaid code neatly with proper indentation.
5. Version your vault. Since Mermaid diagrams are plain text, they work perfectly with Git for version control.

Conclusion

Obsidian's native Mermaid support makes it one of the best environments for combining structured notes with visual diagrams. Whether you're documenting architectures, planning projects, or building a knowledge base, Mermaid diagrams add a powerful visual dimension to your notes — all without leaving your text editor.

Try creating Mermaid diagrams in our free online editor →