DEV Community: Levi Liu

Embed Mermaid in Notion: The 4 Working Approaches in 2026

Levi Liu — Tue, 26 May 2026 10:38:23 +0000

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

Approach	Live updates	Theme control	Maintenance
1. Native `mermaid` code block	✅	❌	None
2. Static image upload	❌	✅	Manual re-upload
3. Public hot-linkable image	✅*	✅	Host the image
4. Live embed via `/embed`	✅	✅	Host the endpoint

* 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:

Render the diagram into your repo: diagrams/auth-flow.svg
Commit and push.
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:

You have more than ~10 diagrams across your Notion workspace and you're losing track of which ones are stale.
You want a theme that matches your company's docs site, not Mermaid's defaults.
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:

Paste your Mermaid source into the editor.
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.
Save & Share — generates a public URL with a 12-char token.
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.

Why Your GitHub README Diagrams Look Amateur (and the 4 Fixes That Take 10 Minutes)

Levi Liu — Wed, 20 May 2026 10:41:08 +0000

TL;DR
If your README diagrams look like every other open-source repo's, that's because they all use the same four defaults. Switching to theme: 'base' plus tuning four properties takes under ten minutes and produces a diagram that looks intentional. This is a follow-up to last week's SVG rendering deep-dive.

The four defaults that ruin your diagrams

Pastel pink/blue palette — the default theme is from a 2014 Bootstrap-era moodboard. It signals "I copy-pasted from the docs."
Curved edges (basis) — works for organic flows, terrible for technical diagrams. Lines that should be crisp end up wavy.
Default font — varies wildly by viewer. Looks fine in the GitHub editor preview, looks like Times New Roman in your CI artifact.
Hardcoded background — light theme on a dark page, or vice versa. The diagram becomes a rectangle.

Each takes one config change to fix.

Fix 1: Switch to base theme

%%{init: {'theme':'base'}}%%
flowchart LR
  A --> B --> C

base is the only theme that exposes themeVariables for full control.

Fix 2: Set six theme variables

%%{init: {
  'theme':'base',
  'themeVariables': {
    'primaryColor': '#1e293b',
    'primaryTextColor': '#f8fafc',
    'primaryBorderColor': '#475569',
    'lineColor': '#94a3b8',
    'fontFamily': 'system-ui, sans-serif',
    'fontSize': '14px'
  }
}}%%

Six variables. That's the entire customization surface you actually need. Mermaid exposes around fifty in total, but the ones above cover 90% of the visual identity of a diagram. Ignore the rest unless you have a specific reason.

Fix 3: Linear edges

%%{init: {'flowchart': {'curve': 'linear'}}}%%

For hierarchies, use step. For organic flows, keep basis. For everything else, linear.

Fix 4: Light/dark adaptive embed

<picture>
  <source media="(prefers-color-scheme: dark)" srcset="./diagrams/auth-flow-dark.svg">
  <img alt="Auth flow" src="./diagrams/auth-flow-light.svg">
</picture>

GitHub READMEs respect prefers-color-scheme. Ship two SVGs and let GitHub pick.

A small but important caveat: this only works for pre-rendered SVGs that you commit to the repo. Inline mermaid code blocks in your README can't use <picture> — they're rendered by GitHub's own Mermaid runtime at view time, with no hook for swapping based on theme. If you want adaptive diagrams in a README, you have to render to SVG first.

Putting all four together

Here's the minimum viable beautified README diagram, end to end:

---
config:
  theme: base
  themeVariables:
    primaryColor: '#1e293b'
    primaryTextColor: '#f8fafc'
    primaryBorderColor: '#475569'
    lineColor: '#94a3b8'
    fontFamily: 'system-ui, sans-serif'
    fontSize: '14px'
  flowchart:
    curve: linear
---
flowchart LR
  A[Client] --> B{Auth?}
  B -->|Yes| C[API]
  B -->|No| D[Login]
  C --> E[(Database)]

The frontmatter form (---\nconfig:\n ...) is Mermaid v11's preferred syntax. The older %%{init: {...}}%% directive still works and is what you'll see in most blog posts — pick whichever your renderer is happy with.

When DIY stops being worth the time

Everything above works. I've shipped this exact pipeline.

But the moment you have more than a handful of diagrams, or you want a different look for slides vs. docs vs. PRs, you're maintaining a config file. And every new contributor to the repo needs to know about it. That's where I personally tap out.

Three signals it's time to graduate from hand-tuned themes:

You're copy-pasting the same themeVariables block across multiple repos.
You want a different look for a slide deck than for the README, but the diagram source stays the same.
Someone non-technical on the team needs to make a diagram and you don't want to teach them YAML frontmatter.

The shortcut: Paste, pick a theme, export

Beauty Diagram is a web editor for Mermaid, PlantUML, and draw.io. Paste your source, pick from 9 production themes, export SVG or PNG. No themeVariables to maintain. (Disclosure: I work on it.)

→ Open the editor

The fastest path is the web editor:

Paste your Mermaid source on the left.
Pick a theme from nine: classic, modern, atlas, blueprint, memphis, obsidian, slate, brutalist, atelier. Each one is a complete design language — palette, typography, edge style, node treatment — not just a colour swap.
Export SVG (vector for repos) or PNG (standard / high / max quality for slides).
Share to get a public hot-linkable URL that updates when the source is edited — drop it into Notion or Linear without re-uploading.

The same renderer is also a CLI if you'd rather automate the README pipeline:

# Render once, ship to your repo
npx @beauty-diagram/cli beautify flow.mmd --theme modern --out flow.svg

# Or render light + dark in one go for the <picture> embed
npx @beauty-diagram/cli beautify flow.mmd --theme modern   --out flow-light.svg
npx @beauty-diagram/cli beautify flow.mmd --theme obsidian --out flow-dark.svg

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

Wrap-up

The README-diagram embarrassment problem is fixable in ten minutes. The four fixes, recapped:

theme: 'base' — only theme that accepts overrides.
Six themeVariables — primaryColor, primaryTextColor, primaryBorderColor, lineColor, fontFamily, fontSize.
flowchart.curve: linear — sharp edges for technical diagrams.
<picture> + prefers-color-scheme — adaptive light/dark, GitHub-native.

Most repos haven't done it because nobody told them where to look. Now you know.

If this was useful, drop a ❤️ and follow — I'm posting weekly on diagrams, docs, and developer ergonomics. Next week: how to embed Mermaid diagrams in Notion (the four working approaches in 2026).

What's the worst-looking diagram in a README you've actually opened a PR against? Drop a link in the comments — I'm collecting examples for a future post.

How to Render Mermaid Diagrams as SVG (and Stop Looking Like Every Other README)

Levi Liu — Sun, 10 May 2026 22:00:00 +0000

TL;DR
Mermaid renders to SVG natively — but the default output usually isn't what you want in a README, slide, or doc. This post walks through the official mmdc CLI, the four theming knobs that actually matter, the three rendering pitfalls everyone hits (fonts, viewBox, dark mode), and the fastest path when you don't want to fight with config. There's a live editor at the end if you want to skip ahead.

The problem nobody talks about

Mermaid is the de-facto "diagrams as code" choice in 2026 — GitHub, Notion, Obsidian, Docusaurus, GitLab, every static site generator worth its salt renders it natively.

That's the good news.

The bad news: 95% of Mermaid diagrams in the wild look exactly the same. Pastel pinks and blues, Comic-Sans-adjacent fonts, edges crossing nodes, arrowheads that don't quite point at anything. You've seen them. You've probably shipped some.

It's not a Mermaid problem — it's a defaults problem. The renderer is optimized for "something showed up", not "this is presentable".

Why SVG and not PNG

Property	SVG	PNG
Scales without blur	✅	❌
Accessible (text selectable)	✅	❌
Adapts to dark mode (`currentColor`)	✅	❌
Searchable in your repo	✅	❌

Approach 1: The official Mermaid CLI

# Run without installing
npx @mermaid-js/mermaid-cli -i diagram.mmd -o diagram.svg

# Or install globally
npm install -g @mermaid-js/mermaid-cli
mmdc -i diagram.mmd -o diagram.svg

The four theming knobs that actually matter

1. `theme` (the cheapest win)

Built-in Mermaid themes: default, forest, dark, neutral, base. Pick base if you want to customize from scratch.

2. `themeVariables`

Six variables actually matter: primaryColor, primaryTextColor, primaryBorderColor, lineColor, fontFamily, fontSize. Set those well, ignore the other 50.

3. Edge curves

Change edge curves from the default to linear or step. The default basis everywhere is one of the top reasons README diagrams look amateur.

4. Layout direction

Pick based on reading flow. LR for pipelines, TD for hierarchies.

Three rendering pitfalls

Fonts don't render in the saved SVG

Use a system font stack: -apple-system, BlinkMacSystemFont, "Segoe UI", system-ui, sans-serif.

viewBox cropping

Post-process to add padding:

function padViewBox(svgString, padding = 16) {
  return svgString.replace(
    /viewBox="(-?\d+\.?\d*) (-?\d+\.?\d*) (\d+\.?\d*) (\d+\.?\d*)"/,
    (_, x, y, w, h) => {
      const nx = parseFloat(x) - padding;
      const ny = parseFloat(y) - padding;
      const nw = parseFloat(w) + padding * 2;
      const nh = parseFloat(h) + padding * 2;
      return `viewBox="${nx} ${ny} ${nw} ${nh}"`;
    }
  );
}

Dark mode is hardcoded

Replace fixed colors with currentColor:

function makeAdaptive(svgString) {
  return svgString
    .replace(/stroke="#[0-9a-fA-F]{6}"/g, 'stroke="currentColor"')
    .replace(/fill="#[0-9a-fA-F]{6}"/g, 'fill="currentColor"');
}

When DIY stops being worth the time

Everything above works. I've shipped this exact pipeline.

It also takes about a day of fiddling to get right, and the result is one diagram style that you maintain forever. The moment you want a different style for a different context — a slide deck vs. a README vs. a postmortem — or someone non-technical on the team wants to make a diagram, the cost-benefit shifts.

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

You're maintaining a "diagram theme" file across multiple repos.
You want a different look for slides vs. docs vs. PRs, but the diagram source stays the same.
Your inputs aren't just Mermaid — PlantUML, draw.io, AI prompts.

The shortcut: Paste, pick a theme, export

Beauty Diagram is a web editor for Mermaid, PlantUML, and draw.io. Paste your source, pick from 9 production themes, export SVG or PNG. No config files. (Disclosure: I work on it.)

→ Open the editor

The fastest path is the web editor:

Paste your Mermaid source on the left.
Pick a theme from nine: classic, modern, atlas, blueprint, memphis, obsidian, slate, brutalist, atelier. Each is a complete design language — typography, palette, edge style, node treatment — tuned so the diagram reads as a finished asset, not a default render.
Export SVG (vector for docs / repos) or PNG (standard / high / max quality for slides and social).
Share to get a public hot-linkable URL with an OG preview — drop it into Notion or Linear and it stays live as you edit.

That's the whole loop. No themeVariables JSON to maintain. No post-processing scripts. The same renderer powers a CLI if you'd rather automate:

# Render once, ship to your repo
npx @beauty-diagram/cli beautify flow.mmd --theme modern --out flow.svg

# Export at higher quality for slides
npx @beauty-diagram/cli export flow.mmd --theme atlas --format png --quality max --out flow.png

# Get a public share URL (with OG preview baked in)
npx @beauty-diagram/cli share flow.mmd --theme modern --title "Auth flow"

Wrap-up

Mermaid's defaults aren't bad — they're designed for "the diagram exists" rather than "the diagram is finished". The fixes break down into roughly three tiers:

Cheap and fine for one style: switch theme: 'base', set six theme variables, change edge curves, run a viewBox-padding regex.
Annoying past one repo: maintain that config across many surfaces.
Use a tool: paste, pick, export.

Where you land depends on how much you care about diagrams and how often you ship them.

If this was useful, drop a ❤️ and follow — I'm posting weekly on diagrams, docs, and developer ergonomics. Next week: why your GitHub README diagrams look amateur, and the four fixes that take 10 minutes.

What's the worst Mermaid diagram you've shipped? Drop a screenshot in the comments — I'll write up the most common issues in a follow-up.

DEV Community: Levi Liu

Embed Mermaid in Notion: The 4 Working Approaches in 2026

Why this article exists

The four approaches at a glance

Approach 1: Native mermaid code block

Approach 2: Static image upload

Approach 3: Public hot-linkable image

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

When DIY stops being worth it

Picking the right approach for your page

Wrap-up

Why Your GitHub README Diagrams Look Amateur (and the 4 Fixes That Take 10 Minutes)

The four defaults that ruin your diagrams

Fix 1: Switch to base theme

Fix 2: Set six theme variables

Fix 3: Linear edges

Fix 4: Light/dark adaptive embed

Putting all four together

When DIY stops being worth the time

Wrap-up

How to Render Mermaid Diagrams as SVG (and Stop Looking Like Every Other README)

The problem nobody talks about

Why SVG and not PNG

Approach 1: The official Mermaid CLI

The four theming knobs that actually matter

1. theme (the cheapest win)

2. themeVariables

3. Edge curves

4. Layout direction

Three rendering pitfalls

Fonts don't render in the saved SVG

viewBox cropping

Dark mode is hardcoded

When DIY stops being worth the time

Wrap-up

Approach 1: Native `mermaid` code block

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

1. `theme` (the cheapest win)

2. `themeVariables`