Add Mermaid diagrams

Mermaid renders diagrams from text stored in the document. Edit the source to change the diagram without uploading an image.

Before you start

You need permission to edit the document. Members of the owning team can edit both the prose and the diagram source. Viewing a diagram does not grant access to a document outside your team.

Diagrams do not have a free-form canvas or draggable shapes. Describe the relationships in Mermaid source.

Before replacing a complicated existing diagram, create a checkpoint with Version and Create version. See versions if you need to return the entire document to that state later.

Insert a diagram

1. Place the cursor where the diagram belongs in the body.
2. Type / and choose Diagram.
3. Replace the example source with the flow you want to describe.
4. Move the selection out of the source and use Show diagram to inspect the picture.

The example is a sequence diagram with a Ping from Alice to Bob and a Pong reply.

For example, replace the starter with this sequence:

sequenceDiagram
	Customer->>App: Submit request
	App->>Worker: Queue task
	Worker-->>App: Report result
	App-->>Customer: Show result

Switch between source and picture

Use Show source when you want to edit an existing diagram. Use Show diagram when you want to read its rendered form.

The editor swaps between those views instead of stacking two copies of the diagram. When the cursor or selection remains inside the code block, the source stays visible so you do not type into hidden text. A block without a rendered picture also keeps its source reachable.

A Mermaid diagram is a code block whose language is mermaid, including in Markdown exports. The slash menu's Diagram command creates that block. The block selector identifies it as a code block. The rendered picture is not a separate attachment.

Open a detailed diagram

Click the rendered diagram to open its larger view. The same action is available as Open the diagram to keyboard and assistive-technology users.

Return to the document to edit the source. Opening the larger view does not change the diagram or surrounding prose.

Fix a rendering error

If Mermaid cannot render the source, Livemark displays Diagram error: followed by the error's first line. Correct the source and check again.

The last successfully rendered picture can remain visible while the source has errors. After correcting the source, check the new render.

If the diagram looks right but contradicts the prose, select the relevant passage and start a comment. For AI help rewriting the source, specify whether to apply the edit or leave a suggestion for review.

Continue with editing for other block types and reviews when the document needs a readiness decision.