DEV Community: Levi Liu

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

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

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

The four defaults that ruin your diagrams

Fix 1: Switch to base theme

Fix 2: Set six theme variables

Fix 3: Linear edges

Fix 4: Light/dark adaptive embed

Putting all four together

When DIY stops being worth the time

Wrap-up

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

The problem nobody talks about

Why SVG and not PNG

Approach 1: The official Mermaid CLI

The four theming knobs that actually matter

1. theme (the cheapest win)

2. themeVariables

3. Edge curves

4. Layout direction

Three rendering pitfalls

Fonts don't render in the saved SVG

viewBox cropping

Dark mode is hardcoded

When DIY stops being worth the time

Wrap-up

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`