ReSpec

https://respec.org/docs
Admin
ReSpec is a tool that makes it easier to write technical documents, originally designed for W3C...
Tokens:41,289
Snippets:557
Trust Score:7.9
Update:5 months ago
Show doc for...
Tokens:
Raw
### Mark Element as Example with `.example`

Source: https://respec.org/docs

Use the `example` class on `<pre>`, `<aside>`, or other elements to create numbered examples. An optional `title` attribute can add a heading.

```javascript
const result = navigator.credentials.get({ password: true });

```

```html
<aside class="example" title="Using the Fetch API">
  <p>Here is how to make a request:</p>
  <pre>
    const res = await fetch("/data.json");
  </pre>
</aside>

```

```html
<pre class="illegal-example">
  document.write("&lt;!-- don't do this -->");
</pre>

```

--------------------------------

### Install ReSpec Dependencies

Source: https://respec.org/docs

Install the necessary project dependencies using pnpm. This command should be run from the repository root.

```bash
pnpm install
```

--------------------------------

### Start ReSpec Server Without Tests

Source: https://respec.org/docs

Starts only the HTTP server without running tests or other parts of the start script.

```bash
pnpm run server
```

--------------------------------

### Start ReSpec Development Server

Source: https://respec.org/docs

Launches the built-in HTTP server for development. Use this for general development tasks.

```bash
pnpm start
```

--------------------------------

### Start ReSpec Local Development Server

Source: https://respec.org/docs

Start the local development servers for ReSpec, including Karma and a local HTTP server. You can specify a browser like Chrome or Firefox.

```bash
pnpm start --browser Chrome
```

--------------------------------

### Run ReSpec after Global Installation

Source: https://respec.org/docs

Execute ReSpec after it has been installed globally.

```bash
respec --src source.html --out index.html

```

--------------------------------

### Install ReSpec Globally

Source: https://respec.org/docs

Install ReSpec globally using npm for repeated use.

```bash
npm install --global respec

```

--------------------------------

### Serve Local Directory Command

Source: https://respec.org/docs

Commands to start a local HTTP server for previewing ReSpec documents. Ensure you run this in the directory containing your spec file.

```bash
# Any of these work:
npx serve .
python3 -m http.server

```

--------------------------------

### Automatic Term Linking Example

Source: https://respec.org/docs

Demonstrates how terms like 'Queue a task' and 'fire an event' are automatically linked when xref is enabled.

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

```

--------------------------------

### Run Development Server with Custom Profile

Source: https://respec.org/docs

Starts the web server using a specified custom profile and browser. This allows you to test your custom ReSpec configuration by accessing `http://localhost:8000/examples`.

```bash
pnpm start --profile YOUR_PROFILE_NAME --browser Chrome
```

--------------------------------

### Clone ReSpec Repository

Source: https://respec.org/docs

Clone the ReSpec repository to begin development. Ensure you have Git installed.

```bash
git clone git@github.com:speced/respec.git
```

--------------------------------

### Install pnpm with Corepack

Source: https://respec.org/docs

Enable and activate pnpm using Corepack, a tool for managing Node.js package managers. This is a prerequisite for installing dependencies.

```bash
corepack enable
corepack prepare --activate # run this from repository root
```

--------------------------------

### Common Annotation Boxes

Source: https://respec.org/docs

Use `<aside>`, `<div>`, and `<p>` with specific classes to create annotation boxes for examples, notes, and issues.

```html
<aside class="example" title="Using the API">
  <pre class="js">
    const result = await navigator.credentials.get();
  </pre>
</aside>

<div class="note">
  <p>Implementations should handle the error case.</p>
</div>

<p class="issue" data-number="42">
  <!-- Content of GitHub issue #42 is embedded automatically -->
</p>
```

--------------------------------

### Complete ReSpec Specification Example

Source: https://respec.org/docs

A full HTML document demonstrating the structure and elements required for a ReSpec specification, including configuration and content sections.

```html
<!DOCTYPE html>
<html lang="en">
  <head>
    <meta charset="utf-8" />
    <title>My API</title>
    <script
      src="https://www.w3.org/Tools/respec/respec-w3c"
      class="remove"
      async
    ></script>
    <script class="remove">
      var respecConfig = {
        specStatus: "ED",
        editors: [{ name: "Your Name", url: "https://your-site.example/" }],
        github: "some-org/mySpec",
        shortName: "my-api",
        xref: "web-platform",
        group: "my-working-group",
      };
    </script>
  </head>
  <body>
    <section id="abstract">
      <p>This spec defines the My API.</p>
    </section>
    <section id="sotd"></section>
    <section class="informative">
      <h2>Introduction</h2>
      <p>Some introductory text.</p>
      <aside class="note" title="A note">
        <p>Notes look like this.</p>
      </aside>
    </section>
    <section data-dfn-for="Foo">
      <h2>The <code>Foo</code> interface</h2>
      <pre class="idl">
        [Exposed=Window]
        interface Foo {
          attribute DOMString bar;
          undefined doTheFoo();
        };
      </pre>
      <p>The <dfn>Foo</dfn> interface represents a {{Foo}}.</p>
      <p>The <dfn>doTheFoo()</dfn> method does the foo. Call it via {{Foo/doTheFoo()}}.</p>
      <ol class="algorithm">
        <li>Let |result:DOMString| be a new string.</li>
        <li>Return |result|.</li>
      </ol>
    </section>
    <section id="conformance"></section>
  </body>
</html>

```

--------------------------------

### With Replace: Element is Substituted (data-include-replace)

Source: https://respec.org/docs

This example demonstrates the behavior when `data-include-replace` is used, showing that the element itself is substituted with the included content.

```html
<section data-include="full-section.html"
         data-include-replace="true">
  <!-- The <section> element itself is replaced by full-section.html's content -->
</section>
```

--------------------------------

### Create Best Practice Box

Source: https://respec.org/docs

Markup best practices using `div.practice`, `p.practicedesc`, and `span.practicelab`. This generates a numbered best practice box. Best practices are automatically numbered and are less common than notes or examples.

```html
<div class="practice">
  <p class="practicedesc">
    <span class="practicelab">Use semantic HTML</span>
    Use the most semantically appropriate HTML element for each piece of content.
    Do not use `<div>` where a `<section>`, `<article>`, or `<nav>` would be more appropriate.
  </p>
</div>
```

```html
<div class="practice">
  <p class="practicedesc">
    <span class="practicelab">Best practice</span>
    Practice makes perfect, but perfect is the enemy of the good.
  </p>
</div>
```

--------------------------------

### Example Violation: Unused Algorithm Variables

Source: https://respec.org/docs

This example shows an HTML structure with an ordered list representing an algorithm. The variable '|unused|' is defined but never referenced again, triggering a warning from the 'no-unused-vars' rule.

```html
<ol class="algorithm">
  <li>Let |request| be a new request.</li>
  <li>Let |unused| be null.</li>       
  <li>Set |request|'s URL to the URL.</li>
</ol>
```

--------------------------------

### Start ReSpec in Interactive Mode

Source: https://respec.org/docs

Launches the development server in interactive mode, providing more control over test execution and disabling automatic file watching by default. This mode is beneficial for advanced debugging.

```bash
pnpm start --interactive
```

--------------------------------

### Linking to External Terms

Source: https://respec.org/docs

Once `xref` is enabled, terms from other specifications can be linked using the `[=term=]` syntax. This example shows linking to 'Queue a task' and 'fire an event'.

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

--------------------------------

### Configure ReSpec to Skip Chromium Download

Source: https://respec.org/docs

Set environment variables to skip downloading Chromium and specify an existing Chrome executable path, speeding up installation and execution.

```bash
export PUPPETEER_SKIP_CHROMIUM_DOWNLOAD=1
export PUPPETEER_EXECUTABLE_PATH="/usr/bin/google-chrome"
# replace "/usr/bin/google-chrome" with path to Chrome executable on your system.
# On MacOS, it's generally:
# "/Applications/Google Chrome.app/Contents/MacOS/Google chrome"

```

--------------------------------

### Default: Content Inserted Inside Element (data-include)

Source: https://respec.org/docs

This example shows the default behavior of `data-include` where the content of the included file is placed inside the target element.

```html
<section data-include="content.html">
  <!-- content.html's markup is placed here, inside the <section> -->
</section>
```

--------------------------------

### Run ReSpec Tests in Firefox

Source: https://respec.org/docs

Starts the testing server and runs unit tests specifically in the Firefox browser. The `--browser` flag can be set to other supported browsers like Chrome, Safari, or their headless variants.

```bash
pnpm start --browser Firefox
```

--------------------------------

### Set Copyright Start Year

Source: https://respec.org/docs

Specify the first year of the copyright period to indicate a copyright range. This is useful for documents developed over multiple years.

```javascript
var respecConfig = {
  copyrightStart: 2018,
  publishDate: "2025-06-01",
  // Results in: "Copyright © 2018-2025 W3C®"
};
```

--------------------------------

### Example violation: no-http-props

Source: https://respec.org/docs

This JavaScript snippet shows a violation of the no-http-props rule, using 'http://' instead of 'https://' for a configuration property.

```javascript
var respecConfig = {
  // BAD: http:// not https://
  implementationReportURI: "http://example.org/report.html",
};
```

--------------------------------

### Example Violation: Non-existent WPT Test

Source: https://respec.org/docs

This HTML snippet demonstrates a violation of the 'wpt-tests-exist' rule. The `data-tests` attribute references 'nonexistent-test.html', which does not exist in the web-platform-tests repository.

```html
<!-- BAD: nonexistent-test.html doesn't exist in WPT -->
<p data-tests="valid-test.html,nonexistent-test.html"></p>
```

--------------------------------

### Automatic Pluralization for Defined Terms

Source: https://respec.org/docs

This example shows that pluralization is enabled by default for `<dfn>` elements, allowing references to both singular and plural forms. No configuration is needed to enable this default behavior.

```javascript
var respecConfig = {
  // pluralize: true is already the default for W3C specs
};

```

--------------------------------

### Automatic Plural Forms Example

Source: https://respec.org/docs

Demonstrates how ReSpec automatically handles plural forms for defined terms. A term defined as 'user agent' can be referenced as both 'user agent' and 'user agents'.

```html
<dfn>user agent</dfn>

<!-- Both of these link correctly: -->
<a>user agent</a>
<a>user agents</a>

```

--------------------------------

### Enable/disable specific accessibility rules with options

Source: https://respec.org/docs

Customize the behavior of individual accessibility rules within the `a11y` lint configuration. This example enables a slow rule (`color-contrast`) and disables another (`image-alt`).

```javascript
var respecConfig = {
  lint: {
    a11y: {
      rules: {
        "color-contrast": { enabled: true },  // slow — disabled by default
        "image-alt": { enabled: false },
      },
    },
  },
};

```

--------------------------------

### Display Git commits between two points with rs-changelog

Source: https://respec.org/docs

Use the `<rs-changelog>` custom element to show a list of Git commits between two points. This example shows changes between 'v1.0' and 'v2.0'.

```html
<rs-changelog from="v1.0" to="v2.0"></rs-changelog>

```

--------------------------------

### Enable Xref (Minimal Configuration)

Source: https://respec.org/docs

A minimal configuration to enable the xref feature. This uses the default W3C profile.

```javascript
var respecConfig = {
  xref: true,
};

```

--------------------------------

### ReSpec CLI Help

Source: https://respec.org/docs

Display help information for the ReSpec command-line interface, including available options.

```bash
respec --help

```

--------------------------------

### Run ReSpec using npx

Source: https://respec.org/docs

Execute ReSpec one-off using npx to convert a source file to HTML. This downloads about 100MB.

```bash
npx respec --src source.html --out index.html

```

--------------------------------

### Link to Implementation Report

Source: https://respec.org/docs

Specify the `implementationReportURI` to provide a link to an implementation report. This is required for Candidate Recommendation (`"CR"`) documents.

```javascript
var respecConfig = {
  specStatus: "CR",
  implementationReportURI: "https://wpt.fyi/results/payment-request",
};
```

--------------------------------

### Example violation: no-headingless-sections

Source: https://respec.org/docs

This HTML snippet illustrates a violation of the no-headingless-sections rule, where a section element is not preceded by a heading.

```html
<!-- BAD: no heading -->
<section id="intro">
  <p>Content without a heading.</p>
</section>
```

--------------------------------

### Advanced Xref Configuration with Profile and Specs

Source: https://respec.org/docs

Configure xref using a predefined profile ('web-platform') and additional specific specs ('PERMISSIONS', 'SCREEN-WAKE-LOCK').

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

```

--------------------------------

### Example violation: check-punctuation

Source: https://respec.org/docs

This HTML snippet demonstrates a violation of the check-punctuation rule, where a paragraph element ends without any punctuation.

```html
<!-- BAD: paragraph ends without punctuation -->
<p>The widget is initialized during construction</p>
```

--------------------------------

### Example violation: no-captionless-tables

Source: https://respec.org/docs

This HTML snippet shows a violation of the no-captionless-tables rule, where a numbered table lacks a caption as its first child.

```html
<!-- BAD: numbered table without a caption -->
<table class="numbered">
  <tr><th>Feature</th><th>Status</th></tr>
  <tr><td>Thing</td><td>Done</td></tr>
</table>
```

--------------------------------

### Example violation: no-unused-dfns

Source: https://respec.org/docs

This HTML snippet demonstrates a violation of the no-unused-dfns rule, showing a <dfn> element that is defined but never referenced or exported.

```html
<!-- Defined but never linked to anywhere in the document: -->
<dfn>orphaned concept</dfn>
```

--------------------------------

### Example fix: no-headingless-sections

Source: https://respec.org/docs

This HTML snippet demonstrates the correct way to fix a violation of the no-headingless-sections rule by adding a heading element to the section.

```html
<section id="intro">
  <h2>Introduction</h2>
  <p>Content with a heading.</p>
</section>
```

--------------------------------

### Enable Cross-Specification References (xref)

Source: https://respec.org/docs

Enable the `xref` configuration option to automatically find and link to terms defined in other specifications. This requires specifying the relevant specifications in `respecConfig`.

```javascript
var respecConfig = {
  xref: "web-platform", // includes HTML, Infra, URL, WebIDL, DOM, Fetch
};
```

--------------------------------

### Example violation: local-refs-exist

Source: https://respec.org/docs

This HTML snippet illustrates a violation of the local-refs-exist rule, where an anchor link points to an ID that does not exist within the document.

```html
<section id="foo">...</section>

<!-- BAD: #bar doesn't exist in the document -->
<a href="#bar">link</a>
```

--------------------------------

### Xref Pipeline Explanation

Source: https://respec.org/docs

Illustrates the process by which ReSpec queries the xref service to find and link terms defined in specifications.

```text
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

```

--------------------------------

### Example violation: informative-dfn

Source: https://respec.org/docs

This HTML snippet shows a violation of the informative-dfn rule, where a normative section links to a definition provided in an informative section.

```html
<section class="informative">
  <dfn>fancy algorithm</dfn> is described here.
</section>

<section>
  <h2>Processing Model</h2>
  <!-- BAD: normative section linking to informative definition -->
  <p>Run the <a>fancy algorithm</a>.</p>
</section>
```

--------------------------------

### Enable Xref with Web Platform Profile

Source: https://respec.org/docs

Enable automatic cross-reference linking using the 'web-platform' profile. Terms wrapped in `[= =]` or `{{ }}` syntax will be automatically linked.

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

```

--------------------------------

### Link to Expansions

Source: https://respec.org/docs

Link to specific IDs within a document. This shorthand expands the ID and creates a link to the corresponding element, often used for examples.

```html
[[[#example-2]]]
```

--------------------------------

### Define a Constructor for a WebIDL Interface

Source: https://respec.org/docs

Define constructors using the `<dfn constructor for="InterfaceName">` syntax. This is used to specify the constructor signature and its associated steps.

```html
<p>The <dfn constructor for="Widget">constructor(name, options)</dfn> steps are:</p>
<ol class="algorithm">
  <li>Let |w:Widget| be a new {{Widget}} object.
  <li>Set |w|'s {{Widget/name}} to |name|.
  <li>Return |w|.
</ol>
```

--------------------------------

### Add Implementation Status from External Source

Source: https://respec.org/docs

Use the postProcess hook to fetch external data and add implementation status badges to document sections. Ensure the external JSON data contains implementation counts keyed by section IDs.

```javascript
async function addImplStatus(config, document) {
  const res = await fetch("https://api.example.org/impl-status.json");
  const status = await res.json();

  // Add a badge to each section that has implementation data
  for (const [id, data] of Object.entries(status)) {
    const section = document.getElementById(id);
    if (!section) continue;
    const badge = document.createElement("span");
    badge.className = "impl-badge";
    badge.textContent = `${data.implementations} implementations`;
    section.querySelector("h2, h3")?.append(" ", badge);
  }
}

var respecConfig = {
  postProcess: [addImplStatus],
};

```

--------------------------------

### Include HTML File with data-include

Source: https://respec.org/docs

Use `data-include` to fetch an external HTML file and insert its content as children of the element. Paths are relative to the including document and includes are recursive up to a depth of 3. Must be served over HTTP/HTTPS.

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

--------------------------------

### Enable MDN Annotations with Short Name

Source: https://respec.org/docs

Activate MDN browser compatibility annotations by setting `mdn` to `true` and providing the `shortName` of the specification. Annotations appear in the right margin and are sourced from MDN's browser-compat-data.

```javascript
var respecConfig = {
  shortName: "payment-request",
  mdn: true,
};
```

--------------------------------

### Define WebIDL Interface with Definitions and Linking

Source: https://respec.org/docs

Group WebIDL blocks with prose definitions for each member within a `<section data-dfn-for="InterfaceName">`. This pattern facilitates clear documentation and linking of interface members.

```html
<section data-dfn-for="Fetch">
  <h2>The <code>Fetch</code> interface</h2>
  <pre class="idl">
  [Exposed=Window]
  interface Fetch {
    constructor(USVString url);
    readonly attribute USVString url;
    undefined send();
  };
  </pre>
  <section>
    <h2>Constructors</h2>
    <p>The <dfn constructor for="Fetch">constructor(url)</dfn> steps are:</p>
    <ol class="algorithm">
      <li>Set [=this=]'s {{Fetch/url}} to |url|.
    </ol>
  </section>
  <section>
    <h2>Attributes</h2>
    <p>The <dfn attribute>url</dfn> attribute steps are to return [=this=]'s url.</p>
  </section>
  <section>
    <h2>Methods</h2>
    <p>The <dfn method>send()</dfn> method steps are:</p>
    <ol class="algorithm">
      <li>...</li>
    </ol>
  </section>
</section>
```

--------------------------------

### Example fix: no-captionless-tables

Source: https://respec.org/docs

This HTML snippet demonstrates the correct way to fix a violation of the no-captionless-tables rule by adding a <caption> element as the first child of a numbered table.

```html
<table class="numbered">
  <caption>Feature implementation status</caption>
  <tr><th>Feature</th><th>Status</th></tr>
  <tr><td>Thing</td><td>Done</td></tr>
</table>
```

--------------------------------

### Enable Markdown Globally

Source: https://respec.org/docs

Set the 'format' option to 'markdown' to process the entire document body as Markdown. Ensure content is left-aligned as whitespace is significant.

```javascript
var respecConfig = {
  format: "markdown",
};

```

--------------------------------

### Link to Plural Forms of Concepts

Source: https://respec.org/docs

ReSpec automatically links plural forms of simple nouns to their singular concept definition. For example, '[=fruits=]' links to the concept 'fruit'.

```html
[=fruits=]
```

--------------------------------

### Enable JSON-LD Metadata

Source: https://respec.org/docs

Set 'doJsonLd' to true to include a `<script type="application/ld+json">` element with schema.org metadata. This requires 'canonicalURI' and 'license' to be set.

```javascript
var respecConfig = {
  doJsonLd: true,
  canonicalURI: "TR",
  license: "w3c-software-doc",
};
```

--------------------------------

### Link to WebIDL Static Operation or Method

Source: https://respec.org/docs

Link to static operations or methods in WebIDL. Argument placeholders can be included.

```html
{{URL.createObjectURL()}}
```

```html
{{URL.createObjectURL(obj)}}
```

--------------------------------

### Specify Previous Recommendation URI

Source: https://respec.org/docs

Use `prevRecURI` to provide the full URL of the previous W3C Recommendation this document supersedes. A dated URL is preferred for stability.

```javascript
var respecConfig = {
  prevRecURI: "https://www.w3.org/TR/2014/REC-css-color-3-20140805/",
};

```

--------------------------------

### Include Markdown File with data-include and data-include-format

Source: https://respec.org/docs

Combine `data-include` with `data-include-format="markdown"` to fetch an external Markdown file. The content is converted from GitHub Flavored Markdown to HTML before insertion.

```html
<section data-include="sections/api.md"
         data-include-format="markdown"></section>
```

--------------------------------

### Configure issue and atRiskBase for tracking

Source: https://respec.org/docs

Configure `issueBase` and `atRiskBase` in `respecConfig` to specify the base URLs for linking issues and at-risk features. This allows `data-number` to create valid links to external trackers.

```javascript
var respecConfig = {
  issueBase: "https://github.com/example/repo/issues/",
  atRiskBase: "https://github.com/example/repo/issues/",
};
```

--------------------------------

### Link to References

Source: https://respec.org/docs

Create a link to a specification or document using its short name. This is useful for citing standards like RFCs.

```html
[[RFC2119]]
```

--------------------------------

### Display Git commits since a tag with rs-changelog

Source: https://respec.org/docs

Use the `<rs-changelog>` custom element to show a list of Git commits between two points. This example shows changes since the 'CR' tag.

```html
<p>Changes since the CR snapshot:</p>
<rs-changelog from="CR"></rs-changelog>

```

--------------------------------

### Browser Support Table (Basic)

Source: https://respec.org/docs

Specify a feature name (e.g., 'payment-request') to automatically include a browser support table sourced from caniuse.com.

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


```

--------------------------------

### Add Custom Links to Document Header

Source: https://respec.org/docs

Configure `otherLinks` to add custom sections with links to external resources like implementation trackers or issue trackers. Each entry gets its own heading in the header.

```javascript
var respecConfig = {
  otherLinks: [
    {
      key: "Implementation status",
      data: [
        {
          value: "Chrome",
          href: "https://chromestatus.com/feature/12345",
        },
        {
          value: "Firefox",
          href: "https://bugzilla.mozilla.org/show_bug.cgi?id=12345",
        },
        {
          value: "Safari",
          href: "https://bugs.webkit.org/show_bug.cgi?id=12345",
        },
      ],
    },
  ],
};

```

--------------------------------

### Inject a Generated Section

Source: https://respec.org/docs

Use the preProcess hook to dynamically create and insert new sections into the document, such as a build information section that includes editor details from the configuration.

```javascript
function addGeneratedSection(config, document) {
  const section = document.createElement("section");
  section.id = "build-info";
  section.innerHTML = `
    <h2>Build Information</h2>
    <p>Built by: <strong>${config.editors[0].name}</strong></p>
  `;
  document.body.insertAdjacentElement("beforeend", section);
}

var respecConfig = {
  preProcess: [addGeneratedSection],
};

```

--------------------------------

### Disable Automatic URL Hyperlinking

Source: https://respec.org/docs

Use the .nolinks class on <pre> elements to prevent ReSpec from automatically converting bare URLs into hyperlinks. This is useful for code examples containing URLs as string literals.

```html
<pre class="nolinks">
const url = "https://example.com/data";
fetch(url); // https://example.com/data stays as text
</pre>
```

--------------------------------

### Alias WebIDL Methods

Source: https://respec.org/docs

This demonstrates aliasing WebIDL method names to provide a shorter or more specific link. Aliasing is generally not recommended.

```html
{{ Window/postMessage(message, options)|postMessage(message) }}
```

```html
{{ Window/postMessage(message, options)|postMessage() }}
```

```html
{{ Window/postMessage(message, options)|postMessage }}
```

--------------------------------

### Add Multiple Logos (W3C + Partner)

Source: https://respec.org/docs

Configure multiple logos by providing an array of logo objects to the `logos` option. This allows for including the W3C logo along with partner or community group logos.

```javascript
var respecConfig = {
  logos: [
    {
      src: "https://www.w3.org/StyleSheets/TR/2021/logos/W3C",
      alt: "W3C",
      url: "https://www.w3.org/",
      height: 48,
    },
    {
      src: "https://partner.example/logo.svg",
      alt: "Partner Org",
      url: "https://partner.example/",
      height: 48,
    },
  ],
};
```

--------------------------------

### Exclude IDL block from index in ReSpec

Source: https://respec.org/docs

Add `class="exclude"` to any `<pre class="idl">` to keep it out of the IDL index. This is useful for non-normative illustrative examples. IDL blocks inside non-normative sections are automatically excluded.

```html
<pre class="idl exclude">
  // This example IDL is not normative
  interface Example {};
</pre>

```

--------------------------------

### Link Alternate Formats (PDF, ePub)

Source: https://respec.org/docs

Configure links to alternate formats of the specification, such as PDF and ePub. Each entry requires a label and a URI.

```javascript
var respecConfig = {
  alternateFormats: [
    {
      label: "PDF",
      uri: "https://www.w3.org/TR/my-spec/my-spec.pdf",
    },
    {
      label: "ePub",
      uri: "https://www.w3.org/TR/my-spec/my-spec.epub",
    },
  ],
};

```

--------------------------------

### Load Additional Language for Highlighting

Source: https://respec.org/docs

Load additional syntax highlighting languages, like Solidity, by using the ReSpec worker to post a message with the language URL and properties.

```javascript
async function loadSolidity() {
  const worker = await new Promise(resolve => {
    require(["core/worker"], ({ worker }) => resolve(worker));
  });
  worker.postMessage({
    action: "highlight-load-lang",
    langURL: "https://example.com/highlightjs-solidity.js",
    propName: "hljsDefineSolidity",
    lang: "solidity",
  });
  return new Promise(resolve => {
    worker.addEventListener("message", function listener({ data }) {
      if (data.action === "highlight-load-lang" && data.lang === "solidity") {
        worker.removeEventListener("message", listener);
        resolve();
      }
    });
  });
}

var respecConfig = {
  preProcess: [loadSolidity],
};

```

--------------------------------

### Set GitHub Repository as Full URL

Source: https://respec.org/docs

Associates the specification with a GitHub repository by providing the full repository URL. This enables feedback links and auto-configuration of related settings.

```javascript
var respecConfig = {
  github: "https://github.com/w3c/payment-request",
};
```

--------------------------------

### Enable MDN Annotations with Explicit Key

Source: https://respec.org/docs

Enable MDN annotations by directly providing the specification's key to the `mdn` option. This is an alternative to using the `shortName` when the key differs.

```javascript
var respecConfig = {
  mdn: "payment-request",
};
```

--------------------------------

### Browser Support Table (With Options)

Source: https://respec.org/docs

Customize the caniuse.com browser support table by providing an options object, including specifying which browsers to display.

```javascript
var respecConfig = {
  caniuse: {
    feature: "payment-request",
    browsers: ["chrome", "firefox", "safari", "edge"],
  },
};


```

--------------------------------

### Set GitHub Repository (Shortest Form)

Source: https://respec.org/docs

Associates the specification with a GitHub repository using the shortest form. This adds a 'Feedback:' section to the document header and auto-sets `edDraftURI` and `issueBase`.

```javascript
var respecConfig = {
  github: "w3c/payment-request",
};
```

--------------------------------

### Enable wpt-tests-exist Rule

Source: https://respec.org/docs

To enable the 'wpt-tests-exist' linting rule, set its value to `true` within the `lint` object in your `respecConfig`. You must also provide the `testSuiteURI` for ReSpec to locate the WPT tests.

```javascript
var respecConfig = {
  testSuiteURI: "https://github.com/web-platform-tests/wpt/tree/HEAD/payment-request/",
  lint: {
    "wpt-tests-exist": true,
  },
};
```

--------------------------------

### Link to WebIDL Operation or Method

Source: https://respec.org/docs

Use this shorthand to link to operations or methods defined in WebIDL. You can include argument placeholders for clarity.

```html
{{PaymentRequest/show()}}
```

```html
{{PaymentRequest/show(detailsPromise)}}
```

--------------------------------

### Enable Dark Mode Support

Source: https://respec.org/docs

Add the meta tag 'color-scheme' with value 'light dark' in the head to enable light and dark mode support for W3C specs.

```html
<head>
  <meta name="color-scheme" content="light dark">
</head>
```

--------------------------------

### Replace Implementation Status Badge with Link on Save

Source: https://respec.org/docs

Configures the implementation status option to replace the interactive badge with a plain link when the spec is saved or exported. This is useful for static exports.

```javascript
var respecConfig = {
  implementationStatus: {
    feature: "screen-wake-lock",
    removeOnSave: true,
  },
};
```

--------------------------------

### Include ReSpec Script and Configuration

Source: https://respec.org/docs

Add these script tags to the HTML head to include ReSpec. The 'remove' class strips them from the final output. Use 'var' for respecConfig as it must be globally accessible.

```html
<script
  src="https://www.w3.org/Tools/respec/respec-w3c"
  class="remove"
  async
></script>
<script class="remove">
  // var is required — ReSpec reads this as window.respecConfig
  // (const/let are block-scoped and not visible to the ReSpec bundle)
  var respecConfig = {
    // configuration options
  };
</script>

```

--------------------------------

### Configure Editors and Authors

Source: https://respec.org/docs

Specify editors and authors with their details like name, URL, company, and retirement dates in the respecConfig object.

```javascript
var respecConfig = {
  editors: [
    {
      name: "Robin Berjon",
      url: "https://berjon.com/",
      company: "W3C",
      companyURL: "https://w3c.org/",
      note: "until 2022",
    },
  ],
  authors: [
    {
      name: "Ada Lovelace",
      company: "Aristocracy",
      retiredDate: "1852-11-27",
    },
  ],
};

```

--------------------------------

### Enable Preview Banner

Source: https://respec.org/docs

Use `isPreview: true` to add a prominent warning banner indicating a preview version. This is useful for distinguishing draft versions from official releases.

```javascript
var respecConfig = {
  isPreview: true,
};
```

--------------------------------

### Disable Syntax Highlighting with PRE

Source: https://respec.org/docs

To disable syntax highlighting for a specific <pre> block, use the 'nohighlight' class.

```html
<pre class="nohighlight">
pseudocode or plain text here
</pre>

```

--------------------------------

### Configure Test Suite URI

Source: https://respec.org/docs

Set the URI for the WPT test suite. This is required for the `wpt-tests-exist` linting rule to validate `data-tests` paths.

```javascript
var respecConfig = {
  testSuiteURI: "https://wpt.fyi/payment-request/",
};

```

--------------------------------

### Configure Custom MDN Data Source and Cache

Source: https://respec.org/docs

Customize the MDN annotations by providing an options object to the `mdn` configuration. This allows specifying a custom data source URL and cache duration.

```javascript
var respecConfig = {
  mdn: {
    key: "payment-request",
    maxAge: 3600000, // 1 hour cache
  },
};
```

--------------------------------

### Build Custom ReSpec Profile

Source: https://respec.org/docs

Generates a ReSpec bundle for a custom profile using the builder script. Replace `YOUR-PROFILE-NAME` with the actual name of your custom profile file.

```bash
node ./tools/builder.js YOUR-PROFILE-NAME
```

--------------------------------

### Configure Web Monetization Payment Pointer

Source: https://respec.org/docs

Use this to set a custom payment pointer for Web Monetization. This enables monetization for your document.

```javascript
var respecConfig = {
  monetization: "$wallet.example.com/my-wallet",
};

```

--------------------------------

### Enable Preview Banner with Pull Request Link

Source: https://respec.org/docs

When `prNumber` and `prUrl` are provided along with `isPreview: true`, the warning banner includes a link to the specific pull request. This is helpful for PR preview deployments.

```javascript
var respecConfig = {
  isPreview: true,
  prNumber: 123,
  prUrl: "https://github.com/example/spec/pull/123",
};
```

--------------------------------

### Fetch External Data Before Processing

Source: https://respec.org/docs

Utilize the preProcess hook to fetch external data, such as terminology definitions, and inject them into the document as <dfn> elements before ReSpec begins its main processing.

```javascript
async function loadTerms(config, document) {
  const res = await fetch("https://api.example.org/terms.json");
  const terms = await res.json();

  // Inject <dfn> elements so xref can resolve them
  const section = document.querySelector("#terminology");
  for (const { id, label } of terms) {
    const p = document.createElement("p");
    p.innerHTML = `The <dfn data-export id="${id}">${label}</dfn> is ...`;
    section.append(p);
  }
}

var respecConfig = {
  preProcess: [loadTerms],
};

```

--------------------------------

### Define Browser Permission String

Source: https://respec.org/docs

Define a browser permission string using either the `class="permission"` attribute or `data-dfn-type="permission"`. The permission name must be a quoted string. These definitions are exported and linkable.

```html
<p>
  The Geolocation API is identified by the powerful feature name
  <dfn class="permission">"geolocation"</dfn>.
</p>
```

```html
<dfn data-dfn-type="permission">"geolocation"</dfn>
```

--------------------------------

### Auto-detected Syntax Highlighting with PRE

Source: https://respec.org/docs

ReSpec automatically syntax-highlights <pre> and <code> elements using highlight.js. Language is auto-detected if no class is specified.

```html
<pre>
function fetch(url) {
  return new Promise(resolve => {
    // ... JS is auto-detected
  });
}
</pre>

```

--------------------------------

### Replace Element with Included Content using data-include-replace

Source: https://respec.org/docs

Use `data-include-replace="true"` to replace the element entirely with the content of the fetched file. This is useful when the included file provides its own wrapper element.

```html
<section data-include="sections/header.html"
         data-include-replace="true"></section>
```

--------------------------------

### Mark Section as Appendix with `.appendix`

Source: https://respec.org/docs

Apply the `appendix` class to a `<section>` to designate it as an appendix. Appendix sections are lettered (A, B, C...) instead of numbered.

```html
<section class="appendix">
  <h2>Acknowledgements</h2>
  <p>The editors thank the following for their contributions…</p>
</section>

```

--------------------------------

### Add Custom Bibliography Entry

Source: https://respec.org/docs

This JavaScript configuration shows how to add a custom bibliography entry using the `localBiblio` option in `respecConfig`. This allows you to cite specifications not present in the SpecRef database.

```javascript
var respecConfig = {
  localBiblio: {
    "MY-SPEC": {
      title: "My Custom Specification",
      href: "https://example.org/my-spec/",
      status: "ED",
      publisher: "Example Community Group",
    },
  },
};
```

--------------------------------

### Set Document License

Source: https://respec.org/docs

The `license` option specifies the copyright license for the document. Use specific values like `"cc0"` for non-W3C documents or when a different license is required. The default for W3C documents is `"w3c-software-doc"`.

```javascript
var respecConfig = {
  // w3c-software-doc is already the default for W3C documents
};
```

```javascript
var respecConfig = {
  license: "cc0",
};
```

--------------------------------

### Plugin run() Function Arguments

Source: https://respec.org/docs

The exported `run` function in a ReSpec plugin accepts a `conf` argument, which is the ReSpec configuration object (`window.respecConfig`). It's important not to modify this object.

```javascript
export async function run(conf) {
  if ("something" in conf || document.querySelector("#important-element")) {
    await someAsyncTask();
  }
}
```

--------------------------------

### Migrate Deprecated wgPatentURI Option

Source: https://respec.org/docs

Replaces the deprecated `wgPatentURI` option with the modern `group` option. The `group` option auto-configures the correct patent policy URI.

```javascript
// Before (error-prone):
// wgPatentURI: "https://www.w3.org/2004/01/pp-impl/83482/status",

// After (auto-configured correctly):
var respecConfig = {
  group: "webapps",
};

```

--------------------------------

### Enable privsec-section Rule

Source: https://respec.org/docs

To enable the 'privsec-section' linting rule, set its value to `true` within the `lint` object in your `respecConfig`.

```javascript
var respecConfig = {
  lint: { "privsec-section": true },
};
```

--------------------------------

### Link WPT tests to an assertion

Source: https://respec.org/docs

Use `data-tests` attribute on an element to link it to Web Platform Tests. The `testSuiteURI` must be set in `respecConfig`. This works best on elements containing normative assertions.

```html
<script>
  var respecConfig = {
    testSuiteURI: "https://wpt.fyi/payment-request/",
  };
</script>

<p data-tests="payment-request-basics.https.html, timeout.html">
  The user agent MUST reject the Promise if the user cancels.
</p>

```

--------------------------------

### Create a Warning Box with ReSpec

Source: https://respec.org/docs

Use the 'warning' class to create a distinct warning box. This is useful for highlighting important cautions. Content with class="removeOnSave" is fully removed in exported HTML.

```html
<div class="warning">
  <p>Removing entries from this list is a breaking change.</p>
</div>
```

```html
<aside class="warning" title="Deprecation notice">
  <p>The <code>sync</code> flag has been deprecated and will be removed in a future version.</p>
</aside>
```

--------------------------------

### Create a Block Note

Source: https://respec.org/docs

Use the .note class on block elements like <div> or <p> to render content within a labelled 'Note' box. The 'title' attribute can be used to provide a custom heading for the note.

```html
<div class="note">
  <p>Authors must not rely on the computed value being identical
  across different implementations.</p>
</div>
```

```html
<p class="note" title="Always use native semantics">
  If you are using <code>role="button"</code> on a div,
  you are probably doing it wrong.
</p>
```

--------------------------------

### Run ReSpec Tests Headlessly

Source: https://respec.org/docs

Executes tests without opening a browser window, displaying results directly in the terminal. Use `--browser FirefoxHeadless` or `--browser ChromeHeadless` for this purpose.

```bash
pnpm start --browser FirefoxHeadless
```

```bash
# or use ChromeHeadless
```

--------------------------------

### Run ReSpec Tests Matching a Pattern

Source: https://respec.org/docs

Executes tests that match a specific pattern in their description. This is useful for focusing on a subset of tests, such as those related to 'SEO'.

```bash
pnpm start --grep="SEO"
```

--------------------------------

### Use data-dfn-for for WebIDL Definitions

Source: https://respec.org/docs

Use the `data-dfn-for` attribute on a `<section>` to set the default interface context for all `<dfn>` elements within it. This simplifies definitions by avoiding repetition of the interface name.

```html
<section data-dfn-for="Request">
  <p>The <dfn>url</dfn> attribute of {{Request}}.</p>
  <p>The <dfn>clone()</dfn> method.</p>
  <!-- Both dfns are automatically "for Request" -->
</section>
```

--------------------------------

### Define Sections and Sub-sections

Source: https://respec.org/docs

Use `<section>` elements to structure content. ReSpec automatically handles numbering, IDs, and ToC entries. Use classes like `informative` for non-normative content.

```html
<section>
  <h2>Concepts</h2>
  <p>Some text.</p>
  <section class="informative">
    <h3>Background</h3>
    <p>Non-normative background text.</p>
  </section>
</section>
```

--------------------------------

### Link to WebIDL Interface, Dictionary, Enum, or IDL Type

Source: https://respec.org/docs

Use this shorthand to create a link to a WebIDL definition. Ensure the identifier is correctly spelled as it is case-sensitive.

```html
{{PaymentRequest}}
```

```html
{{unrestricted double}}
```

```html
{{long long}}
```

--------------------------------

### Export a concept definition with class="export"

Source: https://respec.org/docs

Alternatively, use the `class="export"` on a `<dfn>` element to mark a concept definition for export. This is a shorthand for `data-export`.

```html
<dfn class="export">request</dfn>
```

--------------------------------

### Migrate wgPublicList to group in ReSpec

Source: https://respec.org/docs

Use the `group` option instead of the deprecated `wgPublicList` to configure the short name of the group's public mailing list. The `group` option auto-configures this.

```javascript
// Before:
// wgPublicList: "public-webapps",

// After:
var respecConfig = {
  group: "webapps",
};

```

--------------------------------

### Associate with a Working Group

Source: https://respec.org/docs

Use the `group` option to associate your document with a W3C Working Group. This helps in setting patent policies and other group-specific metadata.

```javascript
var respecConfig = {
  group: "webapps",
};
```

--------------------------------

### Defining a Term

Source: https://respec.org/docs

Use the `<dfn>` tag to define a term. This allows for consistent linking and referencing throughout the document.

```html
<p>The <dfn>fetch</dfn> algorithm retrieves a resource.</p>
```

--------------------------------

### Define Interface Members with data-dfn-for

Source: https://respec.org/docs

Use `data-dfn-for` on a `<section>` to set the context (e.g., interface name) for all definitions within that section. This is useful for defining members of an interface.

```html
<section data-dfn-for="Request" data-link-for="Request">
  <h2><code>Request</code> interface</h2>
  <pre class="idl">
  interface Request {
    readonly attribute USVString method;
    Promise&lt;Response> clone();
  };
  </pre>
  <p>The <dfn>Request</dfn> interface represents a resource request.</p>
  <p>The <dfn>method</dfn> attribute returns the request method.</p>
  <p>The <dfn>clone()</dfn> method returns a copy of the request.</p>
</section>
```
Tokens:
Raw