Add `ref` as Alias for `xref`

changeset-release/main View source

Criteria completion

No incremental history — criteria tracking started on Apr 19.

Relationships

ID:SPEC-008Status:review

Unbuilt Runes — High-Level Spec

ID:SPEC-021Status:draft

Plan Runes

Version:1.0

ID:WORK-021Status:done

Update Plan Documents to Use Xref Syntax

Priority:high

changeset-release/main current done

main done claude/file-naming-convention-LJdwR done

Apr 21, 01:17 PMf2b3512
Content editedby Claude
Add {ID}-{slug}.md filename convention + migrate filenames subcommand
Apr 10, 06:58 PMf262d7b
Content editedby Claude
Backfill source attributes on all 123 work items
Mar 23, 07:20 AMebe0c64
Content editedby Claude
Migrate plan files to {% ref %} xref syntax (WORK-021)
Mar 23, 07:16 AMdc97198
Content editedby Claude
Add ref as alias for xref rune (WORK-026)
Mar 23, 07:12 AM38e7523
Content editedby Claude
Resequence xref work items before CLI scanner
Mar 22, 07:25 PM3fc7634
Created (done)by Claude
Add work items for remaining SPEC-021 plan runes gaps

Summary

SPEC-021 uses {% ref "SPEC-008" /%} syntax for cross-references. The codebase has {% xref %}. Add ref as an alias for xref so both syntaxes work. This keeps the plan spec examples valid and provides a shorter, more natural syntax for inline references.

Acceptance Criteria

{% ref "SPEC-008" /%} produces identical output to {% xref "SPEC-008" /%}
ref registered as alias in the xref tag schema (packages/runes/src/tags/xref.ts)
All xref attributes work with the ref alias (label, type)
Test verifying alias produces same output

Approach

Add ref to the xref tag's aliases array in the Markdoc schema definition. No changes to the transform logic needed — Markdoc handles alias resolution automatically.