A project stood out on Hacker News on October 17-18. It is called Pele: a lightweight SVG renderer that themes Mermaid diagrams with CSS.

Why is it timely? Modern LLMs are very good at producing Mermaid syntax when explaining a diagram. The problem is what comes next. To put that text into a website or a doc, you need a renderer. Mermaid.js is powerful but heavy, hard to theme, and it scales diagrams down on narrow screens.

Pele aims straight at those three problems. It was made by kepano (Steph Ango) at Obsidian, and named after Pele, the goddess of volcanoes.

What it is

Pele (MIT, github.com/obsidianmd/pele)

- Form        : a Mermaid-syntax to SVG renderer
- Dependencies: zero runtime dependencies
- Mode        : synchronous rendering
- Theming     : colors and fonts via CSS variables
                (changing colors needs no re-render)
- Syntax      : every diagram type built into Mermaid 12.1.0
- Testing     : tested against Mermaid's parser specs and
                with differential fuzzing
- Origin      : built for Obsidian to render diagrams quickly
                and match the theme

Using it takes two lines.

npm install pele

import { render } from 'pele';

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

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

With mount(), the browser renders into an element, reads fonts from CSS, and adapts the layout to the container width. If the bundle is a concern, register only the diagram types you need from pele/core, or lazy-load with renderAsync() from pele/lazy. There is also a CDN global build.

The published comparison

Here is the comparison the project published.

Metric Pele Mermaid.js
Bundle size (gzip) 230 kB 1.6 MB
Render time 0.05-0.3 ms 6-82 ms
Direct dependencies 0 23
Small screens Adapts the layout Scales the diagram
Theming CSS variables Theme configuration

In short: 6x smaller and up to 500x faster. I am quoting the table as published, but the last row deserves a caveat: these are the project's own benchmarks. The repository ships npm run bench so you can reproduce them, but the felt difference varies with diagram type and size. Do not read it as "every diagram is always 500x faster."

Still, the second row matters in practice. Mermaid.js's 6-82 ms is time the render blocks the UI thread. In a document with many diagrams, that difference accumulates.

Why CSS variables

Pele's most practical feature is how it themes. Colors change without a re-render.

[How Pele themes]

.pele {
  --pele-bg: #fffcf0;
  --pele-fg: #100f0f;
  --pele-line: #100f0f;
  --pele-surface: #f2f0e5;
  --pele-accent: #205ea6;
  --pele-font: sans-serif;
  --pele-radius: 4px;
}

charts use --pele-series-1 through --pele-series-8

+ switching dark and light mode
  changes only colors, not a re-render

That is more than convenience. When a site's theme changes, you need not redraw diagrams, and you can keep a server-rendered SVG cached while managing color in CSS. Mermaid's theme configuration (themeVariables) does not apply, so plan for that difference when migrating.

Compatibility and limits

A new renderer comes with new constraints. The official docs lay out the differences.

[Layout and appearance]
- Pele uses its own layout engine
  -> node positions, spacing and edge paths differ from Mermaid
- Mermaid themes and themeVariables colors do not apply

[Sizing]
- diagrams scale down to fit narrower containers
- pass maxWidth to let the layout adapt
  (e.g. a wide flowchart can switch to a vertical layout)
- responsive: false for a fixed pixel size

[Limits]
- limits on source length, SVG output size, and edges in
  flowcharts and agentflow
- labels are SVG text (line breaks, bold, italic)
  -> arbitrary HTML labels are not supported
- click statements that open a link are supported; JS callbacks ignored
- external Mermaid plugins such as ZenUML are not supported
  -> use supports() to check a diagram type

Security is documented too. To handle untrusted diagrams, Pele escapes text, filters links and styles, and limits source and output size. In other words, this is not "paste any Mermaid" — for diagrams of unknown origin, apply limits deliberately.

Conclusion: a light way to ship AI-drawn diagrams

The briefing's action, turned into an experiment:

[Compare one Mermaid source across two renderers]

1. Prepare
   [ ] one piece of Mermaid source
   [ ] render it once with Mermaid.js, once with Pele

2. Look at the screen
   [ ] render speed (especially with several diagrams)
   [ ] readability (labels, layout, contrast)
   [ ] compatibility (does it support the types you use)

3. Look at integration
   [ ] bundle size (230 kB vs 1.6 MB gzipped)
   [ ] does color follow a theme change
   [ ] how does the layout behave on narrow screens

4. Decide
   [ ] for dense docs or boards, Pele has an edge
   [ ] if any diagram type is unsupported, plan a fallback

One line captures it.

Shipping the picture AI made for you
is now a matter of renderer choice.

That LLMs produce Mermaid well is a constant. The variable is how lightly, how themedly, and how safely you draw that text. Put the same Mermaid into two renderers and compare on a real screen, and the choice for your docs becomes obvious. For the web side, see AI Vibe-Coding Web Development, and for making visuals with generative AI, continue with Generative AI Content Basics.

Further reading

References

Go deeper with a course

Choosing a renderer, matching your theme, and handling narrow screens all grow fastest from building for the web. Pull an idea onto the web quickly, and the sense of which tool to attach where follows.