Flow diagrams

A flow diagram shows steps, states or things and the links between them, such as a flowchart or a sequence diagram. It is written as text that the Diagrams extension draws, so it stays editable. Every change can be undone.
New tab

The flowDiagram node stores that text, called the source. It is Mermaid text, which writes a diagram as lines such as A --> B, draw.io XML, or BPMN 2.0 XML for a business process, see Formats.

Quick start

A diagram needs a Diagram Renderer, which draws it with one library. This one is for Mermaid and needs the mermaid package. Install Diagrams has the registry access, and the ?url imports are the form Vite reads:

import { Diagrams } 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 diagrams = Diagrams.configure({
  diagramRenderers: [mermaidDiagramRenderer({ mermaidUrl, rendererUrl })],
})

With diagrams in the extensions of new Editor(), this inserts a flowchart captioned "How an order moves":

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

A first diagram has the complete editor. Mermaid explains mermaidUrl and rendererUrl, and other bundlers.

More about diagrams

Editing in the diagram covers changing a text and moving shapes, A diagram from a table a flowchart drawn from a table, and Renderers which Diagram Renderer draws what.

Mermaid kinds

The first line of Mermaid source names its kind, such as flowchart or sequenceDiagram. A diagram can hold any kind Mermaid 11.17 knows, except five that become charts:

KindFirst line
flowchartflowchart, graph
sequencesequenceDiagram
statestateDiagram-v2, stateDiagram
classclassDiagram, classDiagram-v2
ererDiagram
journeyjourney
ganttgantt
mindmapmindmap
timelinetimeline
quadrantquadrantChart
gitgitGraph
kanbankanban
architecturearchitecture-beta, architecture
blockblock-beta, block
c4C4Context, C4Container, C4Component, C4Dynamic, C4Deployment
requirementrequirementDiagram, requirement
packetpacket-beta, packet
vennvenn-beta
ishikawaishikawa-beta, ishikawa
treeViewtreeView-beta
wardleywardley-beta
cynefincynefin-beta
swimlaneswimlane-beta
railroadrailroad-beta, railroad-ebnf-beta, railroad-abnf-beta, railroad-peg-beta
eventModelingeventmodeling

The Kind column is the kind that listDiagrams() returns. MERMAID_DIAGRAM_KINDS, from @tiptap-pro/extension-diagrams, holds this table. mermaidDiagramKind(source), from @tiptap-pro/extension-diagrams/core, returns a source's kind, or null.

mermaid.js and Pele, a Mermaid renderer that runs in a Web Worker, draw these kinds. For a kind outside the table, see Which Renderer draws a diagram.

Diagram or chart

Mermaid pie, xychart, sankey-beta, radar-beta and treemap-beta become a chart node with editable data, see importMermaidChart. The diagram commands refuse that source.

Changing a diagram

updateFlowDiagram changes a diagram's source or title, and setFlowDiagramView switches between drawing and source. When a form calls updateFlowDiagram on every input, undo merges changes made within 500 ms into one step.

The extension draws the diagram again after every change, so it shows the latest source. With lazyRendering, on by default, a diagram away from the viewport is drawn again when it comes near. Mermaid source with a syntax error shows its error message until it is valid.

Diagram or source for every diagram

To switch the view of every diagram, chain setFlowDiagramView. A view change moves no diagram, so the positions stay valid:

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

Listing diagrams

editor.storage.diagrams.listDiagrams() returns every diagram in document order:

FieldContent
pos, attributesIts position, and each attribute as a field, such as source
kindThe Mermaid kind, or null for empty source, a kind outside the table, or XML
drawableWhether a Diagram Renderer for its format can draw the source, false for empty source
linkThe table it is drawn from, or null
lanesThe lane names of a diagram drawn from a table, otherwise empty

Zoom and maximize

setZoom, getZoom and setMaximized in editor.storage.diagrams take a diagram's { pos }. getMaximized() returns the maximized chart's or diagram's position, or null.

Export

Export includes diagrams, and in Word a diagram is a PNG image. The mermaid.js, draw.io and BPMN Diagram Renderers draw only in a browser. So on a server, editor.storage.diagrams.export() throws for a diagram, and exportDocx() leaves it out and says so in its notes. Pele's renderPeleDiagram can draw Mermaid there.

How a diagram is stored

The flowDiagram node has these attributes:

AttributeDefaultContent
format'mermaid''mermaid', 'drawio', 'bpmn' or the id of a format a Diagram Renderer draws
source''The Mermaid text, or the XML. Longer Mermaid text is cut to 50,000 characters
titlenullThe caption below the diagram. Empty text becomes null
descriptionnullAlt text and accessible description
view'diagram''diagram' or 'code', see setFlowDiagramView
options{}Keys of your own are kept. The extension sets the next three
options.sizeNoneThe size
options.linkNoneThe table it is drawn from
options.positionsNoneThe offsets of moved shapes

The document does not store the drawn diagram, its size on screen or its loading state.

Source is data

The source does not run as code in your app's web page. When a command writes it, the extension removes %%{…}%% directives, such as %%{init: …}%%, and the frontmatter block, which could change how Mermaid runs.

A frontmatter title becomes the title unless you give one. Colors come from the --tt-flow-diagram-* custom properties in Diagram drawing.

In HTML and plain text

In HTML, a diagram is a <figure data-type="flow-diagram"> with its source in <pre><code class="language-mermaid">, or language-drawio or language-bpmn, and its title in a <figcaption>. Without the extension, the source stays a code block, and pasting that HTML back gives the diagram.

As plain text, a Mermaid diagram is [diagram: title] and its source, or only the source without a title. Any other format is only [diagram: title], or [diagram].

Commands

Each of these commands returns false and changes nothing when it cannot act.

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',
})
OptionTypeDefaultDescription
sourcestringRequiredMermaid source, or the XML of the format. Empty source is allowed
formatstring'mermaid''drawio', 'bpmn', or a format a registered Diagram Renderer lists
titlestring | nullnullThe diagram's title
descriptionstring | nullnullAlt text
posnumberThe selectionThe position to insert at
selectbooleantruefalse leaves the selection where it is

The diagram replaces an empty paragraph or selected text, and goes after a selected node. Pasting diagram source outside a code block runs this command.

Returns false for chart source, a kind outside the table such as zenuml, source that is not the XML of its format, and source over 1,000,000 characters. Longer Mermaid source is cut to 50,000.

updateFlowDiagram

Changes the source, format, title or description of the selected diagram, or the one at pos.

editor.commands.updateFlowDiagram({ title: 'Order flow, revised' })
OptionTypeDefaultDescription
sourcestringUnchangedThe new source. Moved shapes and size stay. A different source ends a table link
formatstringUnchangedThe new format. Needs source in that format
titlestring | nullUnchangedThe new title. null removes it
descriptionstring | nullUnchangedThe new description. null removes it
posnumberThe selected diagramThe diagram's position

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

setFlowDiagramView

Shows the drawn diagram or its source. The view is stored, so everyone sees the same one.

editor.commands.setFlowDiagramView({ view: 'code' })
OptionTypeDefaultDescription
view'diagram' | 'code'Required'diagram' shows the drawn diagram, 'code' shows the source
posnumberThe selected diagramThe diagram's position

Returns false without a diagram.

convertCodeBlockToDiagram

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

if (editor.can().convertCodeBlockToDiagram()) editor.commands.convertCodeBlockToDiagram()
OptionTypeDefaultDescription
posnumberThe selectionA position inside the code block

Mod-Enter in a code block runs it too.

Returns false for chart source and anything that is not a Mermaid diagram.