xref

xref

Type: boolean | string | string[] | XrefOptions Default: true (W3C profile)

Enables automatic cross-reference linking. When a term is wrapped in [= =] or {{ }} shorthand syntax, ReSpec automatically links it to the defining specification.

Basic usage

var respecConfig = {
  xref: "web-platform",
};

Then write terms naturally — ReSpec links them automatically:

<p>
  [=Queue a task=] to [=fire an event=] named "fetch"
  at the {{Window}} object.
</p>

How xref works

Understanding the pipeline helps when terms aren't found:

Your spec writes [=fetch=]
       ↓
ReSpec queries the xref service (respec.org/xref)
       ↓
Service looks up "fetch" in the WebRef database
       ↓
WebRef is populated by Reffy, which crawls published specs every 6 hours
       ↓
Reffy finds terms marked with <dfn data-export> in published specs
       ↓
Term found → generates <a href="https://fetch.spec.whatwg.org/#concept-fetch">fetch</a>
Term not found → ReSpec shows a red error banner

For a term to be findable via xref, ALL of these must be true:

1. The defining spec is listed in browser-specs
2. The defining spec is published (Editor's Drafts are crawled; unpublished local files are not)
3. The <dfn> in the defining spec has data-export or class="export"
4. Reffy has crawled it (within the last 6 hours for EDs; weekly for TR snapshots)

If a term isn't in the database, ask the defining spec's editors to add data-export. See data-export.

Configuration forms

Boolean

var respecConfig = {
  xref: true,
};

Profile name

var respecConfig = {
  xref: "web-platform",
};

The "web-platform" profile includes: HTML, INFRA, URL, WEBIDL, DOM, FETCH.

Array of spec shortnames

var respecConfig = {
  xref: ["FETCH", "DOM"],
};

Object (advanced)

var respecConfig = {
  xref: {
    profile: "web-platform",
    specs: ["PERMISSIONS", "SCREEN-WAKE-LOCK"],
  },
};

Options

Option	Type	Description
profile	string	Pre-defined profile name (e.g. "web-platform")
specs	string[]	Additional spec shortnames to include in lookups
url	string	Custom xref API URL (advanced — not normally needed)

Notes

• When both profile and specs are set, both sets of specs are used for disambiguation
• To manually link to a specific anchor in another spec, use data-cite
• Browse and test xref lookups at respec.org/xref
• See Auto-linking external references for disambiguation and advanced usage