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:
| Kind | First line |
|---|---|
flowchart | flowchart, graph |
sequence | sequenceDiagram |
state | stateDiagram-v2, stateDiagram |
class | classDiagram, classDiagram-v2 |
er | erDiagram |
journey | journey |
gantt | gantt |
mindmap | mindmap |
timeline | timeline |
quadrant | quadrantChart |
git | gitGraph |
kanban | kanban |
architecture | architecture-beta, architecture |
block | block-beta, block |
c4 | C4Context, C4Container, C4Component, C4Dynamic, C4Deployment |
requirement | requirementDiagram, requirement |
packet | packet-beta, packet |
venn | venn-beta |
ishikawa | ishikawa-beta, ishikawa |
treeView | treeView-beta |
wardley | wardley-beta |
cynefin | cynefin-beta |
swimlane | swimlane-beta |
railroad | railroad-beta, railroad-ebnf-beta, railroad-abnf-beta, railroad-peg-beta |
eventModeling | eventmodeling |
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:
| Field | Content |
|---|---|
pos, attributes | Its position, and each attribute as a field, such as source |
kind | The Mermaid kind, or null for empty source, a kind outside the table, or XML |
drawable | Whether a Diagram Renderer for its format can draw the source, false for empty source |
link | The table it is drawn from, or null |
lanes | The 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:
| Attribute | Default | Content |
|---|---|---|
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 |
title | null | The caption below the diagram. Empty text becomes null |
description | null | Alt 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.size | None | The size |
options.link | None | The table it is drawn from |
options.positions | None | The 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',
})| Option | Type | Default | Description |
|---|---|---|---|
source | string | Required | Mermaid source, or the XML of the format. Empty source is allowed |
format | string | 'mermaid' | 'drawio', 'bpmn', or a format a registered Diagram Renderer lists |
title | string | null | null | The diagram's title |
description | string | null | null | Alt text |
pos | number | The selection | The position to insert at |
select | boolean | true | false 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' })| Option | Type | Default | Description |
|---|---|---|---|
source | string | Unchanged | The new source. Moved shapes and size stay. A different source ends a table link |
format | string | Unchanged | The new format. Needs source in that format |
title | string | null | Unchanged | The new title. null removes it |
description | string | null | Unchanged | The new description. null removes it |
pos | number | The selected diagram | The 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' })| Option | Type | Default | Description |
|---|---|---|---|
view | 'diagram' | 'code' | Required | 'diagram' shows the drawn diagram, 'code' shows the source |
pos | number | The selected diagram | The 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()| Option | Type | Default | Description |
|---|---|---|---|
pos | number | The selection | A 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.