Block References

Block references allow you to link to and embed specific paragraphs, lists, or other content blocks within notes.

Creating Block IDs

Add a block ID to any paragraph or list item:

This is an important paragraph. ^important-point

- List item one
- List item two ^key-item
- List item three

Block IDs:

Start with ^
Appear at the end of the line
Use lowercase letters, numbers, and hyphens
Must be unique within the note

Linking to Blocks

Within the same note

As mentioned in [[#^important-point]], we need to focus.

In another note

See [[Other Note#^important-point]] for details.

With alias

See [[Other Note#^important-point|the key insight]] for details.

Embedding Blocks

Embed a specific block using the ! prefix:

![[Other Note#^important-point]]

This transcludes just that block, not the entire note.

Block ID Best Practices

Naming

Choose descriptive, stable IDs:

The main thesis of this paper is... ^thesis

Key finding: productivity increased 40% ^finding-productivity

Decision: We will use React for the frontend ^decision-frontend

Avoid

Auto-generated IDs that might conflict
IDs that describe position (^paragraph-3)
Overly long IDs

Heading References vs Block References

Heading Reference	Block Reference
`[[Note#Heading]]`	`[[Note#^block-id]]`
Links to section	Links to specific block
Uses heading text	Uses explicit ID
May break if heading changes	Stable if ID preserved

Finding Block References

Search for notes with block IDs:

{
  "query": "\\^[a-z][a-z0-9-]*$"
}

Parser Implementation

Block IDs are parsed during markdown processing:

Location: crates/crucible-core/src/parser/types/blocks.rs

The parser:

Identifies blocks (paragraphs, lists, etc.)
Extracts trailing ^id patterns
Stores block ID → content mapping
Enables block-level linking and embedding

Automatic Block IDs

Crucible can generate block IDs automatically for content hashing:

---
auto_block_ids: true
---

Generated IDs use content hashes and are stable as long as content doesn’t change.

Use Cases

Citing specific points

In [[Research Paper#^methodology]], the authors describe...

Building arguments

Given that:
1. [[Premise One#^main-point]]
2. [[Premise Two#^conclusion]]

Therefore...

Creating excerpts

# Key Quotes

![[Book Notes#^quote-1]]

![[Book Notes#^quote-2]]

Stable references

When heading text might change, use block IDs for stability:

This relates to [[API Design#^rate-limiting-decision]]