Render Mermaid diagrams with Pele instead of mermaid

[gsimone]

## Render Mermaid diagrams with Pele instead of mermaid

Pele (obsidianmd/pele, MIT) is a new Mermaid renderer from the Obsidian team. It's synchronous, has no runtime dependencies and supports every diagram type built into Mermaid 12.1. It writes SVG strings without touching the DOM, and its colors come from CSS variables.

I swapped it into apps/web/src/components/chat/MermaidDiagram.tsx on a fork: gsimone/t3code@feat/pele-mermaid (diff)

Why

• Smaller. Rendering one flowchart loads 53 KB gzip with Pele versus 225 KB with mermaid. The whole renderer is 275 KB gzip versus 961 KB.
• Faster. A warm render of a 40-node flowchart takes about 1 ms with Pele versus 154 ms with mermaid. Even with Pele's text-width cache cleared, the same render takes 20 ms. Cold first render (import to SVG) is 39 ms versus 109 ms.
• No re-render on theme switch. Mermaid writes theme colors into the SVG, so every light/dark switch re-renders every visible diagram, which costs about 150 ms of main-thread time for the medium flowchart. Pele reads --pele-* CSS variables, which the branch maps to the app's theme tokens, so diagrams recolor in place, including in custom themes.
• Simpler code. No global mermaid.initialize config, no serialized render queue, no theme in the cache key. The SVGs are 4 to 7 times smaller, so the existing DOMPurify pass has less to do.

What the branch changes

• MermaidDiagram loads pele/lazy, which fetches one chunk per diagram type, and renders with links and images turned off. The existing DOMPurify sanitizer still runs, now without the foreignObject and HTML allowances mermaid needed.
• index.css maps --pele-* to --background, --foreground, --muted-foreground, --accent, --primary and so on.
• Click-to-expand copies the current theme colors into the exported SVG, so the expanded image keeps the theme.
• mermaid is removed from apps/web.
• A new MermaidDiagram.browser.test.tsx checks that labels survive sanitization, links are dropped, syntax errors don't offer a retry, and the expanded image keeps the theme colors.

Screenshots

Same Markdown file (diagrams.md), opened in the file preview.

	mermaid (main)	Pele (branch)
Light
Dark
Narrow panel

Benchmark

Headless Chromium 148 on an M1 Pro. Each renderer runs the same code path as its version of MermaidDiagram: per-render initialize and mermaid.render on main, renderAsync on the branch. Times are medians in ms.

	mermaid 11.17.2	Pele 1.6.0	Pele, text cache cleared
Cold first render (small flowchart)	109	39
Flowchart, 5 nodes	19.8	0.13	1.8
Flowchart, 40 nodes / 47 edges	153.5	1.06	20.2
Sequence	13.3	0.09	4.8
Class	47.4	0.13	7.4
Gantt	6.2	0.09	5.8
Pie	4.4	0.04	2.0
State	44.9	0.20	3.2
ER	25.3	0.14	4.4
Theme switch (40-node flowchart)	153 (re-render)	0

All eight diagram types rendered with both renderers. Script and raw results: pele-mermaid-evidence/bench.

Caveats and open questions

• Look. Pele has its own layout and visual style. It isn't a pixel match for mermaid, and diagrams that set colors with style or classDef keep those fixed colors.
• Narrow containers. Wide flowchart LR diagrams in narrow panels shrink with both renderers. Pele can re-lay a diagram out for its container width (maxWidth / mount()), which could be a follow-up.
• Package age. Pele 1.6.0 shipped on 2026-10-17, so the branch adds a pinned minimumReleaseAgeExclude entry. Waiting out the release-age window instead would also work.
• Mobile. Mobile doesn't render Mermaid today, but because Pele needs no DOM, it could render diagrams for mobile as well.

Would you be open to this swap? If so, I can open a PR from the branch.

[spiky02plateau]

+1. The mobile point at the end is the part I'd most like to see. On the iOS app, Mermaid fences in chat don't render today, so plans and architecture sketches from agents don't work on my phone.

I checked that Pele's render() runs outside a browser. In plain Node with no DOM, pele 1.6.0 rendered flowchart, sequence, class, ER, gantt, pie and state diagrams. None of the outputs contained <style> or foreignObject, so the SVG is plain shapes and text. The full pele.global.js is 682 kB raw, 252 kB gzip.

One thing a mobile adapter has to handle: colors come through var(--pele-*) in the root style attribute, and react-native-svg doesn't resolve CSS variables. Mobile needs either a WebView like the existing html_render path, or the variables replaced with theme colors before the string goes to SvgXml. The second avoids a WebView per diagram. I haven't tried it on a device.

One renderer across web, desktop and mobile also means a fence looks the same everywhere. #14721 targets the same mobile gap with beautiful-mermaid and a limited syntax subset; Pele covers every Mermaid 12.1 diagram type.

Checked with claude-opus-5-5 in Claude Code.

[spiky02plateau]

A scoping question for maintainers, so the two parts stay independent: if the web swap is approved, would a mobile adapter using the same renderer be welcome as a separate follow-up PR? I'd keep it to apps/mobile, leave invalid or unsupported fences as code blocks, and include iOS simulator screenshots in light and dark.

[Blackskyliner]

If it's even allowed to stay with us in general: https://youtu.be/ESq3ostvznQ?si=lBfOvrFh55AukPyG&t=7710

I would appreciate, to increase approval factor maybe, that it's a toggle just like the LaTeX one in general instead of just plainly supporting it, even if the new renderer you suggested would be more performant..

EDIT after Merge like 8 Minutes after I posted: Whelp my comment aged faster than milk on a thunderstormy summer day. 😅

[juliusmarminge]

Note

Grok responding on behalf of Julius.

This landed in #21472, which swaps mermaid.js for pele for Mermaid diagrams in chat, file previews, plans, and PR descriptions. Thanks for the proposal and the fork that showed the way. Closing as resolved.