Block references
One claim, one address — single source of truth
Transcript
What if the same definition did not splinter into fourteen copies, but lived at a single address — and fourteen places stayed in sync instead of thirteen being forgotten? That is exactly what block references do, and over the next few minutes you will hear how they work and why they push maintenance effort almost to nothing.
A block ID is a UUIDv4 — one canonical place where a claim really lives. With double parentheses and the ID between them, you cite that block everywhere, ((id)). The block stays at its home, and the citation always shows the current state. Change the source, and fourteen citations follow at once.
The pain without references is quiet and expensive. A definition travels via Ctrl+C into fourteen pages. Six months later something changes, you maintain one place and forget thirteen. Consistency between definition and usage falls below half without anyone noticing — until two pages contradict each other and both sound plausible.
The difference between a reference and an embed matters. The reference ((id)) links — the reader jumps with Ctrl+click to the block at its home. The embed mirrors the block inline, so it takes part in the reading flow. Rule of thumb: ((id)) when the reader should jump to the context, embed when the block should read along.
The natural anchor use case is the Architecture Decision Record. You phrase a decision exactly once, with its own ID. Roadmap, onboarding and postmortem cite it via ((id)). When the decision changes, the fix at one place is visible in every citation — no fork, no stale copy.
Here is the difference in numbers. Before: fourteen pages with a copied definition, thirteen of them quietly out of date, maintenance effort growing with every usage. After: one block, fourteen references, one edit point, everything in sync. Maintenance effort stays constant, however often you cite.
The honest question at the end: in how many places is “customer”, “lead” or “done” defined in your wiki? If the number is above one, at least one of them is out of date. One claim, one address — everything else is a mirror. Your second brain holds the threads together and gives back what you entrust to it.
Block IDs are UUIDv4. One definition, one address. ((id)) cites it everywhere. Maintenance effort on a definition change drops by 95%, because you edit exactly one block and 14 places stay in sync.
Copy-paste across pages creates drift
A definition travels via Ctrl+C into 14 pages. Six months later the definition changes. You maintain one place and forget 13. Consistency between definition and usage falls below 50% without you noticing.
- Drift symptom 1: two pages contradict each other, and both look plausible.
- Drift symptom 2: a search for “ICP” returns 14 hits with 4 different definitions.
- Drift symptom 3: nobody knows which version is right — so a new one gets written. Now there are 15.
5 rules for block references
- One UUIDv4 per block. Each block gets an ID when you create it, e.g. 6c1b9a2e-4f3d-47a1-9e10-c0b7e2a55f12. Stable, collision-free, nothing to guess.
- Block reference ≠ block embed. ((id)) links — the block stays visible at its home. {{embed ((id))}} mirrors — the block appears inline at the citation.
- ((id)) syntax. Double parentheses, UUID between them, no space. Auto-complete kicks in once you type ((.
- Single source vs mirror. The definition lives in exactly one place (the source). Every other place is a mirror via ((id)). An edit on the mirror is an edit on the source.
- ADR as the anchor use case. Architecture Decision Records are the natural source: phrase the decision once, then reference it from the roadmap, onboarding and postmortem via ((id)).
## ADR-007: Block-IDs sind UUIDv4
id:: 6c1b9a2e-4f3d-47a1-9e10-c0b7e2a55f12
Wir verwenden UUIDv4 für Block-IDs, weil:
- kollisionsfrei ohne zentrale Vergabe
- 122 Bit Entropie reichen für 10^36 Blöcke
- offline generierbar (crypto.randomUUID())
---
## Roadmap Q3
Siehe Entscheidung: ((6c1b9a2e-4f3d-47a1-9e10-c0b7e2a55f12))
## Onboarding für neue Devs
ID-Schema: ((6c1b9a2e-4f3d-47a1-9e10-c0b7e2a55f12))Before and after — 14 Wikipedia clones vs one block, embedded 14 times
| Before | After |
|---|---|
| 14 pages with the ICP definition copy-pasted | 1 block, 14 references via ((id)) |
| Edit in 14 places, forget 13 | Edit in 1 place, 14 places in sync |
| Search “ICP” → 14 hits, 4 versions | Search “ICP” → 1 source, 14 backlinks |
| Drift goes unnoticed, contradictions in the wiki | Drift ruled out by design |
| Maintenance effort grows linearly with usages | Maintenance effort stays constant, whatever the usage count |
<!-- Source-Block (lebt in /glossar/icp.md) -->
id:: a8e2d710-3b9f-4c25-8d6a-1f2e7b3c4d50
ICP (Ideal Customer Profile): Beschreibung des Konto-Typs, der mium am stärksten profitiert — Branche, Größe, Wissensvolumen, Compliance-Frame.
<!-- Verwendung in /sales/playbook.md -->
Unser ICP: ((a8e2d710-3b9f-4c25-8d6a-1f2e7b3c4d50))
<!-- Verwendung in /onboarding/woche-1.md -->
Lies zuerst: ((a8e2d710-3b9f-4c25-8d6a-1f2e7b3c4d50))
<!-- Verwendung in /roadmap/2026.md -->
Fokus 2026: ((a8e2d710-3b9f-4c25-8d6a-1f2e7b3c4d50))An honest question
How often have you had to maintain the same definition in several places? Count the places where “customer”, “lead” or “done” is defined in your wiki. If the number is above 1, at least one of them is out of date.
One claim, one address. Everything else is a mirror.
One claim. One address.
Build your knowledge so that one change lands everywhere — your second brain holds the threads together.
Reserve your slot··free →