Pele makes Mermaid diagrams themeable without a browser

FuturPulse analysis · 19 October 2026

Pele 1.6.0 shipped on 17 October 2026 with in-place diagram errors, while its core proposition remains unchanged: render Mermaid 12.1.0 syntax as CSS-variable-driven SVG without launching a headless browser.

What shipped in Pele’s first 12 days?

Pele’s public release history shows a fast series of additions between 6 and 17 October 2026. The important distinction is that the project has shipped browser-free SVG rendering already; later releases added safer embedding, responsive behaviour and clearer failure handling around that base.

• 6 October 2026
  Pele 1.0.4 shipped a size guardrail. The release notes set the default maximum at 5,000 flowchart edges and introduced the maxEdges option. That matters when a shared note or generated file might contain a diagram too large to sensibly lay out.
• 7 October 2026
  Pele 1.1.0 shipped zoom and pan controls. The published release entry says mounted diagrams can zoom through controls, gestures, keyboard input and drag actions. This addressed the practical problem created when a responsive diagram shrinks to fit a narrow reading pane.
• 9 October 2026
  Pele 1.2.0 shipped link relationship controls. The release notes added linkRel, with noopener as its default. That gives an application a defined way to set link behaviour in generated diagrams.
• 9 October 2026
  Pele 1.3.0 shipped switches to remove links and images. The version 1.3.0 entry added links: false and images: false, covering relative addresses and internal links as well. It also said mounted diagrams could parse once and reuse that parsed model on later renders.
• 15 October 2026
  Pele 1.5.0 shipped a sanitizer hook for mounted output. The release notes added a sanitize option before SVG insertion and changed container-resize observation to always-on behaviour. This is a useful integration point, not a substitute for an application’s own trust decisions.
• 17 October 2026
  Pele 1.6.0 shipped visible errors in the diagram container. The latest release entry says failed updates keep the last valid drawing dimmed and show an error at its bottom edge. It also added unique SVG IDs for mounted diagrams, avoiding clashes when several diagrams share a page.

That timeline does not show a public roadmap promise followed by a delayed delivery. It shows shipped releases. The useful reading is narrower: Pele’s themeable-SVG claim is now accompanied by controls for mounting, resizing, linking, images, sanitizing and errors.

How does Pele avoid a headless browser?

Pele avoids a headless browser because it does not invoke Mermaid’s browser renderer in Node.js. Its package describes a synchronous library with no runtime dependencies, and its exported module is a JavaScript renderer rather than a wrapper around Chromium, Playwright or Puppeteer.

In practical terms, an app passes Mermaid text to render() and receives an SVG string. In a browser, it can use mount() to place the result in an element and adapt it to the container; the Pele README describes both routes.

This is not merely a smaller install story. A headless browser is a complete browser process used off-screen to execute web code. Pele instead parses the diagram language and creates drawing elements itself, so server-side rendering does not need a browser binary or a browser-launch configuration.

The trade-off is explicit. Pele targets Mermaid syntax but uses its own layout and visual style, so equal input does not mean pixel-identical output. Its authors say diagrams preserve source nodes, connections and labels, while positions, spacing, dimensions and edge routing can differ.

Can the SVG change themes without a new render?

Yes. Pele’s distinctive feature is that colors and fonts are controlled through CSS custom properties, commonly called CSS variables, in the surrounding page. Pele’s site says color changes apply without re-rendering the diagram, so a dark-mode switch can alter an already-mounted SVG.

That is different from choosing a theme only when generating a file. A typical Pele rule can set values such as --pele-bg, --pele-fg, --pele-line, --pele-surface and --pele-font on the diagram or one of its parent elements.

.pele {
  --pele-bg: #171512;
  --pele-fg: #f5f0e7;
  --pele-line: #8fc1ff;
  --pele-surface: #25211b;
  --pele-font: system-ui, sans-serif;
}

For a product team, that means the diagram can inherit the same design tokens used by the rest of the interface. It also means a diagram can follow local context: a warning panel, presentation mode or embedded documentation page can each set different variables without regenerating source text.

The claim should not be overstated. Theme changes alter presentation, not the underlying diagram model. A container-width change can still require a new layout pass, because text wrapping, direction and spacing may need to change when available space changes.

How does Pele compare with other renderers?

Pele is best understood as an alternative rendering engine, not a drop-in promise of visual parity. Mermaid CLI and mermaid-isomorphic are ways to run Mermaid’s own rendering stack outside a normal interactive page; Pele is a separate implementation that accepts Mermaid-oriented syntax and emits its own SVG.

The comparison is operational rather than aesthetic. Mermaid CLI accepts Mermaid files and generates SVG, PNG or PDF, which makes it a natural publishing tool. It also supports a CSS file for Mermaid’s theme configuration, but its own documentation warns that inline CSS can be blocked by a host page’s Content Security Policy.

mermaid-isomorphic takes another route: outside browsers it uses Playwright, and users must install both Playwright and a Playwright browser. That is appropriate when an application needs a browser-backed Mermaid result, including browser behaviour around fonts and SVG generation.

Pele’s advantage is not that it exports SVG while rivals cannot. All three can produce SVG. Its difference is the combination of synchronous browser-free rendering and SVG that keeps its color and font decisions connected to CSS variables after insertion.

What does browser-free mean for deployment?

Browser-free rendering reduces moving parts in a service or build pipeline. A package using Pele can install the renderer and execute it without separately provisioning Chromium, downloading browser binaries or tuning launch settings for a browser process.

The contrast is clearest in container use. Mermaid CLI’s own documentation offers a container route and shows a Podman invocation that mounts a local directory into the renderer container. Podman’s run reference explains that a container starts a process with its own filesystem, networking and isolated process tree.

That isolation can be desirable, especially for a static rendering job. It also introduces file mounts, image retrieval and user identity choices. The CLI’s Podman example uses --userns keep-id; Podman’s user-namespace documentation says this maps a rootless user’s UID and GID to the same values inside the container.

Pele does not erase every deployment concern. Its current package declares Node.js 20 or later, so it remains a Node-based dependency. But it removes the separate browser layer that the Playwright-based route explicitly requires.

Does Mermaid syntax support mean identical diagrams?

No. Pele says it supports every diagram type built into Mermaid 12.1.0, but it also states that its layout and appearance differ. Teams with screenshot tests, regulated document templates or carefully tuned Mermaid themes should treat that warning as central, not incidental.

The compatibility boundary is sensible for most application use. Pele aims to preserve the meaningful graph: nodes, labels and connections. Yet a diagram’s visual layout is also information, especially in sequence charts, architecture diagrams and dense process maps where spacing affects readability.

Pele also deliberately narrows some browser-like behaviour. It uses SVG text rather than HTML labels inside foreignObject, so arbitrary HTML in a label is not retained. It supports links opened by click statements, but parses and ignores JavaScript callback forms.

That makes Pele a better fit when the source language is used as a portable description of a diagram, not as a way to embed interactive page logic. If compatibility means “the same relationships are drawn,” Pele can fit. If it means “the same browser-rendered artwork,” use Mermaid’s own renderer and test the exact version you deploy.

Is Pele’s generated SVG safer to embed?

Pele’s output has a deliberately restricted structure. Its security guidance says returned SVG contains drawing elements, links and images, but no scripts, event handlers, style element, HTML or foreignObject. It also says diagram text is escaped before insertion.

That reduces several common SVG embedding risks. It does not absolve an application from handling untrusted content carefully. Pele warns that icon markup supplied by the host is trusted, internal links contain note names rather than filtered web addresses, and error messages can include diagram source.

The recommended display rule is simple: put rendering errors into textContent, not innerHTML. For teams with an existing SVG sanitizer, Pele’s mounted mode also supports a sanitizer hook before inserting each generated diagram.

Content Security Policy still matters around any SVG embedding strategy. MDN’s CSP reference explains that policies control which resource locations a browser may load, including scripts, styles, images and fonts. Pele’s restricted SVG reduces executable content, but a host page remains responsible for its own link, image and navigation policy.

Who should choose Pele instead of Mermaid CLI?

Choose Pele when diagrams live inside an app, documentation viewer or note system that already has a CSS theme. Its SVG can follow the interface’s colors and fonts, then react to theme changes without rebuilding each diagram.

Choose Mermaid CLI when the desired product is a generated asset: an SVG checked into a repository, a PNG in a report, or a PDF in a publishing pipeline. Mermaid CLI’s documented output formats and file-oriented interface suit those jobs well.

Choose mermaid-isomorphic when visual fidelity to Mermaid’s browser path matters more than avoiding browser infrastructure. Its browser lifecycle management can be worthwhile for a server that already runs Playwright for rendering or testing.

The practical decision is therefore about ownership. Pele owns parsing and layout itself. The other two options run Mermaid’s rendering environment. That is why Pele can offer live CSS-variable theming without a headless browser, and why it cannot promise identical Mermaid geometry.

What we could not verify?

No public benchmark methodology establishes how Pele’s published render times compare across real production diagrams, hardware, Node.js versions or browser environments. An independent benchmark suite using identical diagram sets and disclosed machines could settle that question.

No public compatibility score states how often Pele and Mermaid produce identical geometry, nor is there a published matrix of every syntax edge case beyond the stated Mermaid 12.1.0 target. The Pele maintainers could settle that with versioned conformance results and visual-diff fixtures.

No public roadmap sets the next Pele release date or confirms which Mermaid language additions will be supported next. Future release notes and a maintained compatibility table would answer those questions.

Sources

• Pele homepage
• Pele security guidance
• Pele release history
• Pele repository
• Pele README
• Pele package manifest
• mermaid-isomorphic package documentation
• Podman run reference
• Podman user namespace reference
• MDN Content Security Policy reference