docs/user/features/block-anchors.md
Block anchors let you link to a specific paragraph, list item, heading, or blockquote within a note — not just to the note as a whole or to a section heading.
Place ^your-id at the end of any block element. The ID can contain letters, numbers, and hyphens.
The ^id marker is hidden in the preview — it's metadata, not visible text.
This is an important finding from the experiment. ^key-finding
Multi-line paragraphs work too — put the anchor at the end of the last line:
The first measurements were inconclusive.
After repeating the experiment, results became clear. ^experiment-result
Place the anchor at the end of the item text. Foam anchors the entire item, including any sub-items:
- Mix dry ingredients thoroughly ^dry-step
- 2 cups flour
- 1 tsp salt
- Add wet ingredients ^wet-step
To anchor an entire list, place ^id on its own line immediately after the last item (no blank line):
- First item
- Second item
- Third item
^shopping-list
## Methodology ^methodology
The anchor applies to the heading line itself, not the entire section below it.
Three placements are supported:
As the last line inside the blockquote:
> The only way to do great work is to love what you do.
> ^jobs-quote
On its own line immediately after the blockquote:
> We shall fight on the beaches,
> we shall fight on the landing grounds.
^churchill-beaches
After the blockquote with a blank line (useful if your markdown formatter inserts one):
> We shall fight on the beaches,
> we shall fight on the landing grounds.
^churchill-beaches
Place ^id on its own line after the closing fence. One blank line between the fence and ^id is also accepted (useful if your markdown formatter adds one automatically):
```python
def greet(name):
return f"Hello, {name}"
```
^greet-function
Place ^id on its own line after the table. One blank line is also accepted:
| Name | Score |
| ----- | ----- |
| Alice | 95 |
| Bob | 87 |
^results-table
Use [[note-name#^blockid]] to link directly to a block:
[[research-notes#^key-insight]]
[[research-notes#^list-ref]]
Foam provides autocomplete for block IDs when you type #^ inside a wikilink.
You can also add display text:
[[research-notes#^key-insight|See the key insight]]
Use ![[note-name#^blockid]] to embed just that block inline:
![[research-notes#^key-insight]]
Only the referenced block's content is shown — not the entire note.
Place your cursor on a ^blockid anchor and press F2 to rename it. Foam updates the anchor and all wikilinks that reference it across your workspace.
Foam warns you when a block link points to a ^id that doesn't exist in the target note. A quick-fix lets you pick from the available block IDs.
If you accidentally use the same ^id twice in one file, Foam flags the duplicate with a warning. A quick-fix replaces it with a freshly generated unique ID.