Yard Docs
Sign in
On this page

Notes

Write notes made of blocks, attach images, files and links, and move pieces between notes and the canvas.

Updated November 6, 2026 · 9 min read

In the workspace, notes are placed in docs (see docs), and a doc itself is written like a note, with / for Blocks. On a sheet (listed under Resources, or a project's), notes are blocks as described here.

A note is a page of text on a canvas. It is made of blocks in order: paragraphs, headings, lists, to-dos, quotes, code, dividers, and attachments such as an image, a file or a link card. Each note is saved as a Markdown file in the workspace, so agents can read and write it too.

Writing a note

Choose Add in the canvas toolbar, then Note, upload or link (or press N), or paste text onto the canvas. A new note opens straight away with the caret in its title: an empty title and an empty line under it say "Title" and "Write something…" until you type, on the canvas too. On the canvas a note shows its text, but you do not type there: a click selects it. Double-click it, press Enter, or choose Edit in its action bar, and the note opens in a large panel over the canvas. Close, Esc or a click outside the panel puts it away. On a narrow screen the note takes the whole canvas. When a note's text is longer than its block, scroll it with the wheel once it is selected, or on a touch screen swipe up and down on the text.

Under the text, Add text, Add heading, Add list, Add to-do and Add image or file add a block at the end. Close or Esc puts the note away.

Formatting

Select some text and a small toolbar appears with Bold, Italic, Code and Link (type or paste the address, then Add). On a link, the same button says Unlink.

Typing or pasting a full address that starts with https://, http:// or mailto: makes a link on its own. A bare name such as spec.md or example.com stays plain text, the same way the note's Markdown file reads it. A link you removed with Unlink stays removed as you type on.

The slash menu

Type / at the start of an empty line to choose what the line becomes: Text, Heading 1, Heading 2, Heading 3, Bulleted list, Numbered list, To-do, Quote, Code, Divider, Schema, Image or file, and Reference a block…. Keep typing to filter the list, use the arrow keys and Enter to pick, or Esc to close it. These block options only appear on an otherwise empty line; a / inside a word (a/b) opens nothing.

In a doc the menu starts with Blocks (Decisions, Schema, Cards, Image or video, File, Code from a repository, Link, Project and Table; see docs), and Schema is listed there instead. On a Table block the handle's menu has Add row, Add column, Delete last row and Delete last column.

In a project's spec or a doc, / also opens after a space in a line of text, for a mention: "See /repo" offers Mention a repository…, and the repository you pick goes in the line where the / was.

Schemas

A Schema block shows a data model as tables: each table has a name, a line on what it holds, and its fields with their type, constraints and a note. Keys (pk) and references to another table (→ users) are tagged. Click a cell to change it; Enter keeps the change and Esc puts back what was there. Add a field, Add a table and the remove buttons that show on hover change the rest. A schema works in notes, docs and a project's spec, and agents write their plans' tables, payloads and config files as one instead of nested lists.

A schema starts folded, so a big data model does not push the rest of the page down: a table of more than four fields shows its first three and Show all N fields, and Show all in the block's header opens every table. Show fewer folds them again. A schema of one table with six fields or fewer is shown in full. Folding only changes what you see: it is not saved, so the schema is folded again the next time it is shown, and Add a field opens its table. A printed or exported page has every field.

In the Markdown file it is a fence named schema, a ## name | note line per table and a name | type | constraints | note line per field:

Code
```schema
## users | Who signs in
email | text | unique, not null | Sign-in address
password_hash | text | | argon2id
```

A schema fence that does not read this way (a Prisma model, a JSON schema) stays a code block. In a chat reply the same fence shows as tables too, folded the same way.

Checklists

A To-do block is a checklist item. Click its box to tick it off. Press Enter at the end of one to start the next.

The block handle

Hover a block in the note and a handle appears in the margin, with a + to add a block below it.

  • Drag the handle to move the block elsewhere in the note.
  • Click it for the block's options: Turn into (another kind of text block), Duplicate, Move up, Move down and Delete. On an attachment you also get Open image, Download or Open link, and you can switch a link between a card and a plain link (Show as card or Show as link), and a reference card between a card and a mention in a line (Show inline).

Attachments

Images, files and link cards can live inside a note as blocks of their own. Add one with + Image or file, the slash menu, or Attach image or file below… in a block's options. You can also paste an image or drop files straight onto the note. Uploaded files are stored in the workspace's uploads/ folder.

Moving blocks between notes and the canvas

Blocks travel both ways:

  • Drag a block out of a note by its handle and let go on the canvas. Text becomes a new note; an attachment becomes an image, file or link block.
  • Let go over another note and the block moves into that note.
  • Drag an image, file, link or note block from the canvas over a note and hold Alt (Option on a Mac). Hold it within a few pixels of the note's text for a moment and a line shows where it will go; let go and it becomes part of the note (a whole note's text is merged in) and leaves the canvas. Without Alt the block is only moved, even when you let go on top of a note; a label by the pointer says which will happen. Merge into a note in the canvas settings sets how close it has to be.

Each move is a single step, so one Undo on the canvas takes it all back.

Mentions

@ mentions of blocks and repositories work in a project's spec, not in notes. See projects and specs. To get someone's attention about a note, comment on it with @name.

A note an agent writes can name a repository file as a chip ([[code:<repo>/<path>]](name) in its Markdown, with #L10-40 for some lines). Pressing it opens the file in Files: in a project that has a worktree of that repository, the worktree; anywhere else, the workspace's read-only copy. A chip for a repository the workspace does not have is shown as missing.

A doc can also hold cards for a project, prototype, canvas or research item, a branch or a pull request, and ::<ref> after a code chip's path reads the file at that branch, tag or commit. Drop such an object from the sidebar or the Files panel onto a doc to add its card. If it cannot be referenced there (a doc in itself), a message says why. A prototype's card can be folded to one row and unfolded again.

A doc can point at another doc of the workspace the same way: [[doc:<id>]](title) in its Markdown. It shows as a Doc card, and pressing it opens that doc. A doc that was deleted, or that you may not open, shows as missing.

Questions from the agent

When something about a doc is open that only you can decide, the workspace's agent asks in the doc itself, in the section the question is about. Its Markdown is a fenced block named question:

Markdown
```question
id: q-research-home
chat: <the chat's id>
of: 1 of 2
Where should research live?
- In the sidebar, next to projects | screens.md does this today
- Under the doc that started it
```

The doc shows it as a card: "The agent asks · from chat “…”", the question, its options with their hints, and Something else… for an answer of your own. Your pick takes the card's place in the section, with "Your pick, from the agent’s question" and Change under it to ask the question again. Your picks wait in a bar under the doc ("2 answers not sent yet · 1 question still open") until you choose Send answers: the chat that asked then gets them in one message, "You answered in the doc: …", and carries on. Picks not sent yet are sent when you open another doc or leave the doc. A fence that is not exactly this shape stays a code block. Where the doc is read-only, the options show but cannot be picked.

Editing together

Several people can write in the same note at once. Everyone's changes appear as they type, and nothing is overwritten. If an agent changes a note's file while someone is typing in it, Yard merges the two. Changes are saved to the workspace's history like everything else in the workspace.

Viewers, and everyone while the runner is offline, can read notes but not change them.

Was this page useful?
Edit this page