Diagrams as Code — Beauty Diagram Blog

Beautify Every Diagram in Your Markdown Docs with One Command

Levi Liu — Tue, 23 Jun 2026 15:11:17 GMT

Disclosure: I work on Beauty Diagram, the CLI used in the examples below. Everything in this post is doable with open-source tooling alone; the CLI is one way to make it ergonomic.

TL;DR A typical docs repo has dozens of Mermaid blocks scattered across markdown files, each rendering with a different default theme. 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 . The same pipeline drops into a GitHub Actions workflow at the end.

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 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 embed shows the SVG to readers; the source block becomes a collapsed

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

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 with the SVG as the primary source and a collapsed

for the original code:


  



Mermaid source

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

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 and

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 +

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. Pick a theme once, apply it across the whole repo, let the git-diff check keep contributors honest.

→ Try one diagram in the editor

# 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

bd beautify, bd export, bd extract, and bd batch all work anonymously for rendering. 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
; 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 + collapsed
. Reader sees the themed SVG, contributor still edits Mermaid, source of truth stays in markdown.

Generate Mermaid from Plain English with AI (CLI Walkthrough)

Levi Liu — Fri, 12 Jun 2026 17:34:02 GMT

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.

Disclosure: I work on a small web editor and CLI that's mentioned in the second half. The first half — the prompting workflow and the five diagram types — works with any AI that produces Mermaid; the tool just packages the pipeline.

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 an editor — paste your prompt into an AI panel that writes Mermaid for you, tweak the source, pick a theme, export.
In the terminal — bd ai generate "" prints the Mermaid to stdout. Pipe it into a renderer, redirect to a file, or paste into your README.

The editor path 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.

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 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 a 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 internalise 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."

A small recommendation (disclosed at the top)

The tool I work on, Beauty Diagram, bundles prompt-to-Mermaid generation, a fixed set of production themes (classic, modern, atlas, blueprint, memphis, obsidian, slate, brutalist, atelier), and SVG/PNG export into one editor — useful if you want the prompt → rendered diagram loop without juggling separate tools.

The same pipeline runs from a CLI:
# Prompt → rendered SVG, one pipe
npx @beauty-diagram/cli ai generate "user signup with email verification" \
  | npx @beauty-diagram/cli beautify - --theme modern --out signup.svg
bd ai generate is paid-plan only (each call costs us a model invocation); bd auth login saves a key locally. The renderer half (bd beautify, bd export) works anonymously if you only need rendering. → Try the editor if you want to see the prompt loop without installing anything.

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.

Most teams I've watched adopt this end up using AI for the 20% of diagrams that aren't flowcharts, and keep hand-writing flowcharts because the muscle memory is faster than a prompt. That split happens organically — you don't have to enforce it.

Embed Mermaid in Notion: The 4 Working Approaches in 2026

Levi Liu — Fri, 05 Jun 2026 14:32:40 GMT

-->

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.

Disclosure: I work on a small web editor that's mentioned briefly toward the end. The bulk of the article is about the open-source options — the four approaches stand on their own, no tool needed.

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 honoured. 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 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

Diagrams as Code — Beauty Diagram Blog

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

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

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

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

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

Approach 1: Native `mermaid` code block