What pasted text becomes
Mermaid is a language that describes charts and diagrams as text. Pasted text becomes:
| Pasted text | Becomes |
|---|---|
| Rows, as in the Chart syntax, or CSV with at least two columns | No 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-beta | A chart (importMermaidChart) |
| Any other Mermaid kind | A diagram (Formats) |
| draw.io XML or BPMN XML | A diagram (Formats) |
| Rows from a spreadsheet, while a chart is selected | That chart's new data, see Onto a selected chart |
| Anything, into a code block | The 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 })kind | Text | Command to call |
|---|---|---|
'mermaid-chart' | A Mermaid chart, such as pie or sankey-beta, with at least one row | importMermaidChart({ source }) |
'mermaid-diagram' | Any other Mermaid kind, on more than one line or in a fence | insertFlowDiagram({ 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 column | insertChartFrom({ format: 'chart-syntax', content: source }) |
sourceis the text, trimmed, with a```mermaidfence removed.- A sentence, a lone Mermaid keyword, XML that cannot be read and a fence of another language
return
null. - With custom
delimitersordecimalSeparatoroptions, pass the same values:detectDiagramInput(text, { delimiters, decimalSeparator }). insertFromTextacts on everykind. 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' })| Option | Type | Default | Description |
|---|---|---|---|
text | string | Required | The text, as it would be pasted |
pos | number | The selection | The position to insert at |
Returns false for text that is neither a chart nor a diagram, or without the node it would
become.