Editing in the diagram

Text in the diagram

In an editable editor, a double click on a text in a Mermaid diagram opens a text field over it. The field holds that text.

• Enter, or leaving the field, writes the text into the source through updateFlowDiagram.
• Escape closes the field without a change.
• Only the text changes. Shapes and lines come from the source.
• A diagram drawn from a table opens no field. Its text belongs to the table.

A Diagram Renderer of your own needs editing for this.

What a double click edits

In any other kind, the extension looks for the clicked text in the source. That covers a timeline's periods and events, a kanban's columns and cards, a mind map's nodes, and a journey's or a Gantt chart's tasks and sections.

The text must appear in the source exactly once, as a complete item, not as part of a longer text. An item starts at the start of a line, after a bracket, a quote, a separator such as : or ,, or after title or section. It ends at a closing bracket, a quote, a separator or the end of the line.

• A text that appears twice opens nothing. In a gitGraph, for example, a branch name appears in branch dev and in checkout dev. A double click on the branch opens no field, and both stay as they are.
• A text that Mermaid adds to the drawn diagram, such as a count, is not in the source. It 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.
• 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

In an editable editor, you can drag a shape of a Mermaid flowchart to move it.

• Dragging an empty spot next to the shapes pans a zoomed-in diagram, see Size and view.
• The offset snaps to steps of 10 units of the diagram.
• When you let go of the pointer, the offset is written once, through setDiagramNodePosition. One undo puts the shape back.
• To put all shapes back, call resetDiagramPositions.

How moved shapes are drawn

Mermaid first lays out the diagram from its source. Then the moved shapes are drawn 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 you move a shape out of it.
• The diagram grows when you move a shape past its edge.

Where the offsets are kept

The offsets are stored per node id in options.positions.

• Renaming the id in the source loses the offset.
• An id that is gone from the source moves nothing.
• A change of the source keeps the offsets.
• Only flowcharts can be moved this way. Shapes of other Mermaid kinds, and draw.io and BPMN diagrams, cannot. A Diagram Renderer of your own needs nodeAt and movePositions.

Lines in a diagram

You style the lines of a Mermaid diagram in its source, with linkStyle. There is no field for them outside the source.

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

Commands

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 })

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

resetDiagramPositions

Puts every moved shape back where the layout puts it.

editor.commands.resetDiagramPositions()

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 or a drawn diagram:

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?}'

target is { kind, id }: