Flow diagrams

Quick start

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({
  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.
• Mermaid draws in a sandboxed iframe. mermaidUrl and rendererUrl are the two files it loads.
• The ?url imports are Vite's. With another bundler, serve both files and pass their URLs.
• The Mermaid charts and diagrams share one iframe. See Mermaid.

More about diagrams

Mermaid kinds

A Mermaid diagram holds any kind Mermaid 11.17 knows, except the five that are charts. The first line names it. MERMAID_DIAGRAM_KINDS lists them, and mermaidDiagramKind(source) reads the kind.

• Which kinds a picture shows is up to the Diagram Renderer. The Mermaid and the Pele Renderer draw every kind in the list.
• A kind no registered Renderer draws shows what unavailable returns, with the reason 'unsupported-kind'. Its source stays in the document.
• Editing in the picture works in the kinds listed in Editing in the picture. The others are only shown.

Diagram or chart

• Mermaid pie, xychart, sankey, radar and treemap are charts. They become a chart with data you can edit; see importMermaidChart.
• Every other kind in the list becomes a diagram.
• Chart source, and a kind not in that list such as zenuml, make insertFlowDiagram and updateFlowDiagram return false.
• Empty source is allowed, for a diagram still to be written.

How a diagram is stored

The picture, its size and its loading state are never stored.

Source is data

• The source is data, never code that runs in the page.
• %%{init: …}%% directives are removed when a diagram is written.
• The config of a frontmatter block is removed too, so a document cannot change how Mermaid runs.
• A title in the frontmatter becomes the diagram's title, unless one is given.
• The colors come from the page, not from the source.

In HTML and plain text

• HTML: a diagram is a <figure data-type="flow-diagram">. It holds its source in <pre><code class="language-mermaid"> (language-drawio for draw.io, language-bpmn for BPMN) and its title as <figcaption>.
• Plain text: a diagram that is not Mermaid is only its title.
• Export without the Extension: an HTML or Markdown export keeps the source as a code block.
• Pasting that HTML into an editor with the Extension gives the diagram back.

Changing a diagram

Every change is a Command, see Commands.

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

• Writing while someone types: a form can call updateFlowDiagram on every input. Each call is one undo step.
• Redrawing: the picture is drawn again for every change.
• A drawing that finishes after a newer change is dropped.
• Mermaid source with a syntax error shows the error state and its message until the source is valid again.

Picture or source for every diagram

The view belongs to each diagram. For one switch over the whole document, as in the Mermaid demo, call setFlowDiagramView for every diagram in one chain:

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

Readers, zoom and export

Listing diagrams

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

Zoom and maximize

Zoom and maximize work on a diagram as on a chart: setZoom, getZoom, setMaximized and getMaximized take its position.

Export

Diagrams are exported like charts; Export has the options and what comes back.

• export({ pos }) draws a diagram as SVG, PNG, WebP or JPEG.
• exportAll() includes diagrams, in document order.
• exportDocx() places a diagram in the Word document as a PNG picture with its title as caption, between the native charts. It adds a note to notes that it is a picture there.
• On a server: the mermaid.js, draw.io and BPMN Diagram Renderers draw only in a browser. export throws for a diagram, and exportDocx leaves it out with a note. Mermaid source can still be drawn there with Pele's renderPeleDiagram.

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 Mermaid diagram source, draw.io XML or BPMN XML calls it.

Returns false for Mermaid chart source (pie, xychart, sankey, radar, treemap), for a kind not in the list, 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 left out keeps its value.

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

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

setFlowDiagramView

Shows the picture or the source of a diagram.

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

The view is stored, so every reader of the document sees the same.

convertCodeBlockToDiagram

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

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

• editor.can().convertCodeBlockToDiagram() says whether to offer it.
• Mod-Enter in the code block runs it too, unless codeBlockShortcut says otherwise.

Returns false for a code block holding chart source or anything else.