Block References
One claim, one address — single source of truth
- You understand that a block ID is a UUIDv4 address — one canonical place, any number of ((id)) citations. ·· Success criterion: You explain the difference between a copy and a reference using an example of your own.
- You decide confidently between ((id)) and embed. ·· Success criterion: You sort five cases correctly — jumping across versus staying in the reading flow.
- You create an Architecture Decision Record and cite it from three pages. ·· Success criterion: A change to the ADR appears in all three citations in sync.
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 drops below 50%, without you noticing.
- Drift symptom 1: Two pages contradict each other, both look plausible.
- Drift symptom 2: A search for “ICP” returns 14 hits with 4 different definitions.
- Drift symptom 3: Nobody knows which version holds — so a new one gets written. Now there are 15.
5 rules for block references
- UUIDv4 per block. Each block gets an ID on creation, e.g. 6c1b9a2e-4f3d-47a1-9e10-c0b7e2a55f12. Stable, collision-free, no guesswork.
- Block reference ≠ block embed. ((id)) links — the block stays visible at its home. {{embed ((id))}} mirrors — the block appears inline at the citation site.
- ((id)) syntax. Double parentheses, UUID in between, no space. Auto-complete kicks in after you type ((.
- Single source vs mirror. The definition lives in exactly one place (source). All other places are mirrors via ((id)). An edit on the mirror = 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 are UUIDv4
id:: 6c1b9a2e-4f3d-47a1-9e10-c0b7e2a55f12
We use UUIDv4 for block IDs because:
- collision-free without central allocation
- 122 bits of entropy are enough for 10^36 blocks
- generatable offline (crypto.randomUUID())
---
## Roadmap Q3
See decision: ((6c1b9a2e-4f3d-47a1-9e10-c0b7e2a55f12))
## Onboarding for new devs
ID scheme: ((6c1b9a2e-4f3d-47a1-9e10-c0b7e2a55f12))Before/after — 14 Wikipedia clones vs one block, embedded 14 times
| Before | After |
|---|---|
| 14 pages with the ICP definition copied | 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 structurally ruled out |
| Maintenance effort grows linearly with usages | Maintenance effort stays constant, independent of usages |
<!-- Source block (lives in /glossary/icp.md) -->
id:: a8e2d710-3b9f-4c25-8d6a-1f2e7b3c4d50
ICP (Ideal Customer Profile): description of the account type that benefits the most from mium — sector, size, knowledge volume, compliance frame.
<!-- Usage in /sales/playbook.md -->
Our ICP: ((a8e2d710-3b9f-4c25-8d6a-1f2e7b3c4d50))
<!-- Usage in /onboarding/week-1.md -->
Read first: ((a8e2d710-3b9f-4c25-8d6a-1f2e7b3c4d50))
<!-- Usage in /roadmap/2026.md -->
Focus 2026: ((a8e2d710-3b9f-4c25-8d6a-1f2e7b3c4d50))An honest question
How often have you had to maintain the same definition in different places? Kindly 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.
- Take a definition that lives in several copies across your wiki — say “customer”, “lead” or “done”. Kindly pick one place as the source, give that block an ID, and replace every other copy with ((id)). Then change the source once and check that all citations follow.⏱ 5 min
💡 Search for the term first and count the hits — the list shows you which place should become the canonical one and how many copies you are dissolving.
Model answer: Fourteen copied places become one source block with an ID plus thirteen ((id)) citations. The change to the source appears at once in all citations — maintenance effort falls from fourteen edit sites to one. Whatever is a genuine decision you additionally lift into an ADR and cite from there via ((id)).
What happens to fourteen ((id)) citations when you change the source block?
One claim. One address.
Build your knowledge so that one change lands everywhere — your second brain holds the threads together.
Reserve your slot··free of cost →