How to render Mermaid diagrams with your website's theme: we test Pele, from Obsidian

[Devy]

So your Mermaid diagrams follow your website’s theme, dark mode included, render them with Pele: an MIT library from Obsidian that converts the same Mermaid syntax into SVG whose colors come from CSS variables. That way the diagram changes along with your page instead of keeping Mermaid’s color palette. We installed it, placed it alongside Mermaid.js in light and dark mode, and measured both.

GitHub - obsidianmd/pele: Renders Mermaid diagrams faster than you'd run...

yoDEV Tested · October 18, 2026 We installed Pele 1.6.0 from npm and compared it with Mermaid 12.2.0 on Node 22 and in Chromium headless, with the same diagram and the same CSS. The results we report as ours come from that test.

What is Pele and how does it differ from Mermaid.js?

Pele is a JavaScript library that takes text in Mermaid syntax and returns SVG. It’s not a Mermaid plugin and doesn’t depend on Mermaid: it has its own parser, its own layout engine and zero runtime dependencies. It supports all diagram types included in Mermaid 12.1.0, from flowcharts and sequence diagrams to Gantt, C4, Sankey and mind maps.

It was created for Obsidian, the notes app, with the goal of drawing diagrams quickly and matching the user’s theme. It’s maintained by Steph Ango (kepano) in the obsidianmd organization on GitHub. The name comes from the Hawaiian goddess of volcanoes, not the footballer.

You still write Mermaid. What changes is who draws it.

Why do Mermaid diagrams look bad in dark mode?

Because Mermaid takes its colors from its own theme configuration, not from your stylesheet. In our test we put the same flowchart on the same page, with the same CSS, and switched the browser to dark mode. With its default theme, Mermaid 12.2.0 kept the nodes white, and the lines and arrow tips remained black: on an almost black background they practically disappear. Mermaid does come with its own themes (what in English is searched as mermaid theme), but they’re chosen in its configuration, and your page’s CSS doesn’t reach them.

In Pele, nodes, lines and labels read their colors from --pele-* variables. Each hexadecimal value in the SVG it generated was just a fallback value inside var(). When the page switched to dark, the node fill changed from rgb(242, 240, 229) to rgb(28, 27, 26) without re-rendering the diagram: our render counter stayed at 1.

How do you render Mermaid diagrams with your website’s theme?

You install a package with no additional dependencies:

npm install pele

Then you pass the Mermaid text to render() and insert the SVG it returns:

import { render } from 'pele';

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

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

render() is synchronous and also works in Node without DOM. We rendered the test diagram on the server side, where Pele measures text with a width table included instead of a canvas. So it works the same for converting Mermaid to SVG (mermaid to svg) in a static site generator as in the browser.

There are two other entry points worth knowing about:

• pele/lazy loads each diagram type the first time it’s used: const { svg } = await renderAsync(source);
• pele/global defines a global pele object for pages without a bundler. It comes in the package at dist/pele.global.js, and it’s the version we loaded in Chromium.

How do you change the colors of a Mermaid diagram with CSS variables?

You define the variables in .pele or in any element that contains it. The root <svg> of each diagram has the .pele class. The following block is the color palette from Pele’s theme documentation, with a dark variant under prefers-color-scheme, and it’s exactly what we used in the test:

.pele {
  --pele-bg: #fffcf0;
  --pele-fg: #100f0f;
  --pele-muted: #6f6e69;
  --pele-line: #100f0f;
  --pele-surface: #f2f0e5;
  --pele-surface-alt: #e6e4d9;
  --pele-border: #cecdc3;
  --pele-accent: #205ea6;
  --pele-critical: #af3029;
}
@media (prefers-color-scheme: dark) {
  .pele {
    --pele-bg: #100f0f;
    --pele-fg: #cecdc3;
    --pele-muted: #878580;
    --pele-line: #cecdc3;
    --pele-surface: #1c1b1a;
    --pele-surface-alt: #282726;
    --pele-border: #403e3c;
    --pele-accent: #4385be;
    --pele-critical: #d14d41;
  }
}

In practice, you point these variables to the tokens your site already has. The complete set of mermaid css variables that Pele offers covers:

• background, text, secondary text and lines
• node fill and subgraph fill, and borders
• an accent color, plus a “critical” color for Gantt and kanban
• --pele-error, fonts, font weights and --pele-radius
• --pele-series-1 through --pele-series-8 for charts

Elements also have classes like pele-node, pele-edge and pele-label, and you can target a specific node by its id in the source code with [data-id="…"].

One detail about fonts: Pele measures labels to size the boxes, so it needs to know the font before drawing. mount() reads it from --pele-font; with render() you pass it:

const fontFamily = getComputedStyle(container).fontFamily;
container.innerHTML = render(source, { fontFamily }).svg;

When to use render() and when to use mount()?

Use render() when you want a string: static site generators, server-side rendering, Markdown pipelines. Use mount() when the diagram lives on a page that changes:

import { mount } from 'pele';

const diagram = mount(container, source);
diagram.update('flowchart LR\n  A[Draft] --> B[Published]');

mount() observes the container and redistributes the diagram when its width changes. In our test, when we reduced the container to 320 px, the left-to-right diagram became vertical and zoom activated automatically. It reorganizes the diagram instead of shrinking it until the text is illegible.

mount() also handles errors in place. When we passed it broken syntax in update(), it didn’t throw any exception: the previous diagram remained on screen, dimmed, with the parser error on its bottom edge, and diagram.error.code returned syntax on line 3. With render(), errors are thrown as PeleError, with code, line, column and a snippet that marks the column.

Is Pele faster and lighter than Mermaid.js?

According to our measurements, yes, although the speed difference was smaller than the headline figure. The project’s own comparison, which is self-reported, indicates:

• 230 kB in gzip versus 1.6 MB
• render times of 0.05–0.3 ms versus 6–82 ms
• “up to 500 times” faster

This is what we measured, on a single machine and with a five-node flowchart:

	Pele 1.6.0	Mermaid 12.2.0
Bundle, gzip -9	245 KB	1,532 KB
Hot render, Chromium headless	~0.44–0.59 ms	~71–79 ms
First render on page	~17 ms (mount())	~377–431 ms
Render in Node, with parsing	0.56 ms	not tested

The size claim holds: Pele is about six times lighter. In our diagram, the speed difference was about 135 to 180 times, within the “up to 500” but far from that ceiling. For a documentation page with a handful of diagrams, the practical difference isn’t in the milliseconds, it’s in sending 1.3 MB less JavaScript.

What doesn’t Pele do?

Pele is a reimplementation, so it’s not identical to Mermaid pixel for pixel. Its compatibility page is clear about the differences:

• The layout changes. Node positions, spacing and line tracing come from Pele’s own layout engine. If you depend on Mermaid’s exact layout, check your diagrams in the Playground before migrating.
• Mermaid themes don’t apply. themeVariables are ignored and color comes from CSS.
• Colors defined within the diagram are fixed. The ones you set with style, classDef or linkStyle don’t follow the theme.
• Labels don’t support arbitrary HTML. Line breaks, bold and italics do work.
• click with links work, but JavaScript callbacks are ignored.
• It doesn’t support ZenUML or external Mermaid plugins. supports() tells you if a diagram type is available.

Is it stable enough to use?

It moves fast. Version 1.0.4 came out on October 6, 2026 and 1.6.0 on October 17, and two of the intermediate versions changed the API:

• Version 1.5.0 removed watch and fit() from mount().
• Version 1.6.0 made mount() and update() stop throwing exceptions on invalid input.

Also, at the time of publishing this note (October 18, 2026), Pele documents compatibility with Mermaid 12.1.0, while npm already serves Mermaid 12.2.0. Pin the version and read the release notes before updating. If a diagram looks different than in Mermaid, the project asks you to report it with a comparison made in the Playground.

Is it a good alternative to Mermaid.js?

If you render Mermaid on a site with dark mode, like documentation, a blog or an internal portal, yes: it’s a direct mermaid alternative because it doesn’t force you to rewrite any diagrams. Try it on a page: the change is an import and a CSS block, and diagrams start following your theme. If you depend on Mermaid’s exact layout, its theme configuration or ZenUML, stick with Mermaid for now.

If what you’re looking for is not rendering your Mermaid but having an agent generate diagrams with its own design, check out what we published on diagram-design for Claude Code.

---

What about you? In which part of your work do you use Mermaid diagrams today: documentation, READMEs, presentations or something else?

How do you render your Mermaid diagrams?

• Mermaid.js on my own site
• What my tool brings (GitHub, Obsidian, my docs generator)
• I export them to image and paste them
• I prefer another option (tell us which)

Comment below or, if this article reached you by email, reply directly to the email: your reply is published here.

Related: Reladraw: the alternative to Mermaid where you decide where each node goes