Block IDs and references

Wikilinks normally point at a whole note or a section. Block IDs let you link to a single paragraph, list item, or block anywhere in the note.

Defining a block ID

Append ^some-id to the end of any block:

This is an important paragraph.

- A bullet I want to reference.
- Another.

> [!note]
> A callout I want to reference.

ID rules:

• Allowed chars: letters, digits, -, _.

• Must be unique within the note.

• Convention: kebab-case with a date prefix when relevant.

The ^id is hidden in Live Preview mode — it shows in Source mode only.

Linking to a block

See [[Project Notes#^claim-2026]] for the original claim.

Clicking that link scrolls to the block. Hovering shows a preview popover with the linked content.

You can also link within the same note:

As mentioned above [[#^claim-2026]]...

Auto-IDs from the editor

Right-click any block → Copy block reference. Lettuce assigns a fresh ID if the block doesn’t have one and copies a [[note#^id]] wikilink to your clipboard. Paste anywhere.

Block transclusion (experimental)

![[note#^id]] embeds the referenced block inline instead of linking to it:

The original claim was:

![[Project Notes#^claim-2026]]

Behaves like a live transclusion — if you edit the source block, the embed updates. Currently rendering-only; agents can read the source via read_note and resolve embeds with read_outline.

Programmatic access

read_outline returns only the heading outline — a flat array of {level, title, id} (the id is the heading anchor slug, not a block ID); it does not return a separate block_ids list. To discover existing ^block-id markers, read_note the file and scan the content for ^id tokens rather than guessing.

When to use block IDs vs. section links

• Section link ([[note#heading]]) — use when there’s a natural heading to anchor on.

• Block ID ([[note#^id]]) — use when the granularity is finer than headings (a single quote, claim, or list item).

• Whole-note link ([[note]]) — use when the reader should read the whole thing.

Related

• Core concepts/04 Wikilinks, backlinks, and the graph

• Agent reference/04 Read tools — read_outline tool