Write and validate
References (doc#id)
Link blocks together with ids — and let chiltepin check catch broken links.
Give a block an id:, and other blocks can point at it. chiltepin check checks these block references within the documents it loads.
# ```userstory
id: US-142
role: shopper
want: pay in one step
soThat: I can complete my purchase quickly
links:
- { ref: orders-api#seq-place-order, label: Request flow }How to write a reference
- Same file:
#id— for exampleref: "#seq-place-order". Prefer this form inside a doc; it survives file renames. - Another file:
doc#id, wheredocis the file's path under your docs folder without.md— for exampleorders-api#seq-place-order, orarchitecture/overview#c4-context.
IDs must be unique across the documents checked together. Only reference an id that exists (or that you're adding in the same change).
What chiltepin check catches
| Problem | Code | What you see |
|---|---|---|
| Two blocks with the same id | E_DUP_ID | Both files and lines are named |
| A reference to an id that doesn't exist | E_DANGLING_REF | The file, line, and bad reference |
Both are errors, so a broken reference fails CI. The full list of checks is in Validation.
Which blocks can hold references
Today two block types carry ref fields: userstory (links[].ref) and
stories (items[].links[].ref).