Pele: Mermaid Renderer, 500x Faster, Zero Dependencies

Mermaid.js is in everything. GitHub READMEs, GitLab wikis, Docusaurus sites, Notion pages, VS Code extensions — if a tool claims diagram support, it probably shells out to Mermaid. That ubiquity comes at a price: a 1.6 MB gzipped bundle, 23 npm dependencies, render times between 6 and 82 milliseconds, and theming that fights you at every turn. Steph Ango, founder of Obsidian, decided this was unacceptable and built Pele — a from-scratch Mermaid renderer that ships at 230 KB, renders in 0.05–0.3ms, and has zero dependencies. It went live on Friday, it is MIT-licensed, and it is on npm now.

The Numbers

The headline figures are not marketing copy. They come from direct benchmark comparisons:

• Render speed: 0.05–0.3ms (Pele) versus 6–82ms (Mermaid.js) — up to 500x faster at the high end
• Bundle size: 230 KB gzipped versus 1.6 MB — 6x smaller
• Dependencies: 0 versus 23 npm packages
• Syntax support: Full compatibility with Mermaid 12.1.0 — every diagram type

Even the conservative end of the comparison is significant. A 20x render speedup (0.3ms vs 6ms) is noticeable in any interface that renders diagrams on user interaction. For documentation sites that render dozens of diagrams per page load, the bundle size reduction alone is worth the migration.

Integration Takes Three Lines

Pele’s API is deliberately minimal. The render() function is synchronous — no await, no promise chains, no async initialization overhead:

import { render } from 'pele';

const { svg } = render(`flowchart LR
  A[Start] --> B[Process] --> C[End]`);

document.querySelector('#diagram').innerHTML = svg;

For browser environments with resize and font-loading awareness, mount() handles the lifecycle automatically. For server-side or build-time rendering pipelines, the synchronous render() API is particularly valuable — it eliminates the async complexity that makes Mermaid.js awkward in SSR contexts.

Theming That Actually Works

Mermaid’s theming system requires you to choose a preset theme at initialization time and fight CSS specificity if you want to deviate. Changing a color can mean re-rendering the entire diagram. Pele replaces all of that with CSS custom properties:

:root {
  --pele-bg: #1e1e2e;
  --pele-fg: #cdd6f4;
  --pele-muted: #6c7086;
  --pele-line: #6c7086;
  --pele-surface: #313244;
  --pele-border: #45475a;
}

Update a variable at runtime and the diagram reflects the change without touching the SVG. Dark mode switching — which is a known pain point in Mermaid-powered documentation sites — becomes a single CSS variable swap.

Responsive Layout, Not Responsive Scaling

This distinction matters more than it sounds. Mermaid renders a fixed-size SVG and scales it down when the viewport narrows. Text gets tiny. Nodes crowd together. Pele adapts the layout itself — node positions, spacing, and text reflow for the actual container width. On mobile, a complex flowchart in Pele looks designed for mobile. The same chart in Mermaid looks like a desktop diagram that was squished.

When Not to Use Pele

GitHub READMEs and GitLab wikis render Mermaid diagrams server-side using their own pipeline — Pele cannot help you there. If your diagrams live primarily in markdown files that GitHub renders natively, Pele is not your solution.

Pele is also not a replacement for D2, PlantUML, or Graphviz — it is a Mermaid-compatible renderer, not a new diagram syntax. If you are evaluating diagram formats from scratch, D2 is worth a look for its layout quality. If you are already on Mermaid syntax and want to stay there, Pele is the upgrade.

The Obsidian Signal

Pele will be the default diagram renderer in the next major version of Obsidian — one of the most widely used developer note-taking tools, with millions of active users. This is not an academic benchmark. Pele will be stress-tested against real-world usage at significant scale before most projects encounter it. That matters when evaluating whether a young library is worth adopting.

The project is at Version 1.3.0, has 786 GitHub stars two days after announcement, and shows active maintenance. The playground at pele.run lets you test your own diagrams in the browser before committing to the migration.

Getting Started

npm install pele
# or
pnpm add pele
# or
bun add pele

The GitHub repository includes full API documentation, the theming reference, and examples for both browser and Node environments. The playground is the fastest way to confirm your specific diagrams render correctly before migrating.

Mermaid has served developers well as the path of least resistance for years. It still holds the advantage in GitHub-rendered contexts. But for developers building apps and tools that render diagrams in the browser, Pele is the better option — smaller, faster, and far easier to theme. The only question remaining is how long Mermaid stays as the default dependency in projects that no longer need it.