Tiptap Docs

Formats

A diagram stores its source in one format, named by its format: Mermaid text, draw.io XML, BPMN XML, or a format a Diagram Renderer of your own lists. This page says what each format holds. What pasted text becomes is on Pasting.
Pro ExtensionAlphaPilot program

The formats

formatSourceDrawn by
'mermaid'Mermaid textmermaid.js or Pele, see Mermaid diagrams
'drawio'draw.io XMLThe draw.io Diagram Renderer, see draw.io diagrams
'bpmn'BPMN 2.0 XML with its layoutThe BPMN Diagram Renderer, see BPMN diagrams
Another idStored as it isA Diagram Renderer that lists it, see Other formats

Mermaid diagrams

A diagram with format: 'mermaid' holds Mermaid text, stored as it is typed. Two Diagram Renderers draw it; register one of them for mermaid, since the first that lists a format draws it.

RendererFromDraws inPicture
mermaidDiagramRenderer@tiptap-pro/extension-diagrams/mermaidA sandboxed iframeThe Mermaid look
peleDiagramRenderer@tiptap-pro/extension-diagrams/peleA Web Worker, without a DOMPele's look: straight edges, about 8 times smaller to load
editor.commands.insertFlowDiagram({ source: 'flowchart LR\n  A --> B', title: 'Order process' })
  • Source starts with a Mermaid kind, such as flowchart or sequenceDiagram. Which kinds a diagram holds is under Mermaid kinds.
  • The same source draws with either Renderer, so switching changes the picture, never the document. See Next to mermaid.js.
  • Pele also draws on a server, for an export without a browser.
  • Pasting Mermaid text, bare or in a ```mermaid fence, gives a Mermaid diagram.

draw.io diagrams

A diagram with format: 'drawio' holds draw.io XML. It is drawn by the draw.io Diagram Renderer, which also connects the draw.io editor for changing it. Its page has a demo.

editor.commands.insertFlowDiagram({ source: drawioXml, format: 'drawio', title: 'Order process' })
  • Source is an <mxfile> or a bare <mxGraphModel>.
  • Stored as an <mxfile> whose pages are plain XML, so the stored text can be read and compared.
  • A bare model becomes a file with one page.
  • A page draw.io compressed is uncompressed.
  • Anything else, and source longer than 1,000,000 characters, makes insertFlowDiagram and updateFlowDiagram return false.
  • Pasting draw.io XML as text gives a draw.io diagram.
  • Changing the format: updateFlowDiagram({ source, format }) changes it, for instance when a Mermaid diagram comes back from the draw.io editor. A new format needs source in it.

BPMN diagrams

A diagram with format: 'bpmn' holds BPMN 2.0 XML with its layout. It is drawn by the BPMN Diagram Renderer, which also connects the bpmn-js modeler for changing it. Its page has a demo.

editor.commands.insertFlowDiagram({ source: bpmnXml, format: 'bpmn', title: 'Payment check' })
  • Source is <definitions> in the BPMN 2.0 model namespace.
  • Stored as written.
  • Anything else, and source longer than 1,000,000 characters, makes insertFlowDiagram and updateFlowDiagram return false.
  • Pasting BPMN XML as text gives a BPMN diagram.

Other formats

  • The id is any id of letters, digits, _ and -, up to 64 characters.
  • Accepted by insertFlowDiagram and updateFlowDiagram when a registered Diagram Renderer lists it in formats.
  • Source is stored as it is, up to 1,000,000 characters.
  • No Renderer draws it: a document that holds such a format keeps it unchanged. The diagram shows what unavailable returns, and its source survives every save.
PreviouslyFlow diagrams