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:
| Kind | What a double click opens | Written as |
|---|---|---|
| Flowchart | A shape | id["text"], or label: in id@{ … }. A shape without text gets it at its first mention |
| Flowchart | The text on an edge | -->|"text"|, or -- "text" --> where the edge has that form |
| Sequence | A participant, at the top or the bottom | participant id as text, declared before its first mention if needed |
| Sequence | A message | The text after the colon |
| State | A state | state "text" as id, or the first id : text line |
| Class | A class name | class id["text"]. The id stays, so relations and members keep it |
| Any other | A text that appears once in the source | That 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 devandcheckout 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: 2pxCommands
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 })| Option | Type | Default | Description |
|---|---|---|---|
nodeId | string | Required | The shape's id, such as ship in ship[Shipped], up to 200 characters |
dx | number | Required | The horizontal offset in diagram units, rounded to whole units |
dy | number | Required | The vertical offset. 0, 0 puts the shape back |
pos | number | The selected diagram | The 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()| Option | Type | Default | Description |
|---|---|---|---|
pos | number | The selected diagram | The 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?}'| Function | Returns |
|---|---|
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 }:
kind | id |
|---|---|
'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 |