Skip to content

ReSpec Editor's Guide

Jump to bottom Edit New page
Marcos Caceres edited this page Mar 28, 2026 · 97 revisions

A ReSpec document is an HTML file that brings in the ReSpec script, defines a configuration object, and follows a few conventions. Open it in a browser over HTTP and ReSpec transforms it into a properly formatted specification.

A complete example

<!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>

Preview it: Open the file via a local HTTP server — not file:// (browsers block fetches from file://):

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

Then open http://localhost:PORT/your-spec.html.

Including ReSpec

Add these two <script> elements to the <head>. The class="remove" ensures they are stripped from the exported static 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>

Note: var is required — ReSpec reads this as window.respecConfig. const or let would not be visible to the ReSpec bundle.

ReSpec is continuously updated. Loading it from w3.org/Tools/respec/ means you automatically get the latest bug fixes and features.

Configuring ReSpec

All configuration options are documented in this reference. The minimum required options are specStatus and editors. For W3C working group documents, also set group.

var respecConfig = {
  specStatus: "ED",
  editors: [{ name: "Your Name", url: "https://your-site.example/" }],
};

Configuration can also be overridden via URL query params — useful for generating snapshots without editing the source: index.html?specStatus=WD&publishDate=2025-06-01.

Document structure

ReSpec documents are HTML. They use standard HTML structural elements with a few conventions.

Title

Set the document title using the <title> element. ReSpec uses it to generate the <h1> heading.

<title>Payment Request API</title>

If you need markup in the title (e.g., <code>), use <h1 id="title"> instead. See <h1 id="title">.

Subtitle

Add a subtitle either in config or as markup:

var respecConfig = {
  subtitle: "Level 2",
};
<h2 id="subtitle">Level 2</h2>

Editors and authors

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",
    },
  ],
};

See person for all available fields.

Sections

Wrap content in <section> elements. ReSpec handles numbering, IDs, and ToC entries automatically.

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

Empty links to a section's ID auto-fill with "§ N.N Title":

<p>As described in <a href="#concepts"></a>...</p>
<!-- Renders: As described in § 2 Concepts... -->

Section classes: informative, appendix, notoc.

Table of Contents

Generated automatically after the SotD section. Control depth with maxTocLevel. Suppress with noTOC: true.

Figures

<figure id="fig-overview">
  <img src="overview.svg" alt="System overview diagram" />
  <figcaption>System overview.</figcaption>
</figure>

<p>See <a href="#fig-overview"></a> for the system overview.</p>
<!-- Renders: See Figure 1 for... -->

Generate a Table of Figures with <section id="tof">.

Examples, notes, and issues

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

Syntax highlighting

Code inside <pre> is automatically syntax-highlighted using highlight.js. Specify the language with a class:

<pre class="js">const x = 1;</pre>
<pre class="css">.widget { color: red; }</pre>
<pre class="webidl">interface Foo {};</pre>

Use class="nohighlight" to disable. Use class="nolinks" to prevent URLs from becoming hyperlinks.

External includes

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

Requires HTTP — file:// URLs will fail due to browser CORS restrictions. See data-include.

Conformance

<section id="conformance">
  <!-- RFC 2119 boilerplate added automatically -->
  <p>Additional conformance text here.</p>
</section>

Required for specs with normative requirements. Adds RFC 2119 keyword definitions (MUST, SHOULD, MAY, etc.).

Abbreviations

<p>The <abbr title="World Wide Web Consortium">W3C</abbr> develops web standards.</p>
<!-- All subsequent occurrences of "W3C" are automatically wrapped in <abbr> -->

Or use data-abbr on a <dfn> to auto-generate abbreviations.

Definitions and linking

Define a term

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

Link to a defined term

<p>Run the [=fetch=] algorithm.</p>
<p>Run the <a>fetch</a> algorithm.</p>
<!-- Both produce: Run the fetch algorithm (as a link) -->

Automatic pluralization

<dfn>request</dfn>

<!-- All of these link correctly: -->
<a>request</a>
<a>requests</a>
[=request=]
[=requests=]

Alternative terms and aliases

<dfn data-lt="user agent|browser">user agent</dfn>

<!-- All link to the same definition: -->
[=user agent=]  [=browser=]

See data-lt.

Referencing terms from other specifications

Enable xref and write terms naturally — ReSpec finds them automatically:

var respecConfig = {
  xref: "web-platform", // includes HTML, Infra, URL, WebIDL, DOM, Fetch
};
<p>
  [=Queue a task=] to [=fire an event=] named "load"
  at the {{Window}} object.
</p>

Browse available terms at respec.org/xref.

Linking shorthands

Syntax Links to
[=term=] Concept or abstract term
{{Interface}} WebIDL interface
{{Interface/member}} WebIDL member
[^element^] HTML/SVG element
[[SPEC]] Informative bibliography reference
[[!SPEC]] Normative bibliography reference
[[[#section-id]]] Section in this document
[[[SPEC#section-id]]] Section in another spec

See the Shorthands Guide for full syntax.

References

The [^link^] element is defined in [[HTML]].
This MUST NOT be done per [[!RFC2119]].

ReSpec auto-generates a References section from all [[SPEC]] citations. Spec IDs come from Specref — which includes most W3C, WHATWG, ECMA, and IETF documents.

For a non-normative reference in a normative section, use [[?SPEC]].

To add a missing reference, contribute it to Specref or use localBiblio.

Normative vs. informative references

ReSpec infers from context: references in informative sections, notes, examples, or figures become informative automatically. References in normative sections are normative.

W3C documents

Working group

var respecConfig = {
  group: "webapps", // see respec.org/w3c/groups/ for shortnames
};

group configures patent policy, group homepage, and mailing list automatically. It replaces the old wg, wgId, wgURI, wgPatentURI, and wgPublicList options.

Specification status

specStatus sets the document maturity level. Common values:

Value Description
"ED" Editor's Draft (default — for active development)
"WD" Working Draft
"CR" Candidate Recommendation
"REC" Recommendation
"CG-DRAFT" Community Group Draft

See specStatus for the full list.

Publishing to W3C TR/

For TR/ publication:

var respecConfig = {
  specStatus: "WD",
  publishDate: "2025-06-15",
  previousPublishDate: "2024-12-01",
  previousMaturity: "FPWD",
  group: "webapps",
  shortName: "my-api",
};

Export to static HTML first (ReSpec pill → Save as HTML), then submit via Echidna or the W3C publication tools.

Copyright and patents

By default, W3C specs use the standard W3C copyright and the group's patent policy (set via group).

To modify: use license, copyrightStart, or additionalCopyrightHolders.

Add custom patent notes directly into <section id="sotd">.

💖 Support ReSpec by becoming a sponsor via Open Collective. 💖

✨ View rendered version of this documentation at https://respec.org/docs/ ✨

Guides

Configuration options

W3C Configuration options

Linting rules

Internal properties

Handled by ReSpec for you.

Special <section> IDs

HTML elements

Custom Elements

HTML attributes

CSS Classes

Special properties

Clone this wiki locally