Appearance
Block references and embeds
A [[page]] link points at a page. A block reference points at one block, and renders it — live, in place, wherever you put it.
Making one
Two ways, from either end:
- From where it goes. Type
((and a few words of the block — the last word matches as a prefix — and choose it. The picker says Searching… or No block matches rather than staying hidden. - From the block itself. Alt+Shift+R, or Copy reference in its block menu, then paste on the other page.
Names and regions
A reference points at a block's identity, but people read names. So a block can carry one: Make referenceable in the block menu names it — or, over a selection of several blocks, makes them a region — and copies a reference to it. Copying a reference to a block with no name gives it a short one, which can be changed.
- A name shows in the right margin; a region's blocks share a bracket in the left.
- A region reference shows everything in it, and what is in it is whatever lies between its first and last block now: move a block in or out and every reference to the region follows.
- A heading's section can be referenced too: the heading and everything under it, to the next heading at the same level or above.
In Markdown these are Obsidian's forms — ^name at the end of a block's line, and <!-- region: name --> … <!-- /region --> around a run of blocks — on every page, rich or Markdown. Region and section references show read-only.
A reference is stored by identity and written from the current page title and name, so renaming either changes nothing stored. A reference typed to something that does not exist yet is kept as typed and looked up again, never dropped.
Rich and Markdown pages reference each other freely.
Editing one in place
An embedded block is editable, and this is the part worth understanding: the edit lands on the block's own page, in that page's history, attributed to you.
An embed is a window onto the source document, not a copy of part of it. The alternative — read the text, let somebody change it, write it back — resolves two people typing at once by discarding one of them, silently, and the one who lost never finds out. So the embed binds to the source page's own shared document: the same merge behaviour, the same character-level resolution, and an op on that page's log.
Two guards keep that safe, and the second is not optional:
- Every change must fall inside the block's content. A caret past the boundary could otherwise edit a neighbouring paragraph on a page nobody has open.
- The source page's top-level blocks must be the same before and after. The range check alone is not enough — a split replaces an empty range inside the block and passes it, while adding a paragraph to somebody else's document. The invariant is stated directly: an embed may change what a block says, never which blocks exist.
Permission comes from the source
Not from the page you are reading.
- Somebody reading a page may still edit a block embedded in it that they can edit at its own page.
- Somebody editing a page may not edit a block embedded from a page they can only read.
The socket refuses either way; the caret matches so you find out before you type.
Known limits
- Enter does nothing in an embed. Splitting would add a block to the source page, which guard (2) refuses. The block's own page is where structure is edited.
- No local persistence for embeds. A source page you have never opened has nothing stored, so its embeds are read-only when you are offline.
- Connections are shared per source page, so six embeds of one page open one socket. A page embedded in itself holds two documents in one browser and syncs them through the server.
- A region or a section shows read-only. Edit its blocks where they live.
In the export
On a rich page a reference is T3: a blockquote of the referenced text, attributed to its page, plus a sidecar carrying the link back — and, for a region or section, what it spans. A plain Markdown reader sees the quoted words rather than an identifier.
On a Markdown page it is written as Obsidian writes it — ![[page#^name]], by file name — which Obsidian follows. Obsidian has no multi-block regions: it hides the region markers, and a reference to a region opens the page there without finding the region.