Pele: Obsidian's Lightning-Fast Mermaid Renderer Goes Open Source

Obsidian's Pele: A New Era for Mermaid Diagram Rendering

Obsidian, the popular knowledge management platform, has unveiled Pele, a lightweight open-source library that renders Mermaid diagrams as themeable SVG. Developed by Steph Ango (kepano), the library is set to become the default renderer in the next version of Obsidian, but it's available now for any developer to integrate. The project is named after the Hawaiian goddess of volcanoes and fire, a fitting moniker for a tool designed to be explosive in performance.

Pele directly addresses long-standing pain points with the standard Mermaid.js library: bundle size, rendering speed, and theming complexity. By leveraging CSS variables instead of a rigid theme configuration, Pele allows developers and users to style diagrams with unprecedented flexibility. The result is a renderer that's not only faster but also more responsive to user preferences and device contexts.

Performance Benchmarks: 500x Faster and 6x Smaller

The headline numbers from the official comparison are striking. Pele boasts a gzip bundle size of just 230 kB compared to Mermaid.js's 1.6 MB—a 6x reduction. More impressively, render times drop from 6–82 ms to a mere 0.05–0.3 ms, representing up to a 500x speed improvement. This is achieved with zero direct dependencies, whereas Mermaid.js relies on 23.

These gains are not just theoretical. For Obsidian, which renders diagrams dynamically as users type, this translates to a dramatically more fluid note-taking experience. For web developers, it means faster page loads and less JavaScript to parse, especially on mobile devices. The performance difference is so significant that it could shift the default choice for new projects requiring Mermaid compatibility.

CSS Variable Theming: Instant Customization Without Re-rendering

Pele's theming approach is its most innovative feature. Instead of a central theme configuration, Pele exposes seven CSS variables that control the entire visual appearance:

• --pele-bg: Background color
• --pele-fg: Foreground/text color
• --pele-muted: Muted text color
• --pele-line: Line and connector color
• --pele-surface: Primary surface (e.g., node background)
• --pele-surface-alt: Alternate surface color
• --pele-border: Border color

Because these are standard CSS variables, color changes apply without re-rendering the SVG. This is a game-changer for applications that support theming or dark mode, as diagrams can instantly adapt to user preferences or system settings. Developers can also inherit variables from their own design system, ensuring diagrams match the surrounding UI perfectly.

Full Mermaid 12.1.0 Compatibility and Responsive Layout

Despite the performance and size advantages, Pele maintains full compatibility with Mermaid syntax. It supports every diagram type built into Mermaid 12.1.0, including flowcharts, sequence diagrams, class diagrams, state diagrams, and more. This means developers can migrate existing Mermaid code without rewriting their diagrams.

Pele also handles responsive design differently than Mermaid.js. On small screens, Pele adapts the layout of the diagram itself, rather than simply scaling the entire SVG down. This approach preserves readability and prevents diagrams from becoming cramped or unreadable on mobile devices—a subtle but crucial improvement for modern web applications.

How to Integrate Pele into Your Application

Adding Pele to a project is straightforward. It's available via all major package managers:

npm install pele
pnpm add pele
yarn add pele
bun add pele

The API consists of a single render() function that accepts Mermaid syntax and returns an SVG string:

import { render } from 'pele';

const { svg } = render(`flowchart LR
  A[Mermaid text] --> B[SVG]`);

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

This simplicity is intentional. The library is designed to be a drop-in replacement for Mermaid.js in most use cases, with the added benefit of CSS-based theming. The official documentation includes a playground where users can experiment with both Mermaid syntax and CSS variables in real-time.

Why Pele Matters for the Web Development Ecosystem

The release of Pele represents a significant shift in how diagram rendering can be approached. By decoupling the rendering engine from theming and leveraging CSS variables, Obsidian has created a library that is both developer-friendly and user-centric. The performance gains are not incremental—they are transformative, especially for applications that render many diagrams or operate on low-powered devices.

Furthermore, Pele's MIT license and open-source nature mean it can be adopted freely in commercial and personal projects. Its development for Obsidian ensures it will be battle-tested in a real-world application, and the active community around both projects suggests ongoing maintenance and improvements. As the web continues to demand faster, more responsive experiences, Pele positions itself as a compelling alternative to the established Mermaid.js library.