remark-mermaid-tldraw

name

remark-mermaid-tldraw

description

Integrate the `remark-mermaid-tldraw` package so a project's ```mermaid code fences render as tldraw's warm, hand-drawn SVGs at build time (light + dark variants, zero client JS). Use this skill whenever the user wants their mermaid diagrams to look hand-drawn / sketched / less generic, mentions tldraw + mermaid together, wants build-time or pre-rendered diagrams in a blog or docs site, asks to "make my diagrams look better", or is wiring diagrams into MDX, Astro, Next.js, Eleventy, Vite, or React Router markdown. It encodes the exact install (including the headless-browser peer deps), the four wiring steps, the per-framework recipes, and — most importantly — the MDX-only `rehype-raw` gotcha that silently breaks the build if you miss it, plus how caching, light/dark, and the unsupported-diagram fallback work. Reach for it proactively when adding diagrams to any markdown/MDX pipeline; the default mermaid output is fine but flat, and this swaps it for the tldraw aesthetic without shipping any runtime JS.

remark-mermaid-tldraw

Pre-render ​```mermaid fences into tldraw's hand-drawn SVGs at build time. It's two cooperating parts that agree on a filename and never talk to each other:

1. a remark plugin that rewrites each fence into light/dark <img> tags, and
2. a headless renderer (CLI / programmatic / Astro integration) that drives a real tldraw editor in Playwright-Chromium and writes the SVGs.

The reader downloads an <img> — no mermaid, no tldraw, no hydration. Package: remark-mermaid-tldraw · GitHub.

Install

npm i -D remark-mermaid-tldraw tldraw @tldraw/mermaid playwright react react-dom
npx playwright install chromium

tldraw, @tldraw/mermaid, playwright, react, react-dom are peer deps (the renderer needs a browser + the React/tldraw stack). vite, @vitejs/plugin-react, unist-util-visit, mdast-util-from-markdown, and tinyglobby come along as regular deps. The remark plugin itself is lightweight — it does NOT pull in tldraw/playwright, so importing it in a config is cheap.

Wire it up — four steps

1. Add the remark plugin

It rewrites each ​```mermaid fence into <figure class="mermaid-diagram not-prose"> with a light and a dark <img> pointing at /diagrams/<hash>.svg.

import { remarkMermaidTldraw } from "remark-mermaid-tldraw";
// in your markdown/MDX remarkPlugins:
remarkPlugins: [remarkMermaidTldraw];
// or with options: [remarkMermaidTldraw, { theme: "dark" }]

2. Add the render step (produces the SVGs)

A prebuild CLI for most setups:

// package.json
"scripts": {
  "mermaid": "remark-mermaid-tldraw --content \"src/**/*.{md,mdx}\" --out public/diagrams"
}

Run npm run mermaid whenever a diagram changes, and commit public/diagrams/. (Or wire it into a prebuild step if your CI has a browser.) On Astro, prefer the integration — it auto-renders on config:setup and hot-reloads in dev:

import { mermaidTldraw } from "remark-mermaid-tldraw/astro";
export default defineConfig({
  integrations: [mermaidTldraw()],
  markdown: { remarkPlugins: [remarkMermaidTldraw] },
});

3. Add the light/dark CSS

Both variants are emitted with transparent backgrounds; you pick one per scheme:

.mermaid-dark { display: none; }
@media (prefers-color-scheme: dark) {
  .mermaid-light { display: none; }
  .mermaid-dark { display: inline; }
}
/* class-based theme: html.dark .mermaid-light{display:none} html.dark .mermaid-dark{display:inline} */
.mermaid-diagram { margin: 2rem auto; display: flex; justify-content: center; }
.mermaid-diagram img { width: 100%; height: auto; }

On a single-theme site, pass { theme: "dark" } (or "light") to the plugin so the browser never fetches the variant it can't show.

4. Write a fence

```mermaid width=380
flowchart TD
  A --> B
```

width= (bare number → px, or any CSS length) caps a tall flowchart's width.

⚠️ The MDX gotcha (read this — it silently breaks the build)

The plugin emits a raw HTML <figure> node. Plain markdown (Astro .md, remark-rehype) handles that fine. MDX does not — @mdx-js throws Cannot handle unknown node "raw". Fix: add rehype-raw as the FIRST rehype plugin, with passThrough for MDX's own node types, or it will destroy any JSX components in your .mdx files:

import rehypeRaw from "rehype-raw";

rehypePlugins: [
  [rehypeRaw, {
    passThrough: [
      "mdxFlowExpression", "mdxJsxFlowElement", "mdxJsxTextElement",
      "mdxTextExpression", "mdxjsEsm",
    ],
  }],
  // ...your other rehype plugins after this
]

(npm i -D rehype-raw.) This step is MDX-only; skip it for plain-markdown pipelines.

Per-framework cheat sheet

• Astro — remark plugin in markdown.remarkPlugins + the /astro integration. No rehype-raw needed (Astro markdown handles raw HTML).
• Vite + @mdx-js/rollup (incl. React Router 7) — plugin in remarkPlugins, add rehype-raw (passThrough) as the first rehypePlugins entry, run the CLI as a prebuild.
• Next.js (@next/mdx) — plugin in remarkPlugins, rehype-raw (passThrough) in rehypePlugins, CLI prebuild over content//app/.
• Eleventy / plain remark — plugin + CLI; no rehype-raw.

How caching works (so you don't fight it)

• Filenames are sha256(source).slice(0,16) — the URL depends ONLY on the diagram source, so it never changes when render logic does.
• A render-version marker comment lives inside each SVG. Bump RENDER_VERSION (or visual changes from a tldraw upgrade) → diagrams re-render in place, URLs stay stable.
• The headless browser launches ONLY when something is stale. Cached build = no browser.

Troubleshooting

• Labels clipped / spilling out of boxes — a font race; the harness already preloads tldraw's fonts before rendering, so this is handled. If you see it, you're on an old version — update.
• Build error Cannot handle unknown node "raw" — you're on MDX without rehype-raw. See the gotcha above.
• Diagram didn't update after an edit — re-run the render step; a source edit changes the hash → a new file. To GC old files run the CLI with --clean.
• Diagram looks like plain mermaid, not hand-drawn — that type (pie, gantt, class, ER) isn't modeled natively by tldraw, so it falls back to mermaid's own SVG. Flowcharts and sequence diagrams get the tldraw look.
• CI — add npx playwright install chromium to the workflow before the render/build step.

Caveats

Build-time only: you need a browser where you build (and in CI). The payoff is zero runtime cost — the visitor gets a cached SVG, never mermaid or tldraw.

---

Built by Sean Geng; generalizes Sunil Pai's Astro plugin and stands on @tldraw/mermaid. Full writeup: Rendering mermaid diagrams as hand-drawn tldraw.