API

Pele exports four functions and one error class. Every function is synchronous, except the optional ones that load diagram types on demand. The API is not final and is subject to change before a stable release.

import { render, parse, detectType, supports, PeleError } from 'pele';

Usage

Pass 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() throws when the text cannot be rendered. Check supports() first to decide whether Pele can handle a diagram, and catch PeleError to report syntax errors.

import { PeleError, render, supports } from 'pele';function draw(source: string, element: HTMLElement) {  if (!supports(source)) return false;  try {    element.innerHTML = render(source).svg;  } catch (error) {    if (!(error instanceof PeleError)) throw error;    element.textContent = error.message;  }  return true;}

An error message quotes the diagram source, so show it as text. Security lists what else an app that displays untrusted diagrams should take care of.

Pele is in early development and has not had a stable release. Every diagram type built into Mermaid is implemented. See Examples for what they look like and Compatibility for the full list.

Loading only what you need

The main entry point includes every diagram type. An app that draws only a few types, or wants to fetch each type when it is first used, can import smaller pieces.

Choose the types up front:

import { register, render } from 'pele/core';import flowchart from 'pele/diagrams/flowchart';import sequence from 'pele/diagrams/sequence';register(flowchart, sequence);const { svg } = render(source);

Or let Pele fetch each type the first time a diagram needs it. renderAsync() takes the same arguments as render() and returns a promise.

import { renderAsync } from 'pele/lazy';const { svg } = await renderAsync(source);

load(type) fetches one type without rendering, and resolves to false for a type Pele does not draw. Once a type is loaded, render() from the same module draws it synchronously.

import { detectType, load, render } from 'pele/lazy';await load(detectType(source));const { svg } = render(source);

With core and lazy, supports() is true only for types that are registered or loaded. Use one of these entry points throughout an app. The main entry point keeps its own separate list of types.

render

function render(text: string, options?: RenderOptions): RenderResult

Parses Mermaid text, lays out the diagram, and returns it as an SVG string. Throws a PeleError if the text cannot be rendered.

const result = render('flowchart TD\n  A --> B', { idPrefix: 'note-1-' });container.innerHTML = result.svg;

The same text, options, and font measurements always produce the same SVG.

RenderOptions

All options are optional.

RenderResult

Each LinkInfo has the id of the node that carries the link, its href, and internal. A node with a click link is reported with internal: false. A node with the class internal-link is reported with internal: true and its label text as the href. An address that is not allowed is reported as about:blank.

parse

function parse(text: string, options?: { limit?: number }): DiagramModel

Parses Mermaid text and returns the diagram model without laying it out or rendering it. Throws a PeleError for unsupported diagram types and syntax errors.

For a flowchart, the model has direction, nodes, edges, subgraphs, classes, and tooltips, along with title, accTitle, and accDescr when the source sets them. The exact shape of the model is subject to change.

const model = parse('flowchart LR\n  A[Start] --> B[End]');model.direction;        // 'LR'model.nodes.get('A');   // { id: 'A', text: 'Start', … }model.edges.length;     // 1

detectType

function detectType(text: string): DiagramType | null

Returns the diagram type that the text declares, or null if it is not a Mermaid diagram. Frontmatter, directives, and comments before the declaration are skipped.

detectType() recognizes every Mermaid diagram keyword, including types Pele cannot render yet. 'flowchart', 'sequence', 'class', 'state', 'er', 'pie', and 'gantt' are some of the values it returns.

detectType('graph TD\n  A --> B');           // 'flowchart'detectType('sequenceDiagram\n  A->>B: Hi');  // 'sequence'detectType('Hello');                         // null

supports

function supports(text: string): boolean

Returns true if the text declares a diagram type that Pele can render. It does not check the rest of the syntax, so render() can still throw a syntax error for text that supports() accepts.

supports('flowchart LR\n  A --> B');         // truesupports('sequenceDiagram\n  A->>B: Hi');    // false

PeleError

render() and parse() throw a PeleError when they cannot handle the text. It extends Error.

Error codes

try {  render(source);} catch (error) {  if (error instanceof PeleError && error.code === 'syntax') {    console.log(`Line ${error.line}, column ${error.column}`);    console.log(error.snippet);  }}

Text measurement

Pele sizes nodes from the measured width of their labels. In a browser it measures with a canvas, using the fontFamily option. Without a canvas, such as in Node.js, it estimates widths from a built-in table of sans-serif metrics.

Pass a measurer to supply your own measurements. This interface is subject to change.

interface TextMeasurer {  width(text: string, size: number, style: number): number;}