Pele Renderer

The entry point @tiptap-pro/extension-diagrams/pele draws Mermaid diagrams with Pele, a Mermaid renderer by Obsidian. It draws no charts.
New tab

Pele draws in a Web Worker, a background script without access to the page, so it needs no DOM and no sandboxed iframe. It is about 5 times smaller to load than mermaid.js.

Quick start

Install exactly Pele 1.6.0, because editing in the diagram depends on that release:

npm install pele@1.6.0
import { Diagrams } from '@tiptap-pro/extension-diagrams'
import { peleDiagramRenderer } from '@tiptap-pro/extension-diagrams/pele'
import PeleWorker from '@tiptap-pro/extension-diagrams/pele-worker?worker'

Diagrams.configure({
  diagramRenderers: [peleDiagramRenderer({ worker: () => new PeleWorker() })],
})

The entry point /pele-worker is the Worker. Load it with your bundler's way of bundling a Worker, ?worker in Vite. The file imports pele by its package name, so a bundler has to build it: a plain URL to the file in node_modules does not load in a browser. Pele and its code for the 25 Mermaid kinds load only in the Worker, not in your page's bundle. The page's entry point /pele exports PELE_DIAGRAM_KINDS, the list of the kinds, and peleDrawsDiagram(source), which returns whether Pele draws a source.

Options

OptionTypeDefaultDescription
worker() => PeleWorkerPortRequiredStarts a Worker, for the first diagram and after a failure
idstring'pele'Names the Renderer
labelstring'Mermaid (Pele)'The name for a menu

Next to mermaid.js

Both draw the same stored Mermaid source. Register one of them for mermaid, because the first Diagram Renderer for a format draws it.

mermaid.jsPele
Draws inA sandboxed iframeA Web Worker
Size, gzippedAbout 980 kBAbout 205 kB, in the Worker
KindsEvery kind of the listThe same
EdgesCurvesStraight, at right angles
journeyFaces under a timelineScores as a line
mindmapRadialA tree to both sides
Text editing in the diagramDouble click, in every kind that has textThe same
Dragging shapesFlowchartsThe same
On a serverNeeds a browserRuns in Node.js, with renderPeleDiagram

How it draws

Pele writes the colors of the --tt-flow-diagram-* custom properties into the SVG, as mermaid.js does. The editor shows the diagram in an <img>, like every diagram. Labels are SVG text without a foreignObject, so PNG, WebP and Word exports need nothing extra.

  • Links and images in the source are dropped, so click … href and @{ img: … } draw nothing.
  • A source that does not parse shows the error state with Pele's message.
  • A Worker that fails rejects every diagram that was waiting for it. The next diagram starts a new Worker.

On a server

The entry point @tiptap-pro/extension-diagrams/pele-render draws without a page, in Node.js or in a Worker of your own. renderPeleDiagram is synchronous, and throws for a source that does not parse:

import { defaultDiagramTheme } from '@tiptap-pro/extension-diagrams/core'
import { renderPeleDiagram } from '@tiptap-pro/extension-diagrams/pele-render'

const { svg, width, height } = renderPeleDiagram({
  format: 'mermaid',
  source: 'flowchart LR\n  A --> B',
  theme: defaultDiagramTheme,
})

Without a canvas, text widths come from Pele's built-in font metrics, so a diagram can be a few pixels wider or narrower than in the browser.

For a Word image, turn the SVG into a PNG with a rasterizer such as resvg. toPeleVariables(theme), from the same entry point, returns the CSS variables that Pele's SVG uses for a theme.

Editing in the diagram

Users edit a diagram Pele drew as one mermaid.js drew. peleDiagramRenderer already includes peleDiagramEditing, so there is nothing to add. See Editing in the diagram.

  • A double click opens the same texts as with mermaid.js, see What a double click edits.
  • Dragging a flowchart's shape stores the same offset as with mermaid.js. The edges of a moved shape are drawn straight from border to border, with their arrowheads turned and their text in the middle.
  • Everything else stays where Pele drew it, including a subgraph's frame, because Pele does not lay out the diagram again.