لم تُترجم هذه الصفحة بعد.

Add diagrams, drawings and media

This page is for anyone who writes instructions. You will add a flowchart, a sequence or a workflow without learning a diagram language, draw your own sketch, and point at pictures, documents, video and sound so that both people and the agent understand them.

Every figure is text inside your instruction. People see it drawn in Preview. The agent receives the text, so the words you give a figure matter as much as the picture.

Before you start

  • Who can do this: a Maintainer adds figures directly. A Contributor's figures become suggestions that a Maintainer accepts. A Reader can't add anything.
  • What you need: an instruction open in the editor. Nothing here needs an account or a paid plan.

Add a flowchart, a sequence or a workflow

The editor starts each figure from a small working example that you then change. There are three ways to add one:

  • Between sections: click + where the figure goes, then Figure ▸ Flowchart, Sequence or Workflow.
  • At the start of a line: type / and pick Flowchart, Sequence or Workflow from the list.
  • From the status bar: open Syntax and choose the figure's button.
  1. Add the figure

    Choose Figure ▸ Flowchart. Content gets a short example, and Preview draws it as boxes joined by arrows.

  2. Change the words

    In Content, change the words inside the brackets to your own steps. Each line joins two boxes with an arrow. Words in square brackets are a step; words in curly brackets are a question with more than one way out.

  3. Name it

    The first line, after %%, is the figure's name. Screen readers announce it, and the agent reads it with the rest of the figure, so say what the figure shows.

A flowchart, written in Content and drawn in Preview.

Here is a small decision flowchart for refunds:

Flowchart
```mermaid
%% How a refund request is handled
flowchart TD
  ask[Customer asks for a refund] --> limit{Under the limit?}
  limit -- yes --> refund[Refund it]
  limit -- no --> lead[Send it to the finance lead]
```

What each figure is for:

Figure What it shows
Flowchart A decision: what happens, and which way it goes
Sequence Who talks to whom, in order
Workflow Steps the platform runs, drawn from which step waits for which

While Content is showing, click a flowchart or a sequence in Preview to go to its lines. Preview draws a figure when it scrolls into view. If it can't read the text, it shows the text instead, with "Diagram not drawn:" and the reason.

The agent receives a flowchart or a sequence exactly as written, as text it can read. A workflow is a list of steps that a workflow platform runs. Publishing an instruction with a workflow doesn't run it. See Workflows.

Draw your own sketch

Draw with a mouse, a pen or a finger. Open the drawing pad in any of these ways:

  • Click + between sections, then Figure ▸ Drawing.
  • Type / at the start of a line and pick Drawing.
  • Open the command palette and choose Draw.
  • Open Syntax in the status bar and choose Drawing.
The drawing pad.
  1. Give it a title

    Type what the drawing shows in the field at the top, the one that says "What it shows — the agent reads this". The title is how the agent knows what the drawing is about, and Preview shows it under the drawing.

  2. Draw

    Pick a tool at the bottom and draw on the canvas. Each tool has a letter key.

  3. Insert it

    Choose Insert, or press ⌘Enter (Ctrl+Enter on Windows). The drawing goes in at the caret, and the editor says "Drawing added — the agent receives it as SVG with its title". SVG is a way of writing a picture as text: its lines, boxes and words.

The tools:

Tool Key What it does
Pen P Draws a free line, smoothed as you go
Arrow A Draws a straight arrow from where you press to where you let go
Box R Draws a rectangle
Ellipse O Draws an oval or a circle
Text T Click where the words go, type them, and press Enter. Escape drops them
Eraser E Removes each shape you drag over

Next to the tools:

  • Colour: Ink, Blue, Red, Green or Amber. Ink is the text's own colour, so it stays readable in a light or a dark theme.
  • Thick line draws wider lines.
  • Undo (⌘Z), Redo (⇧⌘Z) and Clear, which removes everything on the canvas.

Insert stays greyed out until the canvas has something on it. If you choose Cancel with strokes you haven't inserted, the editor asks Discard this drawing?: "What you drew isn't in the instruction yet."

Change a drawing

Click the drawing in Preview, or put the caret inside it in Content and choose Draw. The pad opens with the drawing and its title. The button now says Update, and the editor says "Drawing updated" when you choose it.

Add pictures, documents, video and sound

An instruction can point at a picture, a PDF document, a video or a sound file that is already on the web, by its address. The editor doesn't upload files. Each kind has its own block:

Media
::image{src="https://example.com/refund-form.png" alt="The refund form, with the order number at the top right" caption="Where the order number is"}

::video{src="https://example.com/refund-walkthrough.mp4" alt="A two-minute walkthrough of a refund" transcript="https://example.com/refund-walkthrough.txt"}

::pdf{src="https://example.com/refund-policy.pdf" alt="Acme's refund policy" page=3}

::audio{src="https://example.com/greeting.mp3" alt="The greeting callers hear" transcript="https://example.com/greeting.txt"}

Give every one words that stand in for it:

  • alt says what it shows, in a sentence. People who can't see it hear these words, and the agent reads them.
  • caption is a line shown under it.
  • transcript is the address of the words spoken in a video or a sound file.
  • page points at one page of a PDF.

The agent receives each block as text: its kind, its address and your words about it. It doesn't receive the picture or the sound itself. If a rule depends on what a picture shows, say it in the rule's words too.

The editor and instruction.md's own pages don't load pictures, video or sound from other websites. Preview shows each one as a card with your alt text and its address, or "Image not loaded here" when there is no alt text. Drawings and diagrams are always drawn, because they are written inside the instruction.

Add code samples and HTML previews

A code sample is text the agent should copy exactly, such as a reply or a command. In Content, put it between two lines of three backticks. After the first three backticks you can name the language, and add a file name and a caption:

Code samples
```text {filename="reply.txt" caption="The reply the agent sends after a refund"}
Hello Dana, your refund for order A-1042 is on its way.
```

```html
<p>Hello <b>Dana</b>, your refund is on its way.</p>
```

The agent receives a code sample exactly as written. Preview shows it with its file name at the top and its caption under it.

A code sample marked html is also drawn as the page it describes, in a tab called Rendered beside the Code tab. That page is closed off from everything else: it can't run scripts, send forms or reach your account. Pictures inside it load only from secure web addresses.

Check it worked

  • Preview draws each figure, and each drawing shows its title under it.
  • Each picture, video and sound card shows your alt text.
  • View ▸ Contents opens On this page, and its count of figures includes the new ones.

Undo or stop

  • Press ⌘Z (Ctrl+Z on Windows) right after you insert or update a figure.
  • To remove a figure, delete its lines in Content. A figure that has its own block in Preview also has Delete figure in its menu.

If it doesn't work

What you see What to do
"Diagram not drawn:" and a reason A line of the flowchart or sequence can't be read. Undo your last change, or compare your lines with a new Figure ▸ Flowchart
A picture shows as a card, not the picture The editor never loads pictures from other websites. Check that the alt text says what the picture shows
Insert is greyed out in the drawing pad Draw something first
"A code block is never closed, so everything after it is treated as code." Choose Close it in the problems list, or add the closing three backticks
"Claude is writing — draw when it finishes" Claude is changing the instruction. Open the pad again when it is done

For other problems, see Troubleshooting.

Questions

Do I need to know Mermaid to add a flowchart?

No. Mermaid is the small diagram language a flowchart is written in, and the editor starts you from a working example. Change the words in brackets and keep the arrows. See Add a flowchart, a sequence or a workflow.

What does the agent receive for a drawing?

It receives the drawing as text that lists its lines, boxes and words, with your title first. Give every drawing a title that says what it shows. See Draw your own sketch.

Can I upload a picture?

No. A picture, a document, a video or a sound file is added by its web address, and Preview shows it as a card with its alt text. See Add pictures, documents, video and sound.

Does the agent see my pictures?

No. It receives the picture's address and your words about it. Put anything the agent must know in the alt text or in the rule itself.

For developers: Rules and blocks lists every media block and its attributes, and What an agent receives shows how each one is delivered. A website that shows an instruction with the embed can choose to load its pictures.

Last checked against the product:

Was this page helpful? Report a problem