Pasting

When the user pastes Mermaid, draw.io XML or BPMN XML into the document, the extension turns the text into a chart or a diagram, and rows pasted onto a selected chart become its new data. The editor from A first chart does this without more setup.
New tab

What pasted text becomes

Mermaid is a language that describes charts and diagrams as text. Pasted text becomes:

Pasted textBecomes
Rows, as in the Chart syntax, or CSV with at least two columnsNo chart: they paste as they would without the extension. insertFromText or the Quick Input makes a chart of them
A Mermaid chart, such as pie or sankey-betaA chart (importMermaidChart)
Any other Mermaid kindA diagram (Formats)
draw.io XML or BPMN XMLA diagram (Formats)
Rows from a spreadsheet, while a chart is selectedThat chart's new data, see Onto a selected chart
Anything, into a code blockThe text, unchanged

How pasted text is read

The extension finds pasted Mermaid bare, in a ```mermaid fence, or as a code block with the language mermaid. Bare Mermaid needs its kind, such as flowchart, on the first line, and more than one line, so a sentence that starts with "pie" stays a sentence.

A code block that already holds diagram source becomes the diagram with convertCodeBlockToDiagram, or with Mod-Enter.

Detecting text in a field of your own

detectDiagramInput tells you what text from a field outside the editor would become.

detectDiagramInput

detectDiagramInput(text, options?) returns { kind, source }, or null.

import { detectDiagramInput } from '@tiptap-pro/extension-diagrams'

const detected = detectDiagramInput(text)
if (detected?.kind === 'mermaid-diagram')
  editor.commands.insertFlowDiagram({ source: detected.source })
kindTextCommand to call
'mermaid-chart'A Mermaid chart, such as pie or sankey-beta, with at least one rowimportMermaidChart({ source })
'mermaid-diagram'Any other Mermaid kind, on more than one line or in a fenceinsertFlowDiagram({ source })
'drawio'An <mxfile> or <mxGraphModel>insertFlowDiagram({ source, format: 'drawio' })
'bpmn'BPMN 2.0 <definitions>insertFlowDiagram({ source, format: 'bpmn' })
'chart-syntax'Rows with a delimiter, as the Chart syntax or CSV, with at least two columns, not a single columninsertChartFrom({ format: 'chart-syntax', content: source })
  • source is the text, trimmed, with a ```mermaid fence removed.
  • A sentence, a lone Mermaid keyword, XML that cannot be read and a fence of another language return null.
  • With custom delimiters or decimalSeparator options, pass the same values: detectDiagramInput(text, { delimiters, decimalSeparator }).
  • insertFromText acts on every kind. A paste acts on all but 'chart-syntax'.

Onto a selected chart

Spreadsheet apps copy rows as tab-separated lines. A paste counts as rows with a header, at least one row, and a tab on every line. Comma-separated text or a single line pastes as usual, also onto a selected chart.

  • When a chart is selected, the pasted rows replace its data and keep its spec, through updateChartFromGrid.
  • When the selected chart is read-only, the paste changes nothing.
  • Anywhere else, the rows paste as they would without the extension.

Commands

insertFromText

Inserts a chart or a diagram from a text, read with detectDiagramInput and the editor's delimiters and decimalSeparator. Unlike a paste, it also makes a chart from rows.

editor.commands.insertFromText({ text: 'Month | Sales\nJan | 2\nFeb | 3' })
OptionTypeDefaultDescription
textstringRequiredThe text, as it would be pasted
posnumberThe selectionThe position to insert at

Returns false for text that is neither a chart nor a diagram, or without the node it would become.