Flow diagrams

The flowDiagram node stores a diagram's text, called the source, in one of three formats:

• Mermaid text, for a flowchart, a sequence diagram, a Gantt chart, a mind map and every other Mermaid kind.
• draw.io XML, for a diagram drawn with shapes in the draw.io editor.
• BPMN XML, for a business process model.

Quick start

Install the package and mermaid.js, the library that draws Mermaid diagrams. The example also uses @tiptap/core and @tiptap/starter-kit. Install them too if your project does not have them yet:

npm install @tiptap-pro/extension-diagrams mermaid

Then register a Diagram Renderer for Mermaid and insert a first diagram:

import { Editor } from '@tiptap/core'
import StarterKit from '@tiptap/starter-kit'
import { Diagrams, chartStyleRules, flowDiagramStyleRules } from '@tiptap-pro/extension-diagrams'
import { mermaidDiagramRenderer } from '@tiptap-pro/extension-diagrams/mermaid'
import rendererUrl from '@tiptap-pro/extension-diagrams/mermaid-renderer?url&no-inline'
import mermaidUrl from 'mermaid/dist/mermaid.min.js?url'

const style = document.createElement('style')
style.textContent = chartStyleRules() + flowDiagramStyleRules()
document.head.append(style)

const editor = new Editor({
  element: document.querySelector('#editor'),
  extensions: [
    StarterKit,
    Diagrams.configure({
      diagramRenderers: [mermaidDiagramRenderer({ mermaidUrl, rendererUrl })],
    }),
  ],
})

editor.commands.insertFlowDiagram({
  source: 'flowchart LR\n  A[Order] --> B{Paid?}\n  B -->|yes| C[Ship]',
  title: 'How an order moves',
})

A Diagram Renderer draws diagrams with one library, as a Renderer draws charts. You pass it in the diagramRenderers option. Mermaid explains mermaidUrl, rendererUrl and the ?url imports.

More about diagrams

Mermaid kinds

The first line of Mermaid source names its kind, such as flowchart or sequenceDiagram. A Mermaid diagram can be any kind that Mermaid 11.17 knows, except five kinds that become charts. MERMAID_DIAGRAM_KINDS lists the kinds, and mermaidDiagramKind(source) returns the kind of a source.

Both Diagram Renderers for Mermaid, mermaid.js and Pele, draw every kind in this list. For a kind that no registered Diagram Renderer draws, see Which Renderer draws a diagram. Editing in the diagram lists the kinds whose text you can change in the diagram.

Diagram or chart

Mermaid pie, xychart, sankey, radar and treemap become a chart node with data you can edit, see importMermaidChart. Every other kind in the list becomes a diagram. insertFlowDiagram and updateFlowDiagram refuse chart source.

How a diagram is stored

The document never stores the drawn diagram, its size on screen or its loading state.

Source is data

The source never runs as code in your app's web page. When a diagram is written, the extension removes %%{init: …}%% directives and the frontmatter block, so a document cannot change how Mermaid runs. A title in the frontmatter becomes the diagram's title, unless you give one. The colors come from your page's CSS, not from the source.

In HTML and plain text

In HTML, a diagram is a <figure data-type="flow-diagram">. It holds its source in <pre><code class="language-mermaid"> and its title in a <figcaption>. A draw.io diagram uses language-drawio, and a BPMN diagram uses language-bpmn.

An HTML or Markdown export made without the extension keeps the source as a code block. If you paste that HTML into an editor that has the extension, you get the diagram back.

As plain text, a Mermaid diagram is [diagram: title] followed by its source. A diagram in any other format is only [diagram: title], or [diagram] without a title.

Changing a diagram

You change a diagram with a command:

editor.commands.updateFlowDiagram({ source: 'sequenceDiagram\n  A->>B: Hello' })
editor.commands.setFlowDiagramView({ view: 'code' })

A form of your own can call updateFlowDiagram on every input, while someone types. Each call is one undo step.

The diagram is drawn again after every change. When a drawing finishes after a newer change, it is dropped. Mermaid source with a syntax error shows the error state and its message until the source is valid again.

Diagram or source for every diagram

Each diagram has its own view. To switch them all at once, as the Mermaid demo does, chain setFlowDiagramView for every diagram:

const chain = editor.chain()
for (const { pos } of editor.storage.diagrams.listDiagrams()) {
  chain.setFlowDiagramView({ pos, view: 'code' })
}
chain.run()

Listing, zooming and exporting diagrams

Listing diagrams

editor.storage.diagrams.listDiagrams() returns every diagram with:

Zoom and maximize

setZoom, getZoom, setMaximized and getMaximized take a diagram's position, as they take a chart's. See Size and view.

Export

export({ pos }), exportAll() and exportDocx() include diagrams as they include charts. In Word, a diagram is a PNG image. Export has the options and what comes back.

The mermaid.js, draw.io and BPMN Diagram Renderers draw only in a browser. On a server, export throws for a diagram, and exportDocx leaves the diagram out with a note. Pele's renderPeleDiagram can still draw Mermaid source on a server.

Commands

insertFlowDiagram

Inserts a diagram at the selection, or at pos, and selects it unless select is false.

editor.commands.insertFlowDiagram({
  source: 'flowchart LR\n  order[Order placed] --> ship[Shipped]',
  title: 'Order flow',
})

An empty paragraph at the selection is replaced. Pasting diagram source runs this command.

Returns false for Mermaid chart source (pie, xychart, sankey, radar, treemap), for a kind not in the list, such as zenuml, and, with format: 'drawio' or 'bpmn', for source that is not that XML.

updateFlowDiagram

Changes the source, the format, the title or the description of the selected diagram, or the one at pos. A field you leave out keeps its value.

editor.commands.updateFlowDiagram({ title: 'Order flow, revised' })

Returns false and changes nothing when the new source is not a kind that is drawn in the diagram's format, or when format changes without source.

setFlowDiagramView

Shows the drawn diagram or its source.

editor.commands.setFlowDiagramView({ view: 'code' })

The view is stored in the document, so everyone who opens the document sees the same view.

convertCodeBlockToDiagram

Replaces the code block at the selection, or at pos, with a diagram of its Mermaid source and selects the diagram.

if (editor.can().convertCodeBlockToDiagram()) editor.commands.convertCodeBlockToDiagram()

Mod-Enter in the code block runs it too, see Mod-Enter in a code block.

Returns false for a code block that holds chart source or anything that is not a Mermaid diagram.