A new open source project called Pele has emerged as a lightweight alternative to Mermaid.js, the popular JavaScript library developers use to turn plain text into diagrams. Pele takes the same Mermaid syntax that millions of developers already know and renders it directly into SVG, but with a focus on smaller footprint, faster performance, and easier visual theming. For teams that embed diagrams in documentation, wikis, or note-taking apps, this kind of under-the-hood swap can meaningfully improve load times and styling flexibility without forcing anyone to learn a new syntax.

What Pele actually does

At its core, Pele takes Mermaid syntax as input and outputs an SVG. Developers pass their diagram text to a render() function, and the returned SVG can be inserted directly into a web page. This mirrors the basic workflow that Mermaid.js users are already familiar with, which lowers the barrier to switching. According to the project, Pele supports every diagram type built into Mermaid 12.1.0, meaning flowcharts, sequence diagrams, class diagrams, and other formats should work without modification to existing diagram definitions.

Why theming without re-rendering matters

One of the more notable claims is that Pele lets developers control diagram colors and fonts using CSS variables, and that color changes apply without re-rendering the diagram. In traditional Mermaid.js workflows, changing a theme often means regenerating the SVG or re-running the rendering pipeline, which is computationally wasteful if all that changed is a color palette. By externalizing styling to CSS variables, Pele effectively separates the structural rendering step from the visual styling step. This is a practical win for applications with dark mode toggles, user-customizable themes, or dynamic branding, since the underlying diagram geometry does not need to be recalculated every time a color scheme changes.

The performance and size claims

Pele’s own description states it is zero dependencies, six times smaller, and up to 500 times faster than Mermaid.js. These are the project’s stated figures rather than independently verified benchmarks, but they point to a clear design priority: minimize bundle size and rendering overhead. Mermaid.js is a mature and feature-rich library, but it carries dependencies and a rendering pipeline built to handle a broad set of use cases, which can add weight to web pages or applications that only need basic diagram rendering. A smaller, dependency-free renderer is particularly attractive for performance-sensitive contexts like note-taking apps, browser extensions, or static site generators where every kilobyte and millisecond counts.

Built for Obsidian, useful beyond it

Pele was developed specifically for Obsidian, the popular note-taking and knowledge-management app, where the goal was to render diagrams quickly and have them automatically match the user’s chosen theme. This origin story explains the emphasis on speed and CSS-based theming: Obsidian users frequently switch themes and expect embedded content, including diagrams, to adapt instantly. Because Pele is open source, however, its use is not limited to Obsidian. Any web-based project that currently relies on Mermaid.js for SVG diagram rendering could potentially adopt Pele as a drop-in alternative, provided it only needs the diagram types covered by Mermaid 12.1.0 compatibility.

The name itself is a nod to Pele, the goddess of volcanoes and fire in Hawaiian mythology, a fitting metaphor for a tool built around speed and transformation.

What this means for developers trying it out

For developers curious about Pele, the project’s site includes a live editor where users can write Mermaid syntax and see it rendered to SVG in real time, along with a direct comparison of syntax, layout, and features against standard Mermaid.js. This makes it straightforward to evaluate whether an existing diagram definition renders correctly and whether the visual output meets expectations before committing to a migration.

There are caveats worth keeping in mind. Because Pele is a reimplementation rather than a fork of Mermaid.js, subtle rendering differences in layout or diagram styling are possible even when the syntax is identical. Developers with diagrams that push into edge-case syntax or rely on very specific Mermaid.js rendering behavior should test thoroughly before switching production systems. Additionally, since Pele targets compatibility with Mermaid 12.1.0 specifically, projects depending on newer Mermaid features released after that version may not yet be supported.

Frequently asked questions

Is Pele a replacement for Mermaid.js?
It is designed as an alternative renderer that accepts the same Mermaid syntax, but it is a separate, independently built project rather than an official successor or fork.

Do existing Mermaid diagrams work in Pele without changes?
Pele states it supports every diagram type built into Mermaid 12.1.0, so diagrams written for that version should generally work, though developers should verify rendering output for their specific diagrams.

Can Pele be used outside of Obsidian?
Yes. While it was built for Obsidian, Pele is open source and can be integrated into any project by calling its render() function and inserting the resulting SVG into a page.

Source: Pele – Mermaid diagrams as themeable SVG