Skip to content

Render diagrams with Mermaid

Draw the mermaid fences a model writes as diagrams, while the reply streams, with @aparte/plugin-mermaid.

On this page
Open
A flowchart redrawn as its fence streams.
bash
npm install @aparte/plugin-mermaid mermaid
ts
import { setupMermaid } from '@aparte/plugin-mermaid';

setupMermaid();

Every ```mermaid fence in a reply is drawn by Mermaid — with any Markdown provider, or none, because every fence in a streamed reply is already a block of its own. Mermaid is loaded on the first diagram, and a diagram is drawn only once it comes near the screen, so reopening a long conversation stays fast.

The diagram is drawn as its fence arrives, and redrawn at most every 300 ms — or as long as the last drawing took, if longer — keeping the last version that parsed. Until the first version parses, the source shows. Once the fence closes, a diagram that does not parse shows a short note and its source. A drawn diagram keeps its code card, so the copy button copies its source, ready to paste or edit. Its alt text comes from the diagram’s own accTitle and accDescr, so ask the model to write them.

An image, so nothing in it can act on the page

Section titled “An image, so nothing in it can act on the page”

Each diagram is an <img> of its SVG. A browser draws an image’s SVG with no scripts and no access to the page, so neither a label a model wrote nor a style inside the diagram can act on the chat around it. Mermaid also runs with securityLevel: 'strict' and HTML labels off, and a diagram’s own %%{init}%% cannot turn either back on.

Mermaid draws before that image exists, in the page, and what a diagram names there is fetched at that moment. Three things name a picture. A node’s or an actor’s own: A@{ shape: imageSquare, img: "https://…" } or a sequence diagram’s properties A: {"icon": "https://…"} would send a request to that address, so the plugin asks Mermaid what it parsed, and a diagram holding a picture that is not inline (data:image/…) is not drawn, however the source spelled it. A label Mermaid writes as HTML even with HTML labels off, such as an architecture service’s icon text: it goes through Mermaid’s own sanitizer with pictures, players, frames and styles forbidden, a rule a diagram’s %%{init}%% cannot lift. And a style: classDef c mask-image:url(https://…) in a state or block diagram is fetched as soon as the diagram is measured, so a source holding a CSS url(, image-set( or cross-fade( (or an @import) is not drawn, nor is one that styles something and holds a backslash escape, which could spell one. A diagram that is not drawn shows its source and the note that it could not be drawn. A Mermaid object that cannot be asked what it parsed (setupMermaidWith with your own) falls back to refusing on the text alone, which also refuses a label saying “img” in a diagram with shape data and a sequence diagram using the word properties or details.

The cost: the text in a diagram cannot be selected, and it is set in the system fonts, since an image cannot load the page’s.

The diagram takes its colours from the chat’s theme — --aparte-bg, --aparte-text, --aparte-primary and their neighbours — and is drawn again when the theme changes. Its alt text is the diagram’s own accTitle or accDescr, else “Diagram”. To translate the fallback and the error note:

ts
import { aparteGlobalConfig } from '@aparte/core';

aparteGlobalConfig.extendLocale({ diagramAlt: 'Diagramme', diagramError: 'Ce diagramme ne peut pas être dessiné.' });

@aparte/plugin-mermaid/core imports nothing from mermaid: hand it the instance, or a function that loads it.

ts
import mermaid from 'mermaid';
import { setupMermaidWith } from '@aparte/plugin-mermaid/core';

setupMermaidWith(mermaid, { progressive: false, mermaid: { flowchart: { curve: 'basis' } } });

MermaidOptions takes progressive (false draws a diagram once its fence has closed) and mermaid, Mermaid’s own configuration under the keys the plugin keeps. Any object shaped like MermaidLike will do. Both setups return a function that removes the renderer.

Mermaid keeps one configuration for the whole page, and the plugin calls initialize with its own before every diagram it draws. If your page also draws diagrams of its own with the same Mermaid, call mermaid.initialize(yourConfig) again before your own render() or run():

ts
import mermaid from 'mermaid';

mermaid.initialize({ startOnLoad: false, theme: 'dark' });
await mermaid.run({ querySelector: '.my-diagrams' });