5.2 Embedding Mermaid in Docs & Wikis

Using Mermaid in GitBook.
Embedding in GitHub README.
Using Mermaid with Notion or Obsidian.

1. Using Mermaid in GitBook

Once you’ve learned how to write clear Mermaid diagrams, you’ll probably want to embed them directly into your documentation. One of the best places to do this is GitBook — a popular tool for creating beautiful, shareable online docs and team knowledge bases.

The good news? GitBook has built-in support for Mermaid, so you don’t need any extra plugins — just write your diagrams in Markdown and GitBook does the rest.

✅ Why Use Mermaid in GitBook?

Keep diagrams close to your text — no more uploading static images every time something changes.
Update diagrams easily — edit the Mermaid code directly in GitBook’s editor.
Everything is version controlled — just like your Markdown content.
Diagrams render automatically in your published site, with no extra setup.

✅ How to Add Mermaid in GitBook Add a Code Block

When editing a GitBook page:

Click the + icon or type / to open the block menu.
Choose Code Block.
Change the language to mermaid.

Or just write it in Markdown:

```mermaid
graph TD
  A[Start] --> B[Do Something] --> C[End]
```

Write Your Mermaid Syntax

Inside the ```mermaid block, write your diagram just like you would anywhere else:

Flowcharts (graph TD)
Sequence diagrams (sequenceDiagram)
Class diagrams (classDiagram)
ERDs (erDiagram)

GitBook will automatically render it in the preview.

Save and Publish

When you publish or share your GitBook, your Mermaid diagrams are rendered as live, responsive visuals — no exporting PNGs or updating images by hand.

✅ Example in GitBook

Here’s a simple login flow you could paste directly into GitBook:

```mermaid
graph TD
  User[User] --> Auth[Auth Service]
  Auth --> DB[(Database)]
  DB --> Auth
  Auth -->|Valid| Success[Access Granted]
  Auth -->|Invalid| Fail[Access Denied]
```

✅ Tips for Using Mermaid in GitBook

✔️ Use code fences (```mermaid) to get proper rendering. ✔️ Keep your syntax tidy — if the diagram doesn’t render, double-check your braces and arrows. ✔️ Use themes and inline styles if you want to adjust how your diagram looks. ✔️ Test bigger diagrams in the Mermaid Live Editor first, then paste them into GitBook.

In short:

📌 GitBook + Mermaid is the perfect match for live, always up-to-date diagrams inside your docs — easy to write, easy to maintain, and no more static screenshots!

2. Embedding in GitHub README

Many developers want to include diagrams right inside their README.md files on GitHub. This keeps your documentation clear, up to date, and version-controlled — right next to your source code. The good news is: GitHub now has native support for Mermaid!

✅ Why Use Mermaid in a GitHub README?

No need to save and upload static images.
Diagrams stay editable — just update the text in your Markdown.
Anyone viewing your repo can see the diagram rendered automatically.
Diagrams stay versioned with your project — changes show up in diffs and pull requests.

✅ How to Embed Mermaid in a README

1️⃣ Add a Mermaid Code Block

In your README.md file (or any .md file in your repo), just use a fenced code block with mermaid:

```mermaid
graph TD
  Start[Start] --> Process[Do Work] --> End[Finish]
```

2️⃣ Commit and Push

When you push this Markdown file to GitHub, the web interface will automatically render the diagram inside your README page — no extra tools needed!

✅ Example: Simple Architecture Diagram

Here’s a common example you might put in a README.md:

```mermaid
graph LR
  User[User] --> API[API Server]
  API --> DB[(Database)]
  API --> Cache[(Cache)]
  DB --> Backup[(Backup Storage)]
```

This is perfect for:

Microservice overviews
System architecture sketches
Quick flow explanations for contributors

✅ What If It Doesn’t Render?

👉 Important: As of 2023–2024, GitHub supports Mermaid natively, but there may be cases where:

Some contexts (like old wikis or legacy Markdown processors) don’t support it yet.
The web preview works, but local Markdown renderers (like VS Code’s default preview) may not show it — test it with GitHub’s web UI to be sure!

✅ Pro Tips for GitHub

✔️ Keep diagrams small and clear — giant flowcharts can get cramped in a README. ✔️ If the diagram is big, consider putting it in a separate .md file (like docs/architecture.md) and linking to it from your README. ✔️ Test your Mermaid syntax in the Mermaid Live Editor before committing.

In short:

📌 Mermaid makes it easy to add live, version-controlled diagrams to your GitHub README — no more static screenshots, no more forgotten updates, just clear and always-current visuals.

3. Using Mermaid with Notion or Obsidian

Once you’re comfortable writing Mermaid diagrams, you’ll probably want to use them right inside your favorite note-taking or knowledge tools. Two of the most popular tools for developers, students, and knowledge workers are Notion and Obsidian — and both can work with Mermaid diagrams, though they handle it a bit differently.

✅ Using Mermaid in Obsidian

Obsidian is a powerful Markdown-based note-taking app — and one of its best features is built-in Mermaid support. You don’t need any plugins: Mermaid just works out of the box.

How to use Mermaid in Obsidian:

Create or open a Markdown note. Add a fenced code block with mermaid:

```mermaid
graph TD
  A[Start] --> B[Process] --> C[End]
```

3️⃣ Switch to Preview mode — your diagram renders instantly!

Why it’s great in Obsidian:

Diagrams live right next to your text notes.
They’re fully version-controlled in plain text.
Perfect for personal knowledge bases, study notes, or technical documentation.
Works offline — no internet required.

✅ 2️⃣ Using Mermaid in Notion

Notion does not currently have native Mermaid rendering — unlike Obsidian, it won’t automatically turn ```mermaid blocks into diagrams. But you can still embed Mermaid in Notion in a few practical ways:

Option 1: Export and Embed an Image

Write your diagram in the Mermaid Live Editor.
Export it as an SVG or PNG.
Drag and drop the image into your Notion page.
If the diagram changes, just update the image — not as seamless as Obsidian, but works well for static documentation.

Option 2: Use an Embed Link

Some people host Mermaid diagrams on sites like GitHub or GitBook.
Then use Notion’s Embed block (/embed) to insert a live link.
This shows your diagram in context and can update automatically if the source changes.

Option 3: Third-Party Widgets

Tools like Mermaid.ink or custom Notion widgets can sometimes render live Mermaid blocks.
These usually involve pasting an iframe embed.
Keep in mind: This can be more advanced and may require a free account or integration.

✅ Obsidian vs. Notion for Mermaid

Tool

Native Support

Best For

Obsidian

✅ Native Mermaid rendering

Daily notes, personal knowledge bases, offline writing

Notion

❌ No native rendering (image/embed workaround)

Team wikis, shared docs, pretty pages with static diagrams

✅ Pro Tips

✔️ Use Obsidian when you want to edit and update live Mermaid diagrams inside your Markdown notes. ✔️ Use Notion when you want clean, static documentation — just export diagrams as images or embed them from GitBook or GitHub. ✔️ Always keep your Mermaid source code (the text) somewhere safe — so you can update your diagrams later without redrawing them from scratch.

In short:

📌 Obsidian makes using Mermaid frictionless — type, preview, done. 📌 Notion works well for embedding static or linked diagrams, so your docs look polished and up to date. Either way, Mermaid helps you keep your visuals live, version-controlled, and easy to maintain.

Previous5.1 Styling & Integrations Next5.3 Tips, Best Practices & Resources

Last updated 5 months ago