# Block references Block references are a feature in modern [[Personal Knowledge Management (PKM)]] tools that allow linking to and embedding specific blocks (paragraphs, bullets, or sections) rather than entire pages. Pioneered by [[Roam Research]] and adopted by [[Logseq]], [[Obsidian]], and others, block references enable granular knowledge connections at the idea level. When you reference a block, you can either link to it (navigate there) or embed/transclude it (display its content inline). This concept draws from [[Ted Nelson]]'s vision of [[Transclusion]]—the ability to include content by reference rather than copying. Block references transform note-taking from document-centric to idea-centric. Instead of organizing by files and folders, you organize by atomic ideas that can be referenced from multiple contexts. This supports the [[Zettelkasten method]] principle of one idea per note, but at a finer granularity. Each block becomes a reusable building block of thought. The challenge is that block references create dependencies—if you edit the source block, all references update; if you delete it, references break. Tools handle this differently, with some using stable IDs and others using content hashing. ## How Block References Work ``` ┌─────────────────────────────────────────────────────────────┐ │ BLOCK REFERENCES │ ├─────────────────────────────────────────────────────────────┤ │ │ │ SOURCE NOTE TARGET NOTE │ │ ┌─────────────────────┐ ┌─────────────────────┐ │ │ │ • Idea A │ │ Related thoughts: │ │ │ │ • Idea B ◀─────────┼───────────┼─ ((block-id-B)) │ │ │ │ • Idea C │ │ │ │ │ └─────────────────────┘ │ Embedded: │ │ │ │ │ {{embed ((id-B))}} │ │ │ │ │ ┌─────────────────┐ │ │ │ └──────────────────────────┼▶│ • Idea B │ │ │ │ (transclusion) │ └─────────────────┘ │ │ │ └─────────────────────┘ │ │ │ │ LINK: Points to block (click to navigate) │ │ EMBED: Displays block content inline (transclusion) │ │ │ └─────────────────────────────────────────────────────────────┘ ``` ## Block Reference Types | Type | Description | Use Case | |------|-------------|----------| | **Block link** | Reference that navigates to source | Citations, cross-references | | **Block embed** | Displays content inline (transclusion) | Reusing content, summaries | | **Block alias** | Link with custom display text | Readable inline references | ## Syntax by Tool | Tool | Block Reference | Block Embed | |------|-----------------|-------------| | **Roam Research** | `((block-id))` | `{{embed ((block-id))}}` | | **Logseq** | `((block-id))` | `{{embed ((block-id))}}` | | **Obsidian** | `[[note#^block-id]]` | `![[note#^block-id]]` | | **Notion** | Synced blocks | `/synced block` | | **Tana** | Node references | Inline expansion | ## Benefits | Benefit | Description | |---------|-------------| | **Granular linking** | Connect specific ideas, not just pages | | **Single source of truth** | Edit once, update everywhere | | **Idea reuse** | Build new thoughts from existing blocks | | **Context preservation** | See where ideas are referenced | | **Atomic notes** | Encourages small, focused ideas | ## Challenges | Challenge | Mitigation | |-----------|------------| | **Broken references** | Use tools with stable block IDs | | **Context loss** | Embed with surrounding context | | **Complexity** | Start simple, add references gradually | | **Portability** | Block IDs often tool-specific | | **Over-linking** | Reference only truly connected ideas | ## Block References vs Page Links | Aspect | Page Link | Block Reference | |--------|-----------|-----------------| | **Granularity** | Whole document | Single paragraph/bullet | | **Portability** | More portable | Tool-dependent syntax | | **Stability** | Filename-based | ID-based (can break) | | **Use case** | Topic connections | Idea-level connections | ## Transclusion Block embedding is a form of [[Transclusion]]—a concept coined by [[Ted Nelson]] in 1963: | Concept | Description | |---------|-------------| | **Definition** | Including content by reference, not copy | | **Origin** | Ted Nelson's Project Xanadu | | **Benefit** | Single source of truth | | **In PKM** | Block embeds, synced blocks | ## Best Practices | Practice | Rationale | |----------|-----------| | **Atomic blocks** | One idea per block for clean references | | **Meaningful content** | Blocks should make sense standalone | | **Limit nesting** | Deep embeds become confusing | | **Use for reuse** | Reference ideas you'll use in multiple contexts | | **Check backlinks** | See where blocks are referenced | ## References - Nelson, T. (1965). "A File Structure for the Complex, the Changing, and the Indeterminate" - https://roamresearch.com/ (pioneered modern block references) ## Related - [[Bidirectional Links]] - [[Transclusion]] - [[Personal Knowledge Management (PKM)]] - [[Roam Research]] - [[Logseq]] - [[Obsidian]] - [[Zettelkasten method]] - [[Ted Nelson]] - [[Networked Thought]] - [[Atomic Notes]]