Editing in the diagram

The user can change a Mermaid diagram where it is drawn: double-click a text to edit it, or drag a flowchart's shape to move it. Both go through commands, so each change can be undone and reaches collaborators.
New tab

Text in the diagram

A double click on a text in a Mermaid diagram opens a text field over it, holding that text. Only that text changes in the source.

  • Enter, or leaving the field, writes the text into the source through updateFlowDiagram. An empty or unchanged text writes nothing.
  • Escape closes the field and writes nothing.

A diagram drawn from a table opens no field, because its text belongs to the table. A Diagram Renderer of your own needs editing.

What a double click edits

What opens a field, and how the new text is written, depends on the kind:

KindWhat a double click opensWritten as
FlowchartA shapeid["text"], or label: in id@{ … }. A shape without text gets it at its first mention
FlowchartThe text on an edge-->|"text"|, or -- "text" --> where the edge has that form
SequenceA participant, at the top or the bottomparticipant id as text, declared before its first mention if needed
SequenceA messageThe text after the colon
StateA statestate "text" as id, or the first id : text line
ClassA class nameclass id["text"]. The id stays, so relations and members keep it
Any otherA text that appears once in the sourceThat text, in its place

In any other kind, such as a timeline, a kanban board, a mind map, a journey or a Gantt chart, the extension looks for the clicked text in the source.

The text must appear there exactly once, as a whole item, not as part of a longer text. Otherwise the double click opens no field.

  • A text that appears twice opens nothing, such as a gitGraph branch in branch dev and checkout dev.
  • A text that Mermaid adds, such as a count, is not in the source and opens nothing.
  • A new text with :, ;, ,, |, %, #, ", <, >, brackets or a line break is not written in those kinds, because it would change more than the text. The field closes and the source stays as it was.
  • An edge without text has nothing to double-click. Give it text in the source or with renameMermaidLabel.
  • Edges written as one statement, such as A & B --> C, share their text.
  • A straight double quote in the text becomes a typographic one (“ ”).

Moving shapes

The user can drag a shape of a Mermaid flowchart to move it, in steps of 10 diagram units, the units of the drawn diagram's SVG. On release, the extension writes the offset once through setDiagramNodePosition, so one undo puts the shape back.

resetDiagramPositions puts all shapes back. Dragging an empty spot pans a zoomed-in diagram, see Size and view.

How moved shapes are drawn

Mermaid lays out the diagram from its source, then the extension draws the moved shapes at their offsets, in the editor and in every export.

  • Lines of a moved shape are drawn straight from border to border, with their label in the middle.
  • Lines between shapes that did not move keep their routing.
  • A subgraph's frame stays where the layout put it, even when a shape moves out of it.
  • The diagram grows when a shape moves past its edge.

Where the offsets are kept

The offsets are stored in options.positions as { [nodeId]: { dx, dy } }, by the id the source gives a shape, such as ship in ship[Shipped]. So a change of the source keeps the offsets, renaming an id loses its offset, and an id that is gone moves nothing.

In a diagram drawn from a table, the ids are the step names in lower case, with _ for spaces and punctuation, such as order_in.

Only flowcharts can be moved, not other Mermaid kinds, draw.io or BPMN. A Diagram Renderer of your own needs nodeAt and movePositions.

Lines in a diagram

You style the links of a Mermaid flowchart in its source, with linkStyle. Its number counts the links from 0, in the order they are defined, so a --> b --> c holds two:

flowchart LR
  a --> b --> c
  linkStyle 0 stroke-dasharray: 5 5, stroke-width: 2px

Commands

These commands move the shapes of a Mermaid flowchart. Each returns false and changes nothing without a diagram.

setDiagramNodePosition

Moves one shape of the selected Mermaid flowchart, or the one at pos, away from where the layout puts it.

editor.commands.setDiagramNodePosition({ nodeId: 'ship', dx: 40, dy: 60 })
OptionTypeDefaultDescription
nodeIdstringRequiredThe shape's id, such as ship in ship[Shipped], up to 200 characters
dxnumberRequiredThe horizontal offset in diagram units, rounded to whole units
dynumberRequiredThe vertical offset. 0, 0 puts the shape back
posnumberThe selected diagramThe diagram's position

Returns false for a diagram that is not a Mermaid flowchart, an id with a space or punctuation other than - and _, and an offset that is not a number or beyond 10,000.

resetDiagramPositions

Puts every moved shape back where the layout puts it.

editor.commands.resetDiagramPositions()
OptionTypeDefaultDescription
posnumberThe selected diagramThe diagram's position

Returns false for a diagram without moved shapes.

Without an editor

These functions from @tiptap-pro/extension-diagrams/core work on the source without an editor, such as on a server. This call gives an edge a text, with the edge's id L_<from>_<to>_<n> from the target table:

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

const source = renameMermaidLabel(
  'flowchart LR\n  A[Order] --> B{Paid?}',
  { kind: 'edge', id: 'L_A_B_0' },
  'placed',
)
// 'flowchart LR\n  A[Order] -->|"placed"| B{Paid?}'
FunctionReturns
renameMermaidLabel(source, target, label)The source with that text replaced, or null when the source is not of the target's kind, the target is not in it, or the label is empty
renameMermaidNode(source, nodeId, label)The same with a target of kind 'node'. null for an id with characters other than letters, digits and _, such as my-step
renameMermaidText(source, text, label)The same with a target of kind 'text'
isRenamableMermaidText(source, text)Whether the text appears once in the source, as a complete item
flowDiagramPositions(diagram)The offsets as { [nodeId]: { dx, dy } }, without invalid entries. diagram is an object with options, such as a listDiagrams() entry

The target of renameMermaidLabel is a MermaidLabelTarget, { kind, id }:

kindid
'node'A flowchart shape's id
'edge'A flowchart edge's id, L_<from>_<to>_<n>, where n counts edges between the same two nodes from 0
'participant', 'state', 'class'Its id
'message'Its place among the messages, from '0'
'text'The text itself, in any other kind, appearing once as a complete item