DEV Community: Levi Liu

Adding Beautiful Diagrams to Your Docusaurus / VitePress Site

Levi Liu — Sat, 11 Jul 2026 09:21:45 +0000

TL;DR
Docusaurus and VitePress both render Mermaid, but the defaults ship the same washed-out pastel diagrams as everyone else's docs. The 10-minute fix is enabling the built-in Mermaid support; the 30-minute fix is picking a theme once at the renderer instead of pasting %%{init}%% into every block. This post walks both — plugin install, theme config, and the moment it's worth swapping the renderer entirely for a hosted embed URL.

The doc site tax on Mermaid diagrams

You picked Docusaurus or VitePress because you wanted a doc site that looked considered. Sans-serif that isn't Times New Roman. A sidebar that respects your section hierarchy. Code blocks with a syntax highlighter that isn't from 2012.

Then you dropped in your first Mermaid diagram and the doc suddenly looked like every other Mermaid-in-docs page on the internet. Pale blue nodes on white. Thin grey edges. A font that doesn't match anything else on the page. The diagram is technically there, but visually it reads as a screenshot from a different site someone pasted in.

That's the doc-site tax on Mermaid. The renderer is shared across every project that ships the default config, so every doc site looks the same. This post is how to get out of that shared bucket without leaving Mermaid.

The path a Mermaid block takes from your repo to the reader. Every stage after "Markdown" is somewhere you can influence the visual — most people only ever touch the first one.

Where the rendering actually happens

Both Docusaurus and VitePress bundle a client-side Mermaid runtime. When the doc site builds, fenced mermaid blocks stay as source text in the generated HTML; a small JS bundle on the page finds them at load time and calls mermaid.render() to swap the source for an inline SVG.

This matters because the theme decision runs at three different altitudes, and the trick is knowing which one applies:

In the source — a %%{init}%% block at the top of one Mermaid block, applied to that block only.
In the site config — one Mermaid config passed to the doc-site plugin, applied to every block.
Outside the renderer entirely — pre-render each diagram to SVG and embed the image, bypassing the client Mermaid bundle.

Each altitude trades off different things: reach, consistency, and how much control you have over the styling. I'll walk all three.

Where the Mermaid render happens in a doc site. The theme decision can land at any of these steps; the higher up you push it, the more it applies to.

Path 1: enable Mermaid, accept defaults

Both frameworks make the enable-Mermaid step short. This is the ten-minute baseline every subsequent choice builds on.

Docusaurus

Install the official Mermaid theme:

npm install @docusaurus/theme-mermaid

In docusaurus.config.js, enable it and switch on the Markdown flag:

export default {
  markdown: {
    mermaid: true,
  },
  themes: ['@docusaurus/theme-mermaid'],
};

That's it. Every mermaid block in your MDX files now renders. Docusaurus ships this as a first-party theme, so there's no third-party plugin to babysit through major version bumps.

VitePress

VitePress doesn't ship Mermaid built in, but the community plugin has been stable for years. Install it:

npm install -D vitepress-plugin-mermaid mermaid

In .vitepress/config.ts, wrap your existing config with withMermaid:

import { withMermaid } from "vitepress-plugin-mermaid";

export default withMermaid({
  // your existing vitepress config...
  title: "My Docs",
  description: "…",
  mermaid: {
    // mermaid config goes here — leave empty for defaults
  },
});

The mermaid key is where every theme decision at the site-config altitude lives. Empty object = Mermaid's default look, which is the same pastel you're trying to escape from. Which brings us to path 2.

Path 2: keep Mermaid, pick a theme once

Mermaid has five built-in themes: default, neutral, dark, forest, and base. The first four are pre-set palettes; base is the one you use as a foundation when you want to override individual variables.

Two ways to apply them.

The site-config way (the one you actually want)

Docusaurus takes a themeConfig.mermaid object with two useful keys:

export default {
  markdown: { mermaid: true },
  themes: ['@docusaurus/theme-mermaid'],
  themeConfig: {
    mermaid: {
      theme: { light: 'neutral', dark: 'dark' },
    },
  },
};

theme accepts light/dark variants matched to the site's colour mode. neutral is a good pick if the default pastel bothers you but you don't want to design a palette yourself — it's monochrome, so it never fights the site's brand.

VitePress takes the same options nested under the mermaid key of the withMermaid wrapper:

export default withMermaid({
  mermaid: {
    theme: 'forest',
    themeVariables: {
      primaryColor: '#f8fafc',
      primaryTextColor: '#1e293b',
      primaryBorderColor: '#cbd5e1',
      lineColor: '#64748b',
      fontFamily: 'ui-sans-serif, system-ui, sans-serif',
    },
  },
});

Note: VitePress forces the dark Mermaid theme in dark mode regardless of what you set here — this comes from the plugin, not your config. If you need site-config dark control, use per-page mermaidTheme: frontmatter (see below) as an override.

For both, if you want an actually opinionated look, use theme: 'base' and set themeVariables. That combination is the escape hatch: base disables Mermaid's bundled palettes so your variable overrides stop being silently no-op'd. The five variables that carry 80% of the aesthetic are primaryColor, primaryTextColor, primaryBorderColor, lineColor, and fontFamily.

The per-block way (avoid if you can)

You can also drop %%{init}%% at the top of a single block:

%%{init: { "theme": "base", "themeVariables": { "primaryColor": "#f1f5f9" } }}%%
flowchart LR
  A[Request] --> B[Handler] --> C[Response]

VitePress additionally supports per-page overrides via frontmatter:

---
mermaidTheme: forest
title: Auth architecture
---

Per-block init is fine for one diagram that needs to look different — an on-call runbook that should read as an alert, a post-mortem where you want a warmer palette. It's a trap when you use it as the default styling mechanism. Every new block needs the same prelude pasted in. Six months later, half the diagrams have the prelude and half don't, and the ones that don't render as the pastel you were trying to get rid of.

The rule I use: if the styling belongs on more than one block, it belongs in the site config. Only reach for %%{init}%% for the diagram that's genuinely different.

The scaling ceiling for path 2

Path 2 gets you a long way. For most doc sites, "pick neutral and set a font family" is enough — the diagrams stop looking generic, they match the site's typography, and you don't have to think about it again.

Three signals it's not enough:

You want the same diagrams rendered consistently across your doc site, the project README on GitHub, and social share previews. Mermaid's site config only reaches diagrams inside your Docusaurus/VitePress site. GitHub uses its own hardcoded Mermaid theme; social preview crawlers don't run the Mermaid bundle at all.
You need control over layout, not just palette. Mermaid's theme variables let you change colours and fonts. Node shape, edge routing style, spacing between subgraphs, marker size — those are the layout engine's job, and the built-in themes don't expose them.
You want the doc-site build to stay fast. The Mermaid runtime bundle isn't tiny; on a docs page with a dozen fenced blocks, the JS parse + client render is measurable in the Lighthouse "unused JavaScript" panel.

When any of those apply, path 3 is worth twenty minutes of setup.

Three altitudes for the theme decision. The right one is whichever matches how many diagrams the choice needs to reach.

Path 3: swap the renderer, embed the SVG

The idea: stop asking the doc site's Mermaid runtime to render at all. Pre-render each diagram to SVG somewhere else, then reference the URL as a regular <img src>. The doc site treats it as any other image — no bundle weight, no theme inheritance, no client parse.

The Web UI is where I'd start. Paste a Mermaid block into the Beauty Diagram editor, cycle through the nine production themes — classic, modern, atlas, blueprint, memphis, obsidian, slate, brutalist, atelier — and pick the one that fits the doc's mood. Save the share; the resulting URL is a hotlinkable SVG that renders in any Markdown or MDX file. (Disclosure: I work on Beauty Diagram.)

For power users and CI setups, the CLI has an embed-url command that skips the browser:

npx @beauty-diagram/cli embed-url auth-flow.mmd --theme atelier
# → https://www.beauty-diagram.com/s/abc123.svg

In a Docusaurus or VitePress markdown file, that URL becomes:

![Auth flow](https://www.beauty-diagram.com/s/abc123.svg)

The image renders inline; the doc site's Mermaid bundle doesn't need to run for this block; the render is deterministic from the source; and the same URL works on GitHub, in Notion, in a social preview crawl. One fewer thing depending on the doc site's runtime.

The embed-URL flow. The renderer is the CLI; the doc site is just serving an image.

Two examples of what the themes look like on the same five-node flow:

Blueprint. For engineering deep-dives where the diagram should read as a schematic.

Atelier. For product docs and launch pages where you want the diagram to sit next to prose without shouting.

Same source, different renderer, no mermaid fenced block on the page at all. The doc site's job shrinks to "serve markdown with an image tag".

When each path is right

Signal	Path 1 (defaults)	Path 2 (site config)	Path 3 (embed URL)
One-off internal wiki	✅
Team doc site with a design language		✅
Diagrams shared to README + Notion + docs			✅
Care about bundle size on doc pages			✅
Want per-diagram layout control			✅
Prefer everything as code in the repo	✅	✅

The paths aren't exclusive. In practice I use path 2 for 90% of blocks (neutral theme, one font-family override) and path 3 for the 10% that need to travel outside the doc site — the architecture diagram that's referenced from the README, the sequence diagram that shows up in a launch tweet, the flow chart that gets pasted into a Notion doc for the ops team.

The way to know you're using path 2 well: you haven't touched the Mermaid config in six months and the diagrams still look intentional. The way to know you need path 3: you've started drafting the same diagram twice — once in the doc site, once as a rendered PNG for the README.

Going further: pick one theme; every Mermaid block re-renders through it

Beauty Diagram is what I use as the renderer when I want a Mermaid block to render consistently across the doc site, the README, and Notion — paste source into the web editor, cycle through nine production themes, then keep the same theme via a hotlinkable SVG URL or the CLI. (Disclosure: I work on it.)

→ Try the editor

Wrap-up

Three takeaways:

Enabling Mermaid in Docusaurus or VitePress is the ten-minute step, not the win. The default look is what everyone else's doc site ships. Pick a theme in the site config — even neutral is better than the default pastel.
Push the theme decision as high as it will go. Per-block %%{init}%% is fine for exceptions; the default styling belongs in themeConfig.mermaid (Docusaurus) or the mermaid key of withMermaid (VitePress). One place to change; every block picks it up.
When the diagram needs to leave the doc site — README, Notion, social — swap the renderer entirely. A hotlinkable SVG URL doesn't care what site is embedding it, and the doc-site build stays lean.

The shortest path through this post: enable, theme once, resist the %%{init}%% prelude, ship.

If this was useful, drop a ❤️ and follow — I'm posting weekly on diagrams, docs, and developer ergonomics. Next week: Convert draw.io Files to Production-Ready SVG (Without the Default Look).

What's the ugliest default Mermaid diagram currently sitting in a doc site you own? I'm curious whether the pastel-on-white default is universally hated or whether some people actually pick it on purpose.

10 Mermaid Tricks I Wish I'd Known Before Drawing 200 Diagrams

Levi Liu — Mon, 29 Jun 2026 18:07:27 +0000

TL;DR
Most people learn Mermaid by copy-pasting a flowchart from a tutorial, tweaking it once, and then never going further. The next ten tricks — subgraph zones, classDef inheritance, edge label markdown, init theme variables, click handlers — are the ones that took me from "Mermaid works" to "Mermaid actually communicates something". Every one of them is a vanilla Mermaid feature; no plugins, no forks.

How I got here

I've shipped somewhere north of 200 Mermaid diagrams into READMEs, design docs, runbooks, and onboarding decks over the last two years. The first 50 were flowchart LR and four nodes. The next 100 were the same thing in slightly different colours.

The last 50 were different — same syntax, but the diagrams stopped being placeholder visuals and started being something a reader could navigate without three paragraphs of caption underneath. The difference wasn't a new tool. It was a handful of Mermaid features I'd seen in the docs, skipped past, and only came back to when I got tired of the same flowchart LR look.

This post is those features. Each one ends with the code I actually paste into doc PRs.

The shape of the rest of this post. Three groups; ten tricks; pick the three that apply to whatever fenced block is in front of you today.

1. Comments with `%%` (yes, inside the diagram)

The first time I saw a colleague's flowchart with leading lines like %% retry path lives in worker.ts, I thought they'd broken the syntax. They hadn't — Mermaid treats %% as a single-line comment anywhere in the source.

flowchart LR
  %% Source: docs/architecture/auth.md §3
  U[User] --> A[Auth]
  A --> S[Session]
  %% Session expiry policy: 30d sliding window
  S --> P[Profile]

It's invisible in the rendered output, but if you're using Mermaid as documentation in a long-lived repo, comments are the difference between a diagram a future maintainer can update and a diagram they rewrite from scratch.

2. Edge labels carry weight — use them

The default way to label an edge is A -- text --> B. You'll see this in every tutorial. What the tutorials skip: edge labels accept Mermaid's full text styling, including <br/> for line breaks and inline backticks for code voice.

flowchart LR
  R[Request] -- "validate<br/>(zod)" --> H[Handler]
  H -- "200 OK<br/>+ session" --> C[Client]
  H -- "4xx<br/>+ error code" --> C

The trick: when a flow has two edges between the same pair of nodes (happy path + error path), labels with the response shape make the diagram readable without a separate legend.

3. `linkStyle` for per-edge visual hierarchy

Every edge in a default flowchart looks the same. That works for three nodes. It stops working at six, where the reader can't tell which path is the main one.

linkStyle indexes into the edges in declaration order (0-based) and lets you re-style any of them:

flowchart LR
  R[Request] --> V{Valid?}
  V -- yes --> H[Handler]
  V -- no --> E[Reject 400]
  H --> S[(Storage)]
  S --> O[Response]
  linkStyle 0,2,4,5 stroke:#2563eb,stroke-width:2.5px
  linkStyle 3 stroke:#ef4444,stroke-width:1.5px,stroke-dasharray:4

The happy path now reads as one continuous thread; the error path falls back as a dashed crimson aside. The reader's eye routes itself.

4. Per-node `style` for the one node that matters

style <id> <css> styles one node directly. Most useful for the node a diagram is really about:

flowchart LR
  A[Plan] --> B[Build] --> C[Test] --> D[Ship]
  style D fill:#16a34a,stroke:#14532d,color:#fff,stroke-width:2px

Don't style every node. The whole point of a per-node style is that it's an exception — the reader's eye lands on it because it doesn't match the rest.

5. `classDef` + `class` — styling that scales

Once you have three nodes that should share a style, style per node gets repetitive. classDef is the Mermaid way to define a reusable style and apply it by class:

flowchart LR
  R[Request] --> A[Auth]
  A --> S[Session]
  S --> H[Handler]
  H --> D[(Database)]

  classDef external fill:#e0f2fe,stroke:#0369a1,color:#0c4a6e;
  classDef storage  fill:#fef3c7,stroke:#a16207,color:#78350f;

  class R external
  class D storage

Two lines of classDef, two class assignments, and the diagram now teaches the reader where each component lives (external surface vs persistent storage) without a single label change.

6. classDef inheritance: stack multiple classes on one node

This one took me a year to find in the docs. class accepts multiple class names, comma-separated, and Mermaid merges them in declaration order — later classes win on conflicts. So you can layer role (external / internal / storage) onto state (healthy / degraded / down) without writing six combined classes:

flowchart LR
  A[Auth] --> S[Session]
  S --> D[(DB)]

  classDef storage fill:#fef3c7,stroke:#a16207;
  classDef degraded stroke:#dc2626,stroke-width:3px,stroke-dasharray:4;

  class D storage,degraded

The DB node renders with the storage fill (from storage) and the degraded stroke (from degraded). Adding a "down" state is one more classDef plus a comma in the right class line — no exponential blowup.

7. Subgraphs as zones, not boxes

Most diagrams use subgraph as a way to draw a box around three nodes. It's worth more than that. Subgraphs accept their own direction, their own classDef, and their own internal layout — which means you can use them to split a diagram into zones the reader navigates one at a time:

flowchart LR
  subgraph Edge[Edge]
    R[Request] --> V[Validator]
  end
  subgraph Core[Core service]
    V --> H[Handler]
    H --> Q[Queue]
  end
  subgraph Async[Async workers]
    Q --> W[Worker]
    W --> S[(Storage)]
  end

  classDef zone fill:#f8fafc,stroke:#cbd5e1,stroke-dasharray:6,color:#475569;
  class Edge,Core,Async zone

The subgraph title becomes a section header. The dashed border tells the reader "this is a zone, not a node." And because Mermaid lays out edges across subgraph boundaries, you get a flow that reads top-to-bottom and side-by-side.

The same set of nodes you'd draw flat, but grouped into "where does this code live" zones. The reader can scan the boundaries before they read the edges.

8. Click handlers — Mermaid as navigation

This is the trick that turned my docs from static images into navigation surfaces. click <id> <url> "<tooltip>" makes a node clickable in any Mermaid renderer that supports it (GitHub does, Notion partially, doc sites like Docusaurus and VitePress all do):

flowchart LR
  R[Request] --> A[Auth] --> S[Session] --> H[Handler]

  click A "https://github.com/acme/api/blob/main/src/auth.ts" "src/auth.ts"
  click S "https://github.com/acme/api/blob/main/src/session.ts" "src/session.ts"
  click H "https://github.com/acme/api/blob/main/src/handler.ts" "src/handler.ts"

In a README rendered on GitHub, every node in that diagram is a link to the file it represents. The architecture diagram becomes the index for new contributors — they can scan the shape, then click straight into the code.

Tooltips alone (no URL) are also legal: click NodeId "Tooltip text".

9. Theme variables via `%%{init}%%` — when you don't want the defaults but don't want a tool

You can adjust Mermaid's theme inline at the top of any diagram block. The full set of variables is documented in the Mermaid theming reference, but for most flows you only need 4 or 5:

%%{init: {
  "theme": "base",
  "themeVariables": {
    "primaryColor": "#1e293b",
    "primaryTextColor": "#f1f5f9",
    "primaryBorderColor": "#334155",
    "lineColor": "#64748b",
    "fontFamily": "ui-sans-serif, system-ui, sans-serif"
  }
}}%%
flowchart LR
  R[Request] --> H[Handler] --> D[(Database)]

theme: base is the magic word — it disables Mermaid's bundled palettes so your variables actually take effect. Without it, Mermaid keeps applying its default theme on top of your overrides and most of them silently no-op.

The trade-off: every Mermaid block in the same doc needs its own init prelude (they don't inherit), and the prelude doesn't carry across rendering surfaces. Which is the cleanest segue I can give into trick 10.

10. Pick a theme once at the renderer, not per-block

Eight tricks in, you have a lot of options for in-block styling. The opposite move is to stop styling in the block at all, and pick one theme at the rendering layer — so every fenced mermaid block in your repo (or your vault, or your doc site) renders consistently without a per-block init prelude.

Three open-source ways to do this:

GitHub READMEs: limited — GitHub forces its own Mermaid theme. The escape hatch is to ship rendered SVGs alongside the source (covered in the docs CLI post).
Docusaurus / VitePress: their Mermaid integrations both accept a theme config; set it once in the site config and every block picks it up.
Local preview (Obsidian, VS Code, Cursor): the editor's bundled Mermaid renderer ships one theme. Switching it is plugin territory (covered in the in-editor post).

What this trick really is: a reminder that the more you push into per-block init blocks, the harder your diagrams are to re-theme as a set. If you find yourself pasting the same %%{init}%% line into every block, the theme belongs at the renderer.

When the renderer is the right place to fix it: Pick one theme; every Mermaid block re-renders through it

Beauty Diagram is what I use as the renderer layer when I want consistent Mermaid output across the canonical doc, the embed, and the editor preview — paste source into the web editor, cycle through nine production themes, then keep the same theme via the Obsidian plugin, the VS Code extension, or the CLI for doc repos. The themes are the only knob; you pick a different one rather than tuning the current one. (Disclosure: I work on it.)

→ Try the editor

The Web editor is the fastest way to feel the difference — paste a Mermaid block, click through classic, modern, atlas, blueprint, memphis, obsidian, slate, brutalist, atelier, save the one that fits the doc. For repo-wide consistency, the CLI is a one-liner:

npx @beauty-diagram/cli beautify diagram.mmd --theme blueprint --out diagram.svg

Classic. The "neutral office doc" baseline — fine for most internal docs, deliberately quiet.

Blueprint. For engineering deep-dives where you want the diagram to read as a schematic.

Memphis. For docs that aren't trying to look corporate — blog posts, launch announcements, post-mortems with personality.

Same source, three rendering choices. The trick isn't the styling; it's that the source stayed identical and the renderer absorbed the visual decision.

When the open-source tricks are enough

Most of the time they are. If a single doc has one or two Mermaid blocks, learning classDef, linkStyle, and the init prelude is faster than picking up any external tool. Use the ten tricks above, ship the diagram, move on.

The three signals it's worth graduating to a renderer pick (trick 10):

You're pasting the same %%{init}%% prelude into ten or more blocks. That's a renderer config waiting to happen.
The diagram needs to live somewhere the surface controls the theme — GitHub README, Notion embed, doc site. Per-block init doesn't apply; renderer-level theming does.
Multiple contributors are editing the same diagrams. Per-block init is fragile under copy-paste; renderer config is set once.

Wrap-up

Three things to take away:

Mermaid has more in-syntax features than the tutorials cover. Comments, classDef inheritance, click handlers, init themes — all stock, all worth two minutes to learn.
Style only the things that carry meaning. Per-edge linkStyle, per-node style, zoned subgraphs — each one earns its keep by routing the reader's attention; default-everywhere is the failure mode.
When you're pasting the same style preamble into every block, the renderer is the right place to fix it. Per-block init is the open-source baseline; renderer-level theme picking is the next step up.

The shortest path through the post: read once, apply 3 tricks to the diagram you're touching today, don't re-do this exercise on the same file later.

If this was useful, drop a ❤️ and follow — I'm posting weekly on diagrams, docs, and developer ergonomics. Next week: Adding Beautiful Diagrams to Your Docusaurus / VitePress Site.

Of these ten, which one did you already know but never use? I'm curious whether classDef inheritance is rare-but-loved or just rare.

Beautify Mermaid Diagrams in Obsidian and VS Code (Without Leaving Your Editor)

Levi Liu — Tue, 23 Jun 2026 15:00:18 +0000

TL;DR
Mermaid is great until you preview it in the editor you actually write in. Obsidian and VS Code (plus Cursor / Windsurf / VSCodium) all ship a default pastel renderer that fights the rest of your note or doc. This post walks the two install paths — Obsidian community plugin and VS Code Marketplace — shows the in-place "pick a theme, preview re-renders" loop in each, and covers the per-file front-matter knobs (bd-share, bd-width) that control output without leaving the editor.

The "almost good enough" preview problem

You're in Obsidian writing an architecture note. Or you're in VS Code drafting a doc PR. You paste a Mermaid block — flowchart LR and four nodes — toggle preview, and the diagram appears. Functional. Readable. Off-key.

The default Mermaid renderer in both surfaces ships with the same pastel palette, the same flat edges, and the same uniform stroke weight that every other tool ships. In a polished note about your auth system, the diagram reads like a placeholder. The thing you were trying to communicate clearly is now the one element on the page that looks unfinished.

The fix most people try first: keep editing the source in their editor, then round-trip through a web renderer for the screenshot, paste the image back, repeat on every change. The diagram stops drifting visually, but the source of truth fragments — your .md file has Mermaid syntax that no longer matches the embedded image, and every edit becomes a 90-second context switch.

The cleaner fix is keep the source in the editor, and put a themed renderer in the same pane. That's what this post is about.

The in-editor loop. Source stays put; the preview pane is where the styling happens; saving the note or committing the file captures the themed output without a separate export step.

Why the default Mermaid theme falls flat

Before going into the plugins, it's worth being concrete about what "off-key" means — because if the only thing wrong with the default were "I don't like the colours", a CSS tweak would solve it.

Three things compound:

One theme across every diagram type. Mermaid's defaults apply the same palette to flowcharts, sequence diagrams, ER diagrams, state machines, and Gantt charts. A palette tuned for one is rarely tuned for all five.
No visual hierarchy on edges. Every edge is the same stroke weight and the same colour. In a flow where some edges are "happy path" and some are "error / retry", the reader has to decode that from labels alone.
Defaults read as defaults. Once a reader has seen the pastel-Mermaid look on three other sites that day, your diagram inherits whatever credibility (or lack of it) those other diagrams left behind.

Here's the same four-node flow rendered four ways — the first is roughly what Mermaid's default gives you; the next three are themes you'd pick instead:

The "looks like every other README" baseline. Functional, but doesn't carry weight.

Blueprint — for engineering notes where you want the diagram to read as a schematic, not a sketch.

Obsidian — drops cleanly into a dark vault without re-tinting half the note around it.

Atelier — when the note is closer to writing than to engineering documentation, and you want the diagram to match that voice.

Same source. The plugin's job is to make picking between these a one-click choice inside the editor you're already in.

Path 1 — Obsidian: install from Community Plugins

Obsidian's plugin model is the cleaner of the two. Install once, the renderer takes over every fenced mermaid block in every note in every vault that has it enabled.

The flow:

Obsidian → Settings → Community plugins → Browse.
Search for "Beauty Diagram".
Click Install, then Enable.

The plugin registers itself as a markdown post-processor for mermaid code blocks. On any note with reading view (or live preview) open, fenced Mermaid blocks now render through the themed pipeline instead of Obsidian's bundled mermaid.js.

Picking a theme inside the vault

Open the plugin's settings tab (Settings → Community plugins → Beauty Diagram → ⚙️). The theme picker shows the full set of production themes: classic, modern, atlas, blueprint, memphis, obsidian, slate, brutalist, atelier. Pick one; every open Mermaid preview re-renders within a second.

The choice is per-vault, not per-note. Your "engineering work" vault can pin Blueprint; your "personal writing" vault can pin Atelier; both behave independently.

Per-note overrides via front-matter

When one note in a vault needs a different treatment — say, you're drafting a doc for an external repo whose docs site uses a different theme — you can override at the file level via YAML front-matter:

---
title: Auth handoff flow
bd-theme: blueprint
bd-share: true
bd-width: 720
---

Three knobs to know:

bd-theme picks one of the production themes for this single note. Wins over the vault default.
bd-share: true (Obsidian plugin 0.1.4+) generates a hosted share URL alongside the in-vault preview, so you can drop the same diagram into a Slack thread or a GitHub comment without re-exporting. The URL appears in the preview footer; click to copy.
bd-width: 720 clamps the rendered diagram's max width. Useful in vaults with narrow note widths (or for diagrams you intend to paste into a fixed-width target). Defaults to the source's natural width.

The keys live in the note's front-matter so contributors editing the note in any markdown tool see them; they're inert outside the plugin.

Path 2 — VS Code (and Cursor / Windsurf / VSCodium): install from Marketplace

The VS Code extension covers more editors than the name suggests. The same VSIX runs in:

VS Code — official Marketplace install.
Cursor — same Marketplace; Cursor's extension panel reads from VS Code's registry.
Windsurf — same Marketplace via Open VSX.
VSCodium — install the VSIX directly (Open VSX or download from the Marketplace listing).

The install:

View → Extensions (or Cmd-Shift-X / Ctrl-Shift-X).
Search "Beauty Diagram".
Install.

The extension hooks the built-in markdown preview. Open any .md file, hit Preview to the Side (Cmd-K V), and Mermaid blocks in that file render through the themed pipeline. No restart, no settings.json edit.

Picking a theme without leaving the file

The extension contributes a status bar item — Beauty Diagram: <current theme> — at the bottom-right of the editor when a markdown file with Mermaid blocks is active. Click it, the command palette opens with all 9 themes listed, pick one, the preview re-renders.

The choice persists per workspace (in .vscode/settings.json under beautyDiagram.theme), so your team can commit a workspace theme alongside the docs and everyone's previews match.

Per-file front-matter overrides

Same shape as Obsidian, same keys:

---
bd-theme: modern
bd-share: true
bd-width: 960
---

The Mermaid block below the front-matter is unchanged — any fenced mermaid block in the same file picks up these settings.

bd-theme overrides the workspace setting for this single file.
bd-share: true (VS Code extension 0.1.19+) renders the same hosted share link the Obsidian plugin does. Status bar shows a copyable URL once the preview renders.
bd-width: 960 clamps the rendered width — handy when the doc will be embedded in a site with a known content column.

bd-width landed in the same release (0.1.19) on the VS Code side and 0.1.4 on the Obsidian side. If you're on an older build, the front-matter key is ignored — upgrade via the extension panel / community plugins screen.

The "no round-trip" loop, end to end

The reason both plugins matter together is that the writing loop collapses to:

Type Mermaid in your editor.
Toggle preview.
Cycle themes via the command palette / settings tab until the diagram fits the note.
Save / commit.

No browser tab. No "paste source into a web renderer, screenshot, drag image back, delete source, repeat on next edit." The source stays canonical; the preview is the design surface.

For diagrams that DO need to live outside the vault — a doc embed, a Slack post, a comment on a PR — bd-share: true produces a hot-linkable URL that updates when you edit the source. Same loop, one extra opt-in field per file.

Two install paths, same renderer: beautify Mermaid in the editor you already use

Beauty Diagram ships an Obsidian community plugin and a VS Code Marketplace extension (also works in Cursor, Windsurf, and VSCodium). Pick a theme inside the editor, render every fenced Mermaid block through it, and use the front-matter knobs when one note needs to break ranks. (Disclosure: I work on it.)

→ See the Obsidian plugin

If your daily writing surface is VS Code rather than Obsidian, the VS Code extension landing has the same install walkthrough and a feature matrix specific to that ecosystem (workspace settings, status-bar control, multi-root behaviour).

When the in-editor path isn't the right path

A few cases where you'll want to skip the plugins and stay with the open-source baseline:

Your team requires a sandboxed plugin policy. Some orgs lock down Obsidian community plugins entirely (or whitelist a small set). Submit a security review or stay with the bundled mermaid.js + an init directive for a hand-tuned theme.
You're rendering Mermaid in a context the editor can't reach. A CI step, a hosted preview environment, a server-side render of a markdown blob — none of those run inside Obsidian or VS Code. The in-editor plugins are for the author's loop, not the build pipeline.
The diagram is the doc. A tutorial about Mermaid itself benefits from the reader seeing the same default render they'd get on their own setup. Theming it would obscure the lesson.
You're targeting a surface that ships its own Mermaid renderer. GitHub READMEs, Notion, GitLab, some Docusaurus configurations — the surface's renderer wins regardless of what your editor previewed. The editor plugin makes drafting easier; the published output needs a different conversation (see the previous post in this series on the docs-repo workflow).

The rule of thumb: editor plugins are for the writing loop. Hosted shares and pre-rendered SVGs are for the publishing loop.

Wrap-up

Three takeaways:

The "ugly Mermaid preview" problem is solved at the editor, not at the source. Don't sprinkle init directives across every block; install one plugin that handles every block in the vault or workspace.
One install covers more editors than you'd think. Obsidian on the writing side; VS Code, Cursor, Windsurf, and VSCodium on the code-adjacent side. The renderer is the same; the install shell differs.
Per-file front-matter is the escape hatch. bd-theme, bd-share, bd-width cover the three things you actually want to override per note: visual treatment, shareability, and embedded width.

If this was useful, drop a ❤️ and follow — I'm posting weekly on diagrams, docs, and developer ergonomics. Next week: 10 Mermaid Tricks I Wish I'd Known Before Drawing 200 Diagrams.

Which editor is your default writing surface for Mermaid — Obsidian, VS Code, or something I haven't named? I'm trying to figure out whether the next plugin should be JetBrains or Zed first.

Beautify Every Diagram in Your Markdown Docs with One Command

Levi Liu — Tue, 16 Jun 2026 14:39:26 +0000

TL;DR
A typical docs repo has dozens of Mermaid blocks scattered across markdown files, each rendering with whatever default Mermaid theme the consumer site picked, none of them consistent with each other. This post walks the two-command path — bd extract to pull every fenced block out of markdown, bd batch to render them all to themed SVGs, and a small markdown rewrite to embed the SVGs back via <picture>. The same pipeline drops into a GitHub Actions workflow at the end. If you want to try a single file first, the editor renders one block at a time.

The state of diagrams in most docs repos

Open any mid-sized open-source repo with substantial docs — kubernetes/kubernetes, prometheus/prometheus, vercel/next.js. Search the markdown tree for mermaid fenced blocks. You'll find 30 to 100 of them across docs, contributing guides, RFC archives, and stale design notes.

Then look at how those diagrams actually render. Three observations, every time:

Most diagrams use Mermaid's default theme — the pastel one with the muted blues and the soft drop-shadows. It's fine in isolation. Across 40 diagrams in a single docs site, it reads as "nobody owned this."
Some diagrams are silently broken. A typo in a flowchart arrow, an unclosed subgraph, an erDiagram field that no longer parses on the current Mermaid version. The page renders, the diagram block becomes an error message, nobody notices for six months because nobody reads the contributing guide that often.
The diagrams that DO look good are the recent ones. Whoever shipped them most recently set a theme in an init block at the top of the diagram. Older blocks don't have the directive. The site looks like geological strata of "whatever Mermaid theme was fashionable that quarter."

You can fix all three by hand. Open every markdown file, paste each Mermaid block into a renderer, eyeball it, fix syntax errors, prepend an init directive with your preferred theme, save. For a 60-file docs repo that's maybe a day of mechanical work — and it'll drift again in three months because every new contributor adds blocks without the directive.

Or you can build a two-command pipeline that does this automatically and run it in CI.

The pipeline this post builds: extract every fenced diagram out of markdown, render them all in one batch, embed the SVGs back so the rendered page shows your themed version while the markdown source still holds the original code.

Why bake the SVG into the page (instead of letting the site render Mermaid live)

A reasonable counter-argument: "My doc site already renders Mermaid client-side via mermaid.js. Why pre-render at all?"

Three reasons the pre-render path wins for docs:

Consistency across surfaces. Your README on GitHub, your VS Code marketplace listing, your npm page, your Docusaurus site, your printed PDF export — all render Mermaid differently (or not at all). A pre-rendered SVG looks the same everywhere because there's no rendering left to do.
Bundle weight. mermaid.js minified is around 600 KB. If the only reason your docs ship it is the four diagrams on your architecture page, you're paying a meaningful payload tax for every visitor of every other page.
The diagram becomes a real asset. Once it's an SVG on disk you can review it in PRs (the diff is the SVG file, which renders in GitHub's PR view), you can run an <img> accessibility check on it, and you can link to it from outside the docs site.

The pipeline below keeps the Mermaid source in the markdown — so contributors still edit Mermaid, not SVG — but renders to an SVG asset alongside it. The <picture> embed shows the SVG to readers; the source block becomes a collapsed <details> for anyone who wants to see the code.

Step 1 — `bd extract` pulls every diagram out of markdown

npx @beauty-diagram/cli extract docs/**/*.md --assets-dir docs/_diagrams

This walks every markdown file matching the glob, finds every fenced mermaid (and plantuml) block, and writes each one to a standalone source file under the assets directory. Filename is derived from the markdown file path plus a stable hash of the block contents, so re-running on an unchanged docs tree is a no-op.

A typical output:

docs/_diagrams/
  architecture/
    overview-a3f9c1.mmd
    overview-b8e240.mmd
    auth-flow-7c2105.mmd
  contributing/
    pr-lifecycle-91d8a2.mmd
  guides/
    request-path-4e1c80.mmd

A few flags worth knowing:

--dry-run lists what would be written without touching disk. Run this first to see how many blocks your repo actually has.
--clean removes orphaned source files in the assets directory before extracting — useful when blocks get deleted from markdown and you don't want stale .mmd files lying around.
--concurrency <n> controls parallel parsing for very large doc trees. The default is sensible; only touch it if you're indexing thousands of files.

If a block has a syntax error, bd extract still writes the source file and prints a warning. The block is real even if it's broken; the next step decides what to do with broken blocks.

Step 2 — `bd batch` renders them all to themed SVGs

npx @beauty-diagram/cli batch docs/_diagrams/**/*.mmd \
  --out-dir docs/_diagrams \
  --format svg

This renders every extracted source file to an SVG sibling. Same filename, different extension. Theme is whichever one you set globally — BEAUTY_DIAGRAM_THEME=modern in the environment, or passed per-file via the source's own init directive.

You'll get output like:

✓ docs/_diagrams/architecture/overview-a3f9c1.svg (1142×680)
✓ docs/_diagrams/architecture/overview-b8e240.svg (980×420)
✓ docs/_diagrams/architecture/auth-flow-7c2105.svg (1240×910)
✗ docs/_diagrams/contributing/pr-lifecycle-91d8a2.mmd: parse error at line 14
✓ docs/_diagrams/guides/request-path-4e1c80.svg (860×540)

4 succeeded, 1 failed

The --stop-on-error flag flips the failure mode: by default bd batch keeps going so one bad diagram doesn't tank a 200-diagram run. In CI you'll usually want --stop-on-error so a broken block fails the build, which is the whole point of running this in CI to begin with.

--concurrency defaults to a reasonable parallelism for your CPU; raise it on a big CI runner if the batch takes long enough to matter.

The "consistency" payoff lands here. The same theme renders every diagram across the entire docs tree.

A typical architecture diagram rendered with a single chosen theme. The consistency story is that every one of your 40 docs diagrams comes out looking like this one — same stroke weight, same palette, same edge style.

Step 3 — Embed the SVGs back via `<picture>`

The extract / batch pair gave you SVG files. The markdown still holds the original Mermaid source. Now you decide how the rendered page should reference the asset.

The cleanest pattern is <picture> with the SVG as the primary source and a collapsed <details> for the original code:

<picture>
  <img
    src="/_diagrams/architecture/overview-a3f9c1.svg"
    alt="High-level system architecture: API gateway, auth service, app services, and the shared event bus"
  />
</picture>

<details>
<summary>Mermaid source</summary>

```mermaid
flowchart LR
  Gateway[API Gateway] --> Auth[Auth Service]
  Gateway --> App[App Services]
  App --> Bus[(Event Bus)]
```

</details>

Why this shape:

The reader sees the SVG by default — themed, crisp, no client-side rendering cost.
The source is one click away for anyone who wants to copy it into their own diagram, file a fix, or learn from the syntax.
The markdown file remains the source of truth. A contributor editing the doc edits the Mermaid block, runs the pipeline, commits both the updated source and the regenerated SVG.

Most static site generators (Docusaurus, VitePress, MkDocs, Hugo, Astro) render <picture> and <details> natively. GitHub's markdown renderer does too, including in PR descriptions. The pattern is portable.

If you'd rather not maintain the dual source + asset embed by hand, the extract step has a --rewrite mode that updates the markdown file in place — collapsing the fenced block into the <picture> + <details> pair on first run, leaving it alone on subsequent runs.

Step 4 — Wire it into CI so it stays beautified

A small GitHub Actions workflow that fails any PR introducing a broken diagram or skipping the regeneration:

name: Beautify docs

on:
  pull_request:
    paths:
      - 'docs/**/*.md'
      - 'docs/_diagrams/**'

jobs:
  beautify:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: '20'
      - name: Extract diagrams from markdown
        run: |
          npx @beauty-diagram/cli extract 'docs/**/*.md' \
            --assets-dir docs/_diagrams \
            --clean
      - name: Render every diagram
        run: |
          npx @beauty-diagram/cli batch 'docs/_diagrams/**/*.mmd' \
            --out-dir docs/_diagrams \
            --format svg \
            --stop-on-error
        env:
          BEAUTY_DIAGRAM_THEME: modern
      - name: Fail if anything changed
        run: |
          git diff --exit-code docs/_diagrams || (
            echo "::error::Diagrams are out of date. Run the beautify pipeline locally and commit the result."
            exit 1
          )

The git diff --exit-code at the end is the trick. The job regenerates everything from scratch on every PR; if the output differs from what's checked in, the PR failed to run the pipeline before pushing, and the build fails. Contributors learn the workflow once and it stays automatic forever.

For a Makefile-driven repo, the same pattern collapses to two targets:

diagrams:
    npx @beauty-diagram/cli extract 'docs/**/*.md' --assets-dir docs/_diagrams --clean
    npx @beauty-diagram/cli batch 'docs/_diagrams/**/*.mmd' --out-dir docs/_diagrams --format svg --stop-on-error

verify-diagrams: diagrams
    git diff --exit-code docs/_diagrams

make diagrams regenerates locally; make verify-diagrams is what CI calls.

From one file to a whole repo: themed SVGs for every diagram, in one batch

Beauty Diagram's CLI ships extract + batch as the docs-scale pair, so the same renderer that handles a single file in the editor handles a hundred files in CI. Pick a theme once, apply it everywhere, and let the git-diff check keep contributors honest. (Disclosure: I work on it.)

→ Try one diagram in the editor

The fastest way to feel the workflow is one file at a time in the editor — paste a Mermaid block from your docs repo, pick a theme, see whether the result is the consistency you want. Once you've picked a theme you like:

# Install once
npm install -D @beauty-diagram/cli

# Set the theme for the whole repo
export BEAUTY_DIAGRAM_THEME=modern

# Run the pipeline locally
npx bd extract 'docs/**/*.md' --assets-dir docs/_diagrams --clean
npx bd batch 'docs/_diagrams/**/*.mmd' --out-dir docs/_diagrams --format svg

# Commit the assets and the rewritten markdown
git add docs/_diagrams docs/**/*.md
git commit -m "Beautify docs diagrams"

bd beautify, bd export, bd extract, and bd batch all work anonymously for rendering. The paid tier kicks in for AI features (bd ai generate) and higher quotas; the docs-pipeline use case lives entirely inside the free surface.

When NOT to pre-render

A few cases where the live-Mermaid-in-the-browser path is the better trade:

Your docs site already ships mermaid.js for other reasons. If the bundle cost is paid, you're not saving anything by pre-rendering. Use init directives in your Mermaid blocks to set a consistent theme and call it done.
Diagrams change every commit. A README that auto-regenerates an architecture diagram from the codebase on every push has no use for pre-rendered assets — the SVG would be stale by the next push. Live rendering at view time is the right call.
You only have three diagrams. The batch pipeline pays off when there are enough diagrams that consistency is the problem. Three diagrams you can keep coherent by hand.
Your audience needs the source visible by default. A Mermaid tutorial, a "diagrams as code" RFC, a contributing guide. Pre-rendering hides the syntax behind a <details>; if the syntax IS the point, leave it as a fenced block.

The rule of thumb: pre-render when the diagram is a doc asset (read, not edited, by most readers); live-render when the diagram is the doc.

Wrap-up

Three takeaways:

Diagrams in docs repos drift the same way docs drift. Different themes, broken blocks, no review process. The fix is the same fix you applied to docs: a build step + a CI gate.
The two-command pipeline is bd extract + bd batch. Extract pulls every fenced block to standalone source files; batch renders all of them to themed SVGs. The git-diff CI check keeps the output in sync.
Embed via <picture> + collapsed <details>. Reader sees the themed SVG, contributor still edits Mermaid, source of truth stays in markdown.

If this was useful, drop a ❤️ and follow — I'm posting weekly on diagrams, docs, and developer ergonomics. Next week: Beautify Mermaid Diagrams in Obsidian and VS Code (Without Leaving Your Editor).

How many Mermaid blocks does your docs repo have right now? Run grep -r "mermaid" docs/ | wc -l and drop the number in the comments — I'm collecting "diagrams per docs repo" data and the spread is wider than you'd guess.

Generate Mermaid from Plain English with AI (CLI Walkthrough)

Levi Liu — Wed, 10 Jun 2026 09:43:31 +0000

TL;DR
You already know flowchart TD cold. You don't know sequenceDiagram participant aliases, erDiagram cardinality glyphs, or which state diagram dialect Mermaid is on this year. This post is a walkthrough of five prompts → five diagrams using bd ai generate, plus when the AI-first path is wrong. If you want to try without installing anything, the same prompt input lives in the editor.

The friction isn't drawing — it's remembering

I've shipped probably 200 flowcharts. I can sketch a flowchart TD with arrows and labels without thinking. The syntax has lived in my hands long enough that it's muscle memory.

Then someone asks for a sequence diagram of the OAuth flow, and I open the Mermaid docs. Again. For the seventh time this year.

That's the actual friction with diagrams-as-code: most teams write one diagram type 90% of the time and four other types maybe twice a year each. The rare types never make it into your fingers — you re-read the docs every time, hit a syntax snag, and lose ten minutes. Multiply by every infrequent diagram across a docs repo and that's a real tax.

AI removes the activation energy. You describe the diagram in plain English, get back syntactically valid Mermaid, and skip straight to "does this say what I want." That's a different kind of editing — refining a draft instead of looking up glyphs.

The path this post walks: prompt → AI → Mermaid → rendered diagram.

The shape of the workflow

Two paths, same engine underneath:

In the editor — paste your prompt into the AI Generate panel at /editor. It writes the Mermaid for you, you tweak in the source pane, you pick a theme, you export.
In the terminal — bd ai generate "<prompt>" prints the Mermaid to stdout. Pipe it into the renderer, redirect to a file, or paste into your README.

The editor is the right entry point if you're iterating — you can see the rendered diagram live as you refine the source. The CLI is the right surface once you know what you want and you're scripting it into a docs build, a package.json task, or a CI job.

The five examples below all use the CLI form so the prompts and outputs are easy to copy. Every one of them works in the editor too — paste the same prompt, get the same kind of output.

bd ai generate is a paid-plan feature. Anonymous demo gives you the renderer; AI generation is gated behind a key because every call hits a model and costs money. bd auth login once, set BEAUTY_DIAGRAM_API_KEY in CI, done.

Prompt 1 — OAuth login (sequence diagram)

Sequence diagrams are the textbook case for "I know what I want, I don't remember the syntax." Participants, arrows, dotted return lines, loop blocks — there's just enough surface to forget between uses.

bd ai generate "user signs in with Google OAuth: web app redirects \
to Google's authorize endpoint, user approves, Google returns an \
authorization code, web app exchanges the code at our API for a \
session token"

The AI returns something like:

sequenceDiagram
  participant U as User
  participant W as Web App
  participant G as Google OAuth
  participant A as App API
  U->>W: Click "Sign in with Google"
  W->>G: Redirect to /authorize
  G->>U: Consent prompt
  U->>G: Approve scopes
  G->>W: Authorization code
  W->>A: Exchange code
  A->>W: Session token
  W->>U: Logged in

Render it:

OAuth authorization-code flow, generated from the prompt above and rendered with the atlas theme.

The participants are aliased (U as User, W as Web App) without me having to remember the syntax. The arrows pick ->> for solid calls. Two minutes from prompt to rendered diagram, of which ten seconds was renaming "App API" to "Backend" to match the codebase.

Prompt 2 — Multi-tenant SaaS schema (ER diagram)

ER diagrams are the worst offender for syntax recall. Cardinality glyphs — ||--o{, }o--||, |o--o| — never live in anyone's head.

bd ai generate "multi-tenant SaaS database: users belong to many \
workspaces through memberships; workspaces own projects; projects \
contain tasks; users are also assigned to tasks"

Output:

erDiagram
  USERS ||--o{ MEMBERSHIPS : has
  WORKSPACES ||--o{ MEMBERSHIPS : has
  WORKSPACES ||--o{ PROJECTS : owns
  PROJECTS ||--o{ TASKS : contains
  USERS ||--o{ TASKS : assigned

A multi-tenant SaaS schema, generated from a one-sentence prompt and rendered with the blueprint theme.

The model picked the right cardinality glyphs without you typing them. It also picked an entity-naming convention (uppercase, plural) and stuck with it across all five entities. That's the kind of consistency tax you'd otherwise pay manually.

When this matters: the diagram is wrong if MEMBERSHIPS should have been an attribute on USERS instead of a join entity. The AI guessed "many-to-many through membership", which is the right call for most multi-tenant SaaS — but if you're modeling something else, you'll edit. That's the workflow: get a draft fast, refine the parts that don't match your domain.

Prompt 3 — CI/CD pipeline (flowchart)

Yes, even the flowchart you can write blindfolded benefits from a prompt when the diagram has six branches and a manual gate.

bd ai generate "GitHub Actions pipeline: PR merged to main triggers \
tests; if tests pass build a container image, deploy to staging, \
require manual approval, then deploy to production. If tests fail, \
notify the PR author."

Output:

flowchart TD
  PR[PR merged to main] --> Test[Run tests]
  Test -->|pass| Build[Build image]
  Test -->|fail| Notify[Notify author]
  Build --> Stage[Deploy to staging]
  Stage --> Gate{Manual approval}
  Gate -->|approve| Prod[Deploy to prod]
  Gate -->|reject| Hold[Hold release]

The CI/CD pipeline, with the failure branches the prompt asked for. Rendered with the modern theme.

Two details worth noting. First, the AI chose {Manual approval} (decision diamond) instead of [Manual approval] (rectangle) for the gate — the right shape for a yes/no branch. Second, it used -->|pass| for labelled edges instead of breaking the label onto a separate line, which is the cleaner Mermaid idiom.

You could have written this. The question is whether you want to spend three minutes typing it or thirty seconds prompting it. For a diagram that's going in your team's onboarding doc and won't change for six months, the prompt path is the better trade.

Prompt 4 — Order lifecycle (state diagram)

State machines are another "syntax-rare" category. [*] --> X, transitions with labels, the difference between stateDiagram and stateDiagram-v2 (the v2 syntax is what Mermaid currently maintains).

bd ai generate "order lifecycle state machine: starts in cart, \
becomes placed on checkout, paid when payment succeeds, shipped \
when fulfilled, delivered when the carrier confirms. From paid, \
the customer can cancel to refunded."

Output:

stateDiagram-v2
  [*] --> Cart
  Cart --> Placed: Checkout
  Placed --> Paid: Payment OK
  Paid --> Shipped: Fulfilled
  Shipped --> Delivered: Carrier confirms
  Delivered --> [*]
  Paid --> Refunded: Customer cancels
  Refunded --> [*]

Order lifecycle states, with the refund branch the prompt described. Rendered with the slate theme.

The AI picked stateDiagram-v2 (the current syntax), used [*] for entry and exit, and put transition labels after the colon. All things I'd otherwise look up.

There's a subtler thing happening: the prompt described "from paid, the customer can cancel to refunded" — a side branch from the main happy path. The AI laid it out as a separate transition rather than nesting it inside a state Paid { ... } block. That's a layout decision the model made for you. If you wanted the refund flow nested, you'd add "group Paid → Refunded into a Paid composite state" to the prompt.

Prompt 5 — Notification class hierarchy (class diagram)

Class diagrams are the format devs hate most. The syntax is verbose, the cardinality / inheritance arrows are easy to mix up, and you write maybe two per year.

bd ai generate "class hierarchy for a polymorphic notification \
system: base Notification with channel and deliver(), then \
EmailNotification with htmlBody and fromAddress, SmsNotification \
with shortMessage and senderId, PushNotification with deeplink \
and iconUrl"

Output:

classDiagram
  class Notification {
    +String channel
    +deliver()
  }
  class EmailNotification {
    +String htmlBody
    +String fromAddress
  }
  class SmsNotification {
    +String shortMessage
    +String senderId
  }
  class PushNotification {
    +String deeplink
    +String iconUrl
  }
  Notification <|-- EmailNotification
  Notification <|-- SmsNotification
  Notification <|-- PushNotification

Three-channel notification class hierarchy. Rendered with the atelier theme.

<|-- (empty triangle, hollow head, line) is the inheritance arrow. Reversed direction (--|>) means the same relationship from the other end. Knowing that one glyph fluently is the difference between a 30-second class diagram and a 5-minute one. The AI knows it; you don't have to.

When NOT to use AI

The prompt-to-diagram path is great for drafts. It's a worse fit for these cases:

The diagram already exists, you're refining it. Editing five nodes by hand is faster than prompting "the same diagram but with X changed." Refinement is what the editor's source pane is for.
You need precise layout. AI controls the content (nodes, edges, labels). It doesn't control left-vs-right ordering, column widths, where the diamond lands. If a stakeholder needs the "approve" branch on the right specifically, you'll be editing the source anyway.
The diagram encodes ground truth. Database schemas pulled from \dt, API call sequences pulled from logs, dependency graphs from your build system — pull these from the source of truth, don't have an AI guess. The AI is useful when you're the source of truth and the friction is just getting it into Mermaid syntax.
You're learning Mermaid. If your goal is to internalize the syntax for a diagram type you'll need monthly, hand-write the first five. After that, automation is fine. Skipping the learning round costs you forever.

The rule of thumb: use AI for "I know what I want and I don't want to look up the syntax." Don't use it for "I don't know what the diagram should show yet" or "this diagram needs to be load-bearing for an audit."

Skip the docs lookup: Prompt to rendered diagram, end to end

Beauty Diagram's AI panel generates Mermaid from plain English in the same editor where you pick a theme and export — no separate AI tool, no copy-paste round trip. The same pipeline runs from the CLI for scripted use. (Disclosure: I work on it.)

→ Try it in the editor

The web flow:

Open the editor at /editor and click the AI Generate panel.
Type your prompt. The model writes Mermaid into the source pane.
Tweak the source if needed — rename a participant, reorder an entity, retitle an arrow.
Pick a theme (classic, modern, atlas, blueprint, memphis, obsidian, slate, brutalist, or atelier) and export SVG or PNG.

If you'd rather script it from the terminal:

# Print Mermaid to stdout
npx @beauty-diagram/cli ai generate "user signup with email verification"

# Pipe straight into the renderer with a theme
npx @beauty-diagram/cli ai generate "user signup with email verification" \
  | npx @beauty-diagram/cli beautify - --theme modern --out signup.svg

# Or save the source and the SVG together
npx @beauty-diagram/cli ai generate "user signup with email verification" --out signup.mmd
npx @beauty-diagram/cli beautify signup.mmd --theme modern --out signup.svg

bd ai generate is paid-plan only — bd auth login saves a key locally, or set BEAUTY_DIAGRAM_API_KEY in CI. The renderer half (bd beautify, bd export) works anonymously if you only need rendering.

Wrap-up

The three takeaways:

Use AI for the diagram types you don't write often. Sequence, ER, class, state — anything where you'd otherwise re-read the docs. Flowcharts you already write fluently; skip the AI if you don't need the speed.
Treat the output as a draft. Rename, reorder, retheme. The prompt got you past the syntax wall; you still own the diagram.
Two surfaces, one engine. Editor for iteration, CLI for scripts. The CLI's bd ai generate | bd beautify - pipe is the fastest "prompt to SVG on disk" path.

If this was useful, drop a ❤️ and follow — I'm posting weekly on diagrams, docs, and developer ergonomics. Next week: Beautify Every Diagram in Your Markdown Docs with One Command.

What's the diagram type you re-read the docs for every time? Sequence? State? ER? Drop it in the comments — I'm building a list of "which Mermaid types people forget most" and the answers so far are surprising.

Mermaid vs PlantUML in 2026: Which to Pick for Engineering Docs

Levi Liu — Tue, 02 Jun 2026 16:15:22 +0000

TL;DR
Mermaid won the README and the markdown ecosystem; PlantUML won the engineering whiteboard and the IDE. In 2026 they're still the two serious "diagram as code" formats, and which one you should pick depends on where the diagram lives more than what it shows. This post compares them on syntax, layout, diagram coverage, and ecosystem, ending with a decision rule you can apply in 60 seconds. Both render through the same editor if you want to try them side by side without installing anything.

The honest framing

I've shipped engineering docs with both. Every six months someone on the team asks "should we standardise on Mermaid or PlantUML?" and every six months the answer is "it depends on where the diagram lives."

That answer used to be a cop-out. In 2026 it's the truth. The two formats have converged on the same problem — render diagrams from plain text — and diverged on everything around it: who writes them, where they render, what they look like, and how much patience they expect from you.

This article is the side-by-side I wish someone had handed me three years ago.

At a glance

The table you came here for:

Dimension	Mermaid	PlantUML
Native rendering on GitHub	✅ since 2022	❌ (proxied images only)
Native rendering on Notion	✅	❌
Native rendering on GitLab	✅	✅
IDE / editor extensions	Broad (VS Code, JetBrains, Obsidian)	Broad, with deeper JetBrains roots
Layout engine	Dagre (flowcharts), ELK opt-in	Graphviz (`dot`)
Supported diagram types	~16	~20+
Syntax style	Markdown-adjacent	Annotation-heavy
Server-side renderer	Headless Chromium	Java + Graphviz
Best at	Flowcharts, sequence, journey	Class, component, deployment, ERD
Worst at	Dense ERDs, large class diagrams	Anything that needs to live on GitHub

The rest of this post is the detail under each row.

Round 1 — Syntax ergonomics

The same flow, written two ways. Pick which one reads more naturally to you.

Mermaid:

flowchart TD
  A[Client] --> B{Token valid?}
  B -->|Yes| C[Fetch user]
  B -->|No| D[Redirect to login]
  C --> E[Return 200]
  D --> F[Return 302]

PlantUML:

@startuml
start
:Client;
if (Token valid?) then (yes)
  :Fetch user;
  :Return 200;
else (no)
  :Redirect to login;
  :Return 302;
endif
@enduml

Mermaid's syntax leans on nodes and edges as the primitive. You say "A points to B with this label" and the layout follows. It reads like a constraint list.

PlantUML's syntax leans on statements as the primitive. You say "do this, then this, with this branch" and the layout follows. It reads like pseudocode.

For people who think in flow ("first this happens, then this"), PlantUML's start/if/endif is intuitive. For people who think in graphs ("these are the nodes, these are the edges"), Mermaid is the lower-friction path.

There's no objectively-better here. Pick the one that matches how your team already whiteboards.

Same auth flow, Mermaid source, rendered into a finished SVG.

Same flow expressed in PlantUML — different syntax, same end shape.

Round 2 — Layout quality

Layout is where the two diverge the most, and it's the thing nobody talks about until they've shipped a dozen diagrams and realised one of the formats keeps making nodes overlap.

Mermaid uses Dagre by default. Dagre is a hierarchical layout algorithm — fast, deterministic, and great on flow charts with 5 to 30 nodes. Past that it starts producing the visual you've seen on a thousand READMEs: tall, narrow columns with edges crossing in ways no human would draw.

Mermaid has an elk opt-in (Eclipse Layout Kernel) that's much better at dense graphs. As of 2026 it's still flagged as experimental in most distributions, but it's stable enough to use in production.

PlantUML uses Graphviz (the dot engine), which has been the gold standard for hierarchical graph layout for 30 years. The output reflects that — PlantUML diagrams routinely look right out of the box, especially as the graph grows past 20 nodes.

For a 6-node flow chart, both produce something readable. For a 60-node class diagram, PlantUML wins by a noticeable margin.

The catch: Graphviz is a native binary. Running PlantUML in a CI job or a serverless function means shipping a Java + Graphviz runtime. Mermaid is JavaScript end-to-end, which is the trade.

Round 3 — Supported diagram types

Both cover the basics; PlantUML covers more obscure ones.

Mermaid (2026, native pack):

Flowchart
Sequence diagram
Class diagram
State diagram
ER diagram
Gantt
Pie
User journey
Quadrant chart
XY chart
Mindmap
Timeline
Sankey
Block diagram
Git graph
C4 (experimental)

PlantUML (mature set):

All of the above, plus:
Component diagram
Deployment diagram
Activity diagram (legacy + beta)
Use case
Object diagram
Network diagram (nwdiag)
Wireframe (Salt UI mockup)
Archimate
BPMN-like activity flows
Bytefield diagrams

If you're writing a software architecture doc that needs deployment diagrams or component diagrams — the boxes-inside-boxes-with-interfaces pattern — PlantUML's coverage is meaningfully wider. Mermaid's block diagram type covers a chunk of this, but it's not at parity.

If you're writing a feature spec with flowcharts, sequence diagrams, and ER diagrams — the 80% case for product engineering — both are fine.

Round 4 — Where it renders without help

This is the single biggest practical difference, and the reason the answer in 2026 is "it depends on where the diagram lives".

Mermaid renders natively on:

GitHub READMEs and markdown files (since 2022)
GitLab
Notion code blocks
VS Code markdown preview
Obsidian
Bitbucket Cloud
Most static site generators with a plugin (Docusaurus, VitePress, MkDocs Material, Astro)

PlantUML renders natively on:

GitLab (snippets + wiki)
JetBrains IDEs (with the official plugin)
Confluence (with a plugin)

Everywhere else, PlantUML rendering means either:

Pre-rendering to SVG/PNG and committing the image, or
Pointing at a public PlantUML server (www.plantuml.com/plantuml/svg/<encoded>) and accepting that your diagram source is encoded into a third-party URL.

For a GitHub README in 2026, Mermaid is the only format that renders inline without a build step. That's not a small thing — it's the entire reason Mermaid has more momentum.

For an internal Confluence-driven engineering org, PlantUML's class / component / deployment coverage and Graphviz layout makes it the better default.

Round 5 — Ecosystem and tooling

Both ecosystems are healthy. They optimise for different surfaces.

Mermaid:

Maintained by a foundation; weekly releases
Live editor at mermaid.live
Official CLI: @mermaid-js/mermaid-cli (uses Puppeteer under the hood)
VS Code extension by the maintainers
Obsidian native support
AI tooling generates Mermaid by default — most LLMs output Mermaid when asked for a diagram in markdown

PlantUML:

Maintained primarily by Arnaud Roques and a small team; releases are slower but steady
Live editor at www.plantuml.com/plantuml
Official tool: plantuml.jar (Java)
JetBrains plugin is best-in-class for the JVM crowd
Confluence integration is a paid plugin but widely deployed
AI tooling support is improving but still trails Mermaid

There's a quieter consequence here. When you ask an LLM for "a diagram of X", you almost always get Mermaid back. That's mostly habit and training-set bias, not a quality call — but it does mean that if your team is leaning on AI-assisted doc writing, Mermaid will show up in your repo whether you picked it or not.

Round 6 — Learning curve

The bottom 20% of each language takes about an hour. The remaining 80% is what differs.

Mermaid has a flat learning curve — the syntax is markdown-adjacent and most people write a working flowchart on their first try. The wall comes when you want to customise — themeVariables, init directives, classDef, link styling — because each diagram type has its own subset of the customisation surface, and the documentation is scattered.

PlantUML has a steeper start — @startuml / @enduml, statement-based syntax, skinparam overrides — but a flatter middle, because once you've learned skinparam you've learned the customisation surface for every diagram type. The wall comes later, around legacy syntax (the original activity grammar vs the newer start/stop beta).

For a team that ships occasional diagrams, Mermaid's flat start wins. For a team where someone "owns" the diagram system and is going to push it to its limits, PlantUML's consistency wins.

The decision rule

Three questions, in order:

Does the diagram need to render on GitHub or in a markdown file consumed by tools you don't control? → Mermaid. Stop here.
Does it need to be a deployment, component, or detailed class diagram with 30+ nodes? → PlantUML. Stop here.
Anything else? → Mermaid for the lower install footprint and broader AI tooling; PlantUML if your team is already on JetBrains + Confluence.

The 60-second decision rule.

Most engineering teams in 2026 end up using Mermaid for repo-level docs and PlantUML for architecture documents that live in Confluence or a wiki. That's not a compromise — it's the right answer. The cost of standardising on one format and forcing the wrong fit is higher than the cost of two file extensions in your repo.

Both formats, one editor: Don't pick — render both

Beauty Diagram parses Mermaid, PlantUML, and draw.io. Paste either format, pick from 9 production themes, export SVG or PNG. Useful when your docs repo has both formats and you want them to look consistent. (Disclosure: I work on it.)

→ Try the editor

The web flow:

Paste the source — Mermaid or PlantUML — into the editor at /editor. The format is auto-detected.
Pick a theme. The same nine themes (classic, modern, atlas, blueprint, memphis, obsidian, slate, brutalist, atelier) apply to both formats, so a doc with a mix of Mermaid and PlantUML diagrams renders consistently.
Export SVG or PNG, or use Share to get a hot-linkable URL.

If you're scripting this from CI — say, beautifying every diagram in your docs repo on each release — the same pipeline runs from a CLI:

# Works on both Mermaid and PlantUML files
npx @beauty-diagram/cli beautify auth.mmd --theme atlas --out auth.svg
npx @beauty-diagram/cli beautify components.puml --theme atlas --out components.svg

bd themes lists the available themes. There's no per-property style override — the theme is the choice; you pick a different one if you don't like what you see.

Wrap-up

The 60-second version:

Mermaid wins if the diagram lives in a README, a markdown file, a Notion page, or anything you don't fully control. It also wins if you're heavy on AI-assisted doc writing.
PlantUML wins if the diagram is a deployment / component / detailed class diagram, or if your team is centred on JetBrains + Confluence.
Both is fine. Pick the format per-diagram, not per-org.

If this was useful, drop a ❤️ and follow — I'm posting weekly on diagrams, docs, and developer ergonomics. Next week: Generate Mermaid from plain English with AI — a CLI walkthrough.

Which one is your team standardised on, and did the decision survive the second year? Drop a note in the comments — I'm collecting the regret-or-validation stories.

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

Adding Beautiful Diagrams to Your Docusaurus / VitePress Site

The doc site tax on Mermaid diagrams

Where the rendering actually happens

Path 1: enable Mermaid, accept defaults

Docusaurus

VitePress

Path 2: keep Mermaid, pick a theme once

The site-config way (the one you actually want)

The per-block way (avoid if you can)

The scaling ceiling for path 2

Path 3: swap the renderer, embed the SVG

When each path is right

Wrap-up

10 Mermaid Tricks I Wish I'd Known Before Drawing 200 Diagrams

How I got here

1. Comments with %% (yes, inside the diagram)

2. Edge labels carry weight — use them

3. linkStyle for per-edge visual hierarchy

4. Per-node style for the one node that matters

5. classDef + class — styling that scales

6. classDef inheritance: stack multiple classes on one node

7. Subgraphs as zones, not boxes

8. Click handlers — Mermaid as navigation

9. Theme variables via %%{init}%% — when you don't want the defaults but don't want a tool

10. Pick a theme once at the renderer, not per-block

When the open-source tricks are enough

Wrap-up

Beautify Mermaid Diagrams in Obsidian and VS Code (Without Leaving Your Editor)

The "almost good enough" preview problem

Why the default Mermaid theme falls flat

Path 1 — Obsidian: install from Community Plugins

Picking a theme inside the vault

Per-note overrides via front-matter

Path 2 — VS Code (and Cursor / Windsurf / VSCodium): install from Marketplace

Picking a theme without leaving the file

Per-file front-matter overrides

The "no round-trip" loop, end to end

When the in-editor path isn't the right path

Wrap-up

Beautify Every Diagram in Your Markdown Docs with One Command

The state of diagrams in most docs repos

Why bake the SVG into the page (instead of letting the site render Mermaid live)

Step 1 — bd extract pulls every diagram out of markdown

Step 2 — bd batch renders them all to themed SVGs

Step 3 — Embed the SVGs back via <picture>

Step 4 — Wire it into CI so it stays beautified

When NOT to pre-render

Wrap-up

Generate Mermaid from Plain English with AI (CLI Walkthrough)

The friction isn't drawing — it's remembering

The shape of the workflow

Prompt 1 — OAuth login (sequence diagram)

Prompt 2 — Multi-tenant SaaS schema (ER diagram)

Prompt 3 — CI/CD pipeline (flowchart)

Prompt 4 — Order lifecycle (state diagram)

Prompt 5 — Notification class hierarchy (class diagram)

When NOT to use AI

Wrap-up

Mermaid vs PlantUML in 2026: Which to Pick for Engineering Docs

The honest framing

At a glance

Round 1 — Syntax ergonomics

Round 2 — Layout quality

Round 3 — Supported diagram types

Round 4 — Where it renders without help

Round 5 — Ecosystem and tooling

Round 6 — Learning curve

The decision rule

Wrap-up

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

1. Comments with `%%` (yes, inside the diagram)

3. `linkStyle` for per-edge visual hierarchy

4. Per-node `style` for the one node that matters

5. `classDef` + `class` — styling that scales

9. Theme variables via `%%{init}%%` — when you don't want the defaults but don't want a tool

Step 1 — `bd extract` pulls every diagram out of markdown

Step 2 — `bd batch` renders them all to themed SVGs

Step 3 — Embed the SVGs back via `<picture>`

Approach 1: Native `mermaid` code block

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

1. `theme` (the cheapest win)

2. `themeVariables`