Mermaid Renderer

The Mermaid Renderer draws pie, doughnut, line, bar, sankey, radar and treemap charts with Mermaid, a library that draws charts and diagrams from text. A second Renderer from the same entry point draws Mermaid diagrams.

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 mermaid

The 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

OptionTypeDefaultDescription
mermaidUrlstringRequiredThe URL of Mermaid's single-file build, mermaid/dist/mermaid.min.js, 11.16.1 or later and below 13
rendererUrlstringRequiredThe URL of @tiptap-pro/extension-diagrams/mermaid-renderer, the script that draws in the iframe
scriptNoncestring | nullnullThe nonce for pages with a nonce-based Content Security Policy
idstring'mermaid'The id charts store
labelstring'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.

ChartDrawn by Mermaid
A bar chart with several seriesThe 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 setPlain lines. Mermaid has no dashes, widths, markers or curves
A chart with styled grid or axis lines, such as a radar's rings or spokesWithout the styles
A chart with axes.y.step, axes.x.labels or referencesWithout them
A radar or a treemap with a value below zeroMermaid 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 | 40Such 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: false hides 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.