TL;DR
Notion has native Mermaid in code blocks now, but the default look is the same pastel render you've seen everywhere, and there's no theme override. This post walks through the four approaches that actually work in 2026 — native code block, static image upload, public hot-linkable image, and live-updating embed — with a comparison table at the end so you can pick by trade-off. There's a shortcut at the 70% mark if you'd rather skip the maintenance.

Why this article exists

Two years ago, "embed Mermaid in Notion" was a search query that returned twenty Stack Overflow threads and zero working answers. Then Notion shipped native mermaid code-block rendering, and the question went quiet.

But the question didn't go away — it shifted. The native renderer works, but it gives you exactly one look: Mermaid's default theme, no overrides, no themeVariables honored. The moment you want your team's Notion docs to feel like a finished product instead of a hackathon scratchpad, you're back to needing a workaround.

There are four of them. Each makes a different trade between live-updating, aesthetic control, and how much pipeline you're willing to maintain.

The four approaches at a glance

* Live updates only if the source URL serves a fresh render each time.

The rest of this post is just the details under each row.

Approach 1: Native mermaid code block

The cheapest path. Type /code, set the language to Mermaid, paste your source.

flowchart LR
  A[Client] --> B{Auth?}
  B -->|Yes| C[API]
  B -->|No| D[Login]

Notion renders it live. You can edit the source, the diagram re-renders. Free, zero pipeline.

What you give up:

• No theme override. The %%{init: {...}}%% directive is silently stripped in Notion's renderer. You get default Mermaid pastels whether you want them or not.
• No <picture> for dark mode. Notion's dark/light switch doesn't tell Mermaid anything; the diagram stays one fixed palette.
• No PDF export fidelity. When you export the Notion page to PDF, the Mermaid block renders as a raster snapshot, often at a lower resolution than the page expects.

Use this for: internal scratch docs, RFCs, anything where "the diagram exists" is the bar.

Don't use this for: public-facing docs, customer-shared Notion pages, anything you'd want to look intentional.

Approach 2: Static image upload

Render the diagram to SVG or PNG offline, then drag the file into Notion. It becomes an Image block; Notion hosts it on its own CDN.

# Official Mermaid CLI
npx @mermaid-js/mermaid-cli -i flow.mmd -o flow.svg -t base

Drag flow.svg into the Notion page. Done.

Pros: full theme control (you're rendering it yourself), works in PDF export, looks identical light and dark.

Cons: no live updates. Edit the Mermaid source, you re-render the file, you re-upload it. For a doc with five diagrams that change quarterly, this is fine. For a system architecture page that drifts weekly, it's a paper cut.

A subtle gotcha: Notion strips SVG <script> tags and external font references on upload. If your SVG depends on a webfont link in <defs>, the text falls back to Notion's default font. Inline the font with font-family: -apple-system, system-ui, sans-serif to avoid the mismatch.

Approach 3: Public hot-linkable image

Host the SVG somewhere public, then in Notion: /image → Embed link → paste the URL. Notion fetches it on every page load.

This is the sweet spot for repos that already commit their diagrams as SVG. The pattern:

1. Render the diagram into your repo: diagrams/auth-flow.svg
2. Commit and push.
3. In Notion, embed: https://github.com/<org>/<repo>/raw/main/diagrams/auth-flow.svg

Notion will fetch the URL each time the page loads. Push a new SVG to main, the embed updates within a few minutes (GitHub's raw CDN has a short TTL).

The catch: GitHub's raw.githubusercontent.com serves with Content-Type: text/plain, which some browsers refuse to render as an image. The reliable trick is to route through https://github.com/<org>/<repo>/raw/main/... (no raw. prefix), which redirects to a properly typed CDN response. Notion handles this redirect correctly.

Other hosts work too — Cloudflare R2, S3 with a public bucket, any static CDN. The constraint is just: serve image/svg+xml, allow Notion's user-agent, and don't gate behind auth.

Approach 4: Live embed via /embed + hosted SVG endpoint

The most flexible — and the most pipeline. Use Notion's /embed block (which accepts any URL) to point at an endpoint that renders the Mermaid source on demand.

/embed → https://your-domain.com/render?source=<encoded-mermaid>&theme=atlas

The endpoint does what Mermaid CLI does, but server-side, and returns image/svg+xml. You can pass theme parameters in the query string, regenerate on every request, and the diagram in Notion always reflects whatever the endpoint serves right now.

A barebones version in 50 lines of Node:

import express from "express";
import { run } from "@mermaid-js/mermaid-cli";
import fs from "fs/promises";

const app = express();

app.get("/render", async (req, res) => {
  const source = Buffer.from(req.query.source as string, "base64").toString("utf8");
  const tmpIn = `/tmp/${Date.now()}.mmd`;
  const tmpOut = tmpIn.replace(".mmd", ".svg");

  await fs.writeFile(tmpIn, source);
  await run(tmpIn, tmpOut, { puppeteerConfig: { args: ["--no-sandbox"] } });

  const svg = await fs.readFile(tmpOut, "utf8");
  res.type("image/svg+xml").send(svg);
});

app.listen(3000);

This is the "I want full control" path. You're now running a renderer. That means:

• A box (Lambda, Cloud Run, a Fly machine) running Chromium for Puppeteer
• A cache layer so identical sources don't re-render on every Notion poll
• A timeout policy so a malformed source doesn't hang
• Some auth or rate limiting so the endpoint doesn't become someone else's free render farm

For a team that already has infra, the 80% solution above is a weekend project. For a solo dev, it's the moment you ask whether the time is worth it.

When DIY stops being worth it

Three signals it's time to stop hand-rolling the Notion pipeline:

1. You have more than ~10 diagrams across your Notion workspace and you're losing track of which ones are stale.
2. You want a theme that matches your company's docs site, not Mermaid's defaults.
3. The team's non-engineers want to make and edit diagrams without learning Mermaid or your render endpoint.

The shortcut: Paste, pick a theme, embed

Beauty Diagram is a web editor for Mermaid, PlantUML, and draw.io. Paste your source, pick from 9 production themes, get a hot-linkable URL that updates when you edit. Drop the URL into Notion's /embed block and it stays live. (Disclosure: I work on it.)

→ Try the editor

The web flow for Notion specifically:

1. Paste your Mermaid source into the editor.
2. Pick a theme from nine: classic, modern, atlas, blueprint, memphis, obsidian, slate, brutalist, atelier. Each is a complete design language — palette, typography, edge style, node treatment — tuned so the embed reads as a finished asset.
3. Save & Share — generates a public URL with a 12-char token.
4. In Notion, /embed and paste the share URL's .svg form, e.g. https://api.beauty-diagram.com/v1/share/<token>.svg. The embed re-fetches on each page load; if you edit the share, Notion shows the new version within ~5 minutes.

If you'd rather automate from a CLI — say, a CI job that regenerates every diagram in your repo on each release — the same render pipeline is one command:

# Render and get a hot-linkable URL in one shot
npx @beauty-diagram/cli embed-url flow.mmd --theme atlas --share
# → https://api.beauty-diagram.com/v1/share/<token>.svg

bd embed-url --share saves the diagram first, then prints the share-resource SVG URL. Drop that URL directly into a Notion /embed block, or any other surface that accepts an image URL. Re-running on the same file replaces the share contents in place, so the URL is stable and the embed picks up the update automatically.

The CLI exposes the same nine themes (bd themes lists them). It does not expose per-property style overrides — the philosophy is that the theme is the choice; you don't tune a theme, you pick a different one.

Picking the right approach for your page

A rough decision tree:

• Throwaway internal doc? Native code block. Five seconds, zero pipeline.
• Quarterly architecture review that gets exported to PDF? Static SVG upload. Manual, but PDF-safe.
• Diagrams that already live in your repo? GitHub raw URL embed via /image. Free, auto-updates on push.
• Customer-facing Notion page, or a team doc that drifts weekly? Live embed against a hosted endpoint. Either roll your own, or use a service.

The trap to avoid: picking the most powerful approach for every diagram. Native code blocks are fine when "the diagram exists" is the bar — don't over-engineer them.

Wrap-up

The four approaches, recapped:

• Native mermaid code block — free, live, but locked to Mermaid defaults.
• Static image upload — full control, but no live updates.
• Public hot-linkable image — live and themed, but you host the SVG.
• Live embed via /embed — full pipeline, full control, the most work.

If this was useful, drop a ❤️ and follow — I'm posting weekly on diagrams, docs, and developer ergonomics. Next week: Mermaid vs PlantUML in 2026 — which to pick for engineering docs.

What's your team's Notion diagram setup — native blocks, static uploads, or something else? Drop a note in the comments; I'm collecting setups for a follow-up.