Mermaid Renderer
Mermaid runs in a sandboxed iframe, and the editor shows the result as an image, so nothing Mermaid produces runs in your page.
Quick start
npm install mermaidThe Renderer supports Mermaid 11.16.1 and later, and Mermaid 12, which draws some diagrams differently (see Mermaid 12). It refuses an older version and a later major version.
import { Diagrams } from '@tiptap-pro/extension-diagrams'
import { mermaidRenderer } from '@tiptap-pro/extension-diagrams/mermaid'
import mermaidUrl from 'mermaid/dist/mermaid.min.js?url'
import rendererUrl from '@tiptap-pro/extension-diagrams/mermaid-renderer?url&no-inline'
Diagrams.configure({ renderers: [mermaidRenderer({ mermaidUrl, rendererUrl })] })In Vite, ?url gives a file's URL, and no-inline keeps a small file from becoming a data:
URL, which the iframe cannot load. With another bundler, serve mermaid/dist/mermaid.min.js and
dist/mermaid-renderer.js from the installed @tiptap-pro/extension-diagrams as files, and pass
their URLs.
Options
| Option | Type | Default | Description |
|---|---|---|---|
mermaidUrl | string | Required | The URL of Mermaid's single-file build, mermaid/dist/mermaid.min.js, 11.16.1 or later and below 13 |
rendererUrl | string | Required | The URL of @tiptap-pro/extension-diagrams/mermaid-renderer, the script that draws in the iframe |
scriptNonce | string | null | null | The nonce for pages with a nonce-based Content Security Policy |
id | string | 'mermaid' | The id charts store |
label | string | 'Mermaid' | The name for a menu |
Without mermaidUrl or rendererUrl, a chart shows the error "Set mermaidUrl and
rendererUrl to render Mermaid."
Mermaid 12
Mermaid 12 draws some diagrams differently from Mermaid 11, so updating Mermaid changes how
existing diagrams look. This affects the diagrams mermaidDiagramRenderer draws, not the charts
of mermaidRenderer. The documents stay the same, because they store the Mermaid source, not the
drawing.
Flowchart, state, class, ER and requirement diagrams get a different arrangement, because Mermaid 12 places their shapes with the layout library ELK instead of dagre. Shapes in flowcharts and state diagrams are also larger.
To keep the dagre arrangement with Mermaid 12, pass layout: 'dagre' to mermaidDiagramRenderer:
import { Diagrams } from '@tiptap-pro/extension-diagrams'
import { mermaidDiagramRenderer } from '@tiptap-pro/extension-diagrams/mermaid'
import mermaidUrl from 'mermaid/dist/mermaid.min.js?url'
import rendererUrl from '@tiptap-pro/extension-diagrams/mermaid-renderer?url&no-inline'
Diagrams.configure({
diagramRenderers: [mermaidDiagramRenderer({ mermaidUrl, rendererUrl, layout: 'dagre' })],
})The layout option applies to every diagram the Renderer draws. A single diagram cannot choose
its layout, because the extension removes configuration from Mermaid source (see
Source is data). That includes a frontmatter block, the
settings between two --- lines at the start of the source.
A shape the user moved can end up somewhere else among
the other shapes, because Mermaid 12 places the shapes differently. With layout: 'dagre', moved
shapes stay closer to where they were. Without it, check such diagrams after the update.
resetDiagramPositions puts the shapes of a
diagram back where Mermaid places them.
Mermaid 12 includes ELK in mermaid.min.js, under the Eclipse Public License 2.0, so the file
your app serves is about 2 MB larger.
Limits
Mermaid draws no area or scatter charts, so they show what
unavailable returns unless another Renderer draws them.
The Mermaid Renderer declines the charts in this table, so another registered Renderer draws them. When none does, Mermaid draws them as the second column says.
| Chart | Drawn by Mermaid |
|---|---|
| A bar chart with several series | The bars lie on top of each other, without a legend |
A bar chart with spec.orientation: 'horizontal' | The bars stand upright |
A line chart with spec.series set | Plain lines. Mermaid has no dashes, widths, markers or curves |
| A chart with styled grid or axis lines, such as a radar's rings or spokes | Without the styles |
A chart with axes.y.step, axes.x.labels or references | Without them |
| A radar or a treemap with a value below zero | Mermaid reads no minus sign. A radar shows the value at zero, and a treemap leaves it out |
A treemap with a node at the top that has no children, such as Gifts | 30 beside Products / Books | 40 | Such nodes share one top-level group, named after the value column |
Mermaid also draws these charts differently, whatever else is registered:
- A doughnut is drawn as a pie.
- A missing value is drawn as zero in a line or bar chart, and gets no slice in a pie.
- A sankey link that closes a loop is left out, as with the other Renderers.
- A sankey's title is drawn above the chart by the Renderer, because Mermaid draws none.
- A radar's legend is always at the top right.
legend.show: falsehides it.
A double click on a text opens nothing, so users cannot
rename a text in the chart. Export on a server is not possible, because
toSVG needs a browser.
Importing Mermaid
Mermaid pie, xychart, sankey-beta, radar-beta and treemap-beta source becomes a chart
with editable data through importMermaidChart or
pasting. Any chart Renderer that draws the resulting type, such as
treemap, draws it.
Diagrams
mermaidDiagramRenderer, from the same entry point, draws all 25
Mermaid kinds a diagram holds, such as flowchart,
sequence, class, Gantt, mind map and timeline. It takes the options of mermaidRenderer, plus layout:
import { mermaidDiagramRenderer, mermaidRenderer } from '@tiptap-pro/extension-diagrams/mermaid'
Diagrams.configure({
renderers: [mermaidRenderer({ mermaidUrl, rendererUrl })],
diagramRenderers: [mermaidDiagramRenderer({ mermaidUrl, rendererUrl })],
})layout is 'dagre' or 'elk', the layout library for flowchart, state, class, ER
and requirement diagrams. Without it, Mermaid's own default applies: dagre in Mermaid 11 and ELK in
Mermaid 12. Mermaid 11 has only dagre, so 'elk' changes nothing there.
Mermaid 12 says when to set it.
Both Renderers share one sandboxed iframe when they get the same URLs and nonce, so Mermaid loads
once. A diagram takes its colors and font from the --tt-flow-diagram-* custom properties, not
from the source, see Diagrams. Like the chart Renderer, it draws only
in a browser.
Pele is a second Diagram Renderer for Mermaid source. It draws in a Web Worker and also on a server.