Obsidian Block References — Design

Status (2026-10-31): design approved; Phase 1 (block references) is being planned. Canonical spec: docs/superpowers/specs/2026-10-31-obsidian-block-references-design.md.

Follows Native Wikilinks & Embeds, Obsidian Vault Import and Live Preview & Daily Notes. Those covered everyday Obsidian use. This design brings in the syntax they left out of scope, which heavy Obsidian users depend on and which import used to delete.

Phases

Phase	Feature
1	Block references: ^id anchors, [[Page#^id]] links, ![[Page#^id]] embeds, copy-block-link, [[Page#^ completion, import keeps block ids
2	==highlight== and %% comments %%
3	Tick task checkboxes from the reader
4	Inline #tags: rendered, indexed, completed

Each phase ships on its own. Before a phase deploys, the live corpus is scanned for text the new syntax would capture, so no existing page silently loses visible text.

Block references (Phase 1)

• Syntax: a trailing ^id on a paragraph or list item, or a standalone ^id paragraph that tags the block before it (tables, quotes, callouts, lists, code, display math). Headings don't take ids. Never inside code or math. The marker must follow whitespace, so x^2 is never an id.
• Anchors: the block gets id="^id" and links use #^id, as in Obsidian Publish. A wikilink fragment starting with ^ is always a block, never a heading slug.
• One block model: a shared server utility lists, finds, assigns and strips block ids from page source, parsing it exactly as rendering does. The editor has a mirror, and a shared parity fixture keeps the two in agreement.
• Block embeds reuse the page-embed renderer: same view permission, loop and size limits, and the render is kept out of shared caches.
• Copy block link: a gutter button on each block in the reader copies [[Page#^id]] ("Copy URL" is the alternative). If the block has no id and the reader can edit, the server assigns one and saves a new version, refusing with 409 if the page changed meanwhile. The server stamps each block with a source ordinal so the click finds the exact block. Included and embedded content carries no ordinals.
• Completion: [[Page#^ lists that page's blocks. Picking one without an id assigns it (editors only).
• Reader: landing on a block flashes it. A missing block shows a toast, and missing blocks appear in the broken-links report.
• Import now keeps ^id markers and [[x#^id]] links. Vaults imported earlier must be re-imported to recover them.

Source vs reader text

Markers and comments are part of page source. They are stripped from everything derived for reading: rendered HTML, ?format=md, excerpts, chunks/embeddings, search, feeds and Knowledge Graph input. Source surfaces always keep block markers, so agents can link to blocks and never delete ids on write-back. Comments on source surfaces are kept for editors and admin MCP, and stripped for view-only readers and knowledge MCP. No new MCP tools: agents read and write markers as text.

Later phases

• Highlights render as <mark> with nested emphasis. Comments are hidden from readers but are not private: anyone who can edit the page or view its history sees them. An unclosed %% stays literal instead of hiding the rest of the page.
• Reader task toggling is optimistic and version-checked: a changed page rolls the tick back and offers a reload. It is off on derived pages, legacy-markup pages and inside embeds.
• Inline tags share one identity with frontmatter tags (lowercase, / becomes -, the rule import already used), so #Foo and tags: [foo] are one tag. Inline tags feed search, facets and tag listings but not SEO metadata. Nested-tag hierarchy is out of scope.

Out of scope

Canvas, Dataview, citations addressed by block id, automatic link rewrite when a block id changes, block-level backlinks, and nested-tag hierarchy.