How Do I

How Do I…

Common tasks for ReSpec spec editors.

---

Link to a term in another spec

Use the [= term =] shorthand after enabling xref:

var respecConfig = {
  xref: "web-platform", // or true, or ["FETCH", "DOM"]
};

<p>Run these steps to [=fetch=] a resource.</p>
<p>Fire an [=event=] named "load" at the {{Window}} object.</p>

Browse available terms at respec.org/xref.

---

Define a term so other specs can link to it

<p>The <dfn data-export>fetch</dfn> algorithm takes a request...</p>

The data-export attribute makes the term available in the xref database after your spec is crawled (usually ~6 hours after publication). See data-export.

---

Link to a section in the same document

As described in <a href="#authentication"></a>.
<!-- Empty href auto-fills with "§ N Authentication" -->

---

Add a normative or informative citation

This follows [[!FETCH]] (normative).
See also [[INFRA]] (informative).

The ! prefix makes it normative. See the Shorthands Guide.

---

Link to a specific anchor in another spec

Use data-cite:

<a data-cite="FETCH#concept-request">request</a>
<a data-cite="!HTML#event-loop">event loop</a>

---

Define a WebIDL interface

<section data-dfn-for="Widget" data-link-for="Widget">
  <h2>The <code>Widget</code> interface</h2>
  <pre class="idl">
  [Exposed=Window]
  interface Widget {
    readonly attribute DOMString name;
    undefined update(optional WidgetOptions options = {});
  };
  </pre>
  <p>The <dfn>name</dfn> attribute returns the widget's name.</p>
  <p>The <dfn>update()</dfn> method updates the widget.</p>
</section>

See the WebIDL Guide.

---

Add browser support data

var respecConfig = {
  caniuse: "payment-request",
};

var respecConfig = {
  mdn: true, // uses shortName as key
};

---

Include content from another file

<section data-include="sections/api.html"></section>

<section data-include="sections/intro.md"
         data-include-format="markdown"></section>

Requires HTTP — see data-include.

---

Mark a section as non-normative

<section class="informative">
  <h2>Use Cases</h2>
  <p>This section is non-normative.</p>
</section>

ReSpec adds "This section is non-normative." automatically.

---

Add a note, warning, or editor's note

<div class="note">
  <p>Implementations should handle this case carefully.</p>
</div>

<p class="ednote">TODO: clarify this algorithm.</p>

---

Sort a list alphabetically

<ul data-sort>
  <li>Zebra</li>
  <li>Apple</li>
  <li>Mango</li>
</ul>

See data-sort.

---

Link tests to an assertion

<p data-tests="test-basic.https.html,test-error.html">
  The user agent MUST reject the Promise if...
</p>

Requires testSuiteURI in config. See data-tests.

---

Suppress a linting warning

<table data-lint-ignore="no-captionless-tables">
  <tr><td>data without caption</td></tr>
</table>

See lint-ignore.

---

Run code before/after ReSpec processes the document

async function fetchData(config, document) {
  // runs before ReSpec
}

function cleanup(config, document) {
  // runs after ReSpec
}

var respecConfig = {
  preProcess: [fetchData],
  postProcess: [cleanup],
};

See preProcess and postProcess.

---

Know when ReSpec is done

await document.respec.ready;
// document is now fully processed

See document.respec.

---

Export the spec to static HTML

Click the ReSpec pill (top-right corner) → Save as HTML.

This produces a standalone HTML file with all scripts removed — suitable for W3C publication.

Alternatively, calling await document.respec.toHTML() outputs the same HTML as a string programmatically.