Pele (Mermaid)

Canonical version: Pele (Mermaid).

Pele is an Open Source library (MIT) that renders Mermaid diagrams to SVG. It comes from the Obsidian team and was created by Steph Ango (kepano), the CEO of Obsidian. The goal is stated plainly on the website: render diagrams quickly in Obsidian and make them match your theme.

The name comes from Pele, the Hawaiian goddess of volcanoes and fire. Fitting for something that claims to be up to 500x faster!

Why Pele?

Mermaid's syntax is great. The official renderer (Mermaid.js) is heavy, though: 23 dependencies, a big bundle, and theming through a configuration object instead of plain CSS. Pele keeps the syntax and replaces the renderer.

Here are the numbers from the project's own benchmark (headless Chrome, Pele vs Mermaid.js):

• Bundle size: 230 kB gzipped vs 1.6 MB (the site says "6x smaller")
• Render time: 0.05 to 0.3 ms vs 6 to 82 ms ("up to 500x faster")
• Direct dependencies: 0 vs 23

These are the author's numbers. I haven't benchmarked it myself, so take them as a claim, not a measurement.

What it does

• Supports every diagram type built into Mermaid 12.1.0 (the parsers are tested against Mermaid's own parser specs, plus differential fuzzing)
• Renders synchronously, with zero runtime dependencies
• Uses its own layout and visual style, so the output does NOT look exactly like Mermaid.js
• Adapts the layout on small screens, where Mermaid.js just scales the whole diagram down
• Themes through CSS variables (e.g., --pele-bg, --pele-fg, --pele-accent, --pele-font, --pele-radius, --pele-series-1 to --pele-series-8 for charts). Color changes apply without re-rendering
• Escapes diagram text, filters links and styles, and limits source and output size, which matters when you render untrusted input

Usage

Install it with npm install pele (or pnpm, yarn, bun). There's also a CDN build: https://cdn.jsdelivr.net/npm/pele@1/dist/pele.global.js.

Render to an SVG string:

import { render } from 'pele';

const { svg } = render(`flowchart LR
  A[Start] --> B{Decision}
  B -->|Yes| C[Action]
  B -->|No| D[End]`);

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

In the browser, mount() renders into an element, reads the fonts from your CSS, and adapts to the container width:

mount(document.querySelector('#diagram'), text);

To keep the bundle small, register only the diagram types you need:

import { register, render } from 'pele/core';
import flowchart from 'pele/diagrams/flowchart';

register(flowchart);

Or load the diagram types lazily with renderAsync from pele/lazy.

Theming is just CSS:

.pele {
  --pele-accent: #205ea6;
}

My take

This follows the same pattern as Defuddle: kepano takes a piece that Obsidian needs, builds it as a small standalone library, and gives it away under MIT. The CSS variables are what make Pele a natural fit for Obsidian themes (and for any site that already has a design system).

I'd reach for it whenever I render Mermaid in a web app or a static site and care about page weight. The one case where I'd stay with Mermaid.js is when I need the output to match Mermaid's look pixel for pixel. Pele doesn't try to do that.

References

• Official website: https://pele.run/
• Source code: https://github.com/obsidianmd/pele
• API documentation: https://pele.run/api
• Theming: https://pele.run/theming
• Security: https://pele.run/security
• NPM package: https://www.npmjs.com/package/pele

Related

• Mermaid
• beautiful-mermaid
• Obsidian
• Steph Ango
• Defuddle

About Sébastien

Ready to get to the next level?