ReSpec Documentation

The recommended pattern is a <section data-dfn-for="InterfaceName"> that groups the IDL block with prose definitions for each member:

<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|.</li>
    </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>

data-dfn-for on a <section> sets the default interface context for all <dfn> elements within it. This saves repeating the interface name on every definition:

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

Without data-dfn-for, use explicit for= attributes on individual <dfn> elements.

Define constructors with <dfn constructor for="InterfaceName">:

<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>
  <li>Set |w|'s {{Widget/name}} to |name|.</li>
  <li>Return |w|.</li>
</ol>

Link to the constructor from prose: {{Widget/constructor(name, options)}}.

Enum values defined in the IDL block are automatically linked. To add prose descriptions, define them explicitly using data-dfn-type="enum-value" and data-dfn-for:

<pre class="idl">
enum RequestMode { "navigate", "cors", "no-cors", "same-origin" };
</pre>

<p>The <dfn data-dfn-type="enum-value" data-dfn-for="RequestMode">"cors"</dfn>
mode means cross-origin requests are sent with CORS headers.</p>

<p>The <dfn data-dfn-type="enum-value" data-dfn-for="RequestMode">"navigate"</dfn>
mode is used for top-level navigation.</p>

Link to enum values in prose: {{RequestMode/"cors"}}.

Dictionary members defined in IDL are automatically linked. Reference them in prose as {{DictionaryName/memberName}}:

<pre class="idl">
dictionary RequestInit {
  ByteString method = "GET";
  boolean keepalive = false;
};
</pre>

<p>If |init|'s {{RequestInit/method}} is not a [=method=], throw a {{TypeError}}.</p>

If two interfaces share attribute or method names, use data-dfn-for to distinguish them:

<section data-dfn-for="Request">
  <p>The <dfn>url</dfn> attribute of {{Request}}.</p>
</section>

<section data-dfn-for="Response">
  <p>The <dfn>url</dfn> attribute of {{Response}}.</p>
</section>

When defining IDL members as prose <dfn> elements, you can omit data-dfn-type when data-dfn-for is set on the containing section — ReSpec infers the type from the IDL. For explicit control:

• The <pre class="idl"> block is syntax-highlighted and validated by ReSpec
• IDL terms are automatically added to the terms index and IDL index
• Use class="exclude" on a <pre class="idl"> to keep it out of the IDL index: <pre class="idl exclude">
• See data-dfn-type for the full list of definition types

You can alias WebIDL method names if you think the original name is adding noise.

The syntax is [=concept you want to link to=]. For example, [=queue a task=] and [=fire an event=].

To link to a concept in another spec, you need to use the xref configuration option, and simply cite the spec you want to link to:

<p data-cite="HTML DOM">
  You can [=queue a task=] to [=fire an event=] named `"respec-is-amazing"`.
</p>

In the above, "queue a task" is defined in the HTML specification while "fire and event" is defined in the DOM specification.

See xref for more information.

ReSpec supports automatically linking to plural forms for simple nouns. Thus, [=fruits=] links to the singular concept of fruit, even across specs.

Always try to adapt your text to a defined concept, and only use an alias if absolutely needed! This keeps specs consistent and keeps things easier to find across specs.

Having said that, sometimes [=convoluted thing=] might be confusing or not make sense in the context of your spec. In such cases, use a pipe | to "alias" a given concept into something that better fits the flow of your spec.

For example, with [=convoluted thing|simpler thing=], simpler thing will be the text on your spec. It will link to convoluted thing.

Another reason is that the definition’s default name does not grammatically fit into your sentence. For example, your definition is [=queue a task=] but you are giving an example of "task queuing". Alias the concept with [=queue a task|task queuing=] (again, don't do this! fix your spec instead or talk to the other editors of the other spec to export a more sane definition 🙇‍♂️).

Just as WebIDL interfaces can have methods and attributes, concepts have a very specific relationship to each other.

For example, the definition of a forEach() method for a list behaves differently from the definition of forEach() method for a map: the former operates on a single item, while the letter operates on a key/value pair. To make the relationship clear, we would write [=map/for each=], which is different to, say, [=list/for each=].

To associate a concept with another concept, use data-dfn-for to indicate who or what owns the concept. This tells Respec who or what the concept is "for". See the example below:

A <dfn>car</dfn> has a <dfn data-dfn-for="car">engine</dfn>, which burns petroleum.
A <dfn>browser</dfn> has a <dfn data-dfn-for="browser">engine</dfn>, which burns
democracy.

Add : and the data type after the variable's name.

For example, |value:DOMString| tells Respec that the variable value is of type {{DOMString}}.

ReSpec tracks declared variables within algorithms, allowing users to click on them to have them highlighted.

This helps readers know where variables were declared and where they are used. If the variable has is type information, ReSpec also propagates this throughout an algorithm. When a reader hovers over a variable, Respec presents information about the variable's type (see an example - GIF, 2.8MB).

• Enabled by default for W3C documents — section markers (§) appear on hover next to each heading
• Clicking a § link copies the section URL to the clipboard (or navigates to it)
• Disable if your document uses a custom heading layout where the markers cause visual issues

• In most cases, editors is preferred over authors for W3C specifications
• Use authors for major contributors who are not editors, or when the document follows a format that distinguishes authors from editors
• See person for full documentation of person object fields

• The caniuse widget requires JavaScript — in saved/exported HTML it is replaced by a plain link to caniuse.com
• The feature key is the slug from the caniuse.com URL: https://caniuse.com/FEATURE-KEY
• wf-* prefixed features (Baseline/web-features) are not yet supported — they come from a different data source
• To find the right feature key, browse caniuse.com and copy the URL slug

• When github is set, edDraftURI is automatically derived from the repo — you usually don't need to set it manually
• Set to null to suppress the link: edDraftURI: null
• For published W3C documents, editors' drafts are typically hosted on GitHub Pages (https://w3c.github.io/short-name/)

• See person for full documentation of all person object fields and the extras format
• To credit former editors, use formerEditors, or set retiredDate to keep them listed inline
• For non-editor contributors, use authors

• To use Markdown for only specific included sections, use data-include-format="markdown" instead of setting this globally
• When using format: "markdown", keep all text flushed to the left — Markdown is whitespace-sensitive
• See the Markdown guide for detailed usage, examples, and known limitations

• Use formerEditors to keep a clean current editors list while acknowledging past contributors
• Alternatively, add a retiredDate to a person in editors to show them inline as "until [date]"
• See person for full documentation of person object fields

• Setting github auto-populates edDraftURI — no need to set it separately
• For monorepos where multiple specs share one repository, use pullsURL and commitHistoryURL to filter to your spec's files

• Variables must be marked up with <var> elements: Let <var>request</var> be a new request.
• Highlighting is scoped to the nearest enclosing .algorithm list or <section> — whichever is closest
• Clicking multiple variables gives each a distinct highlight color (up to 7 colors)
• The |variable| shorthand automatically generates <var> elements

• Shows a large red "Preview" banner — intentionally attention-grabbing
• Useful for PR preview deployments to avoid readers accidentally citing a draft-of-a-draft
• Do not set in production specs

• For most W3C specifications, the default is correct — no need to set license explicitly
• cc0 is intended for documents heading to the WHATWG; W3C does not support it

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

Then cite it in the document as [[MY-SPEC]] (informative) or [[!MY-SPEC]] (normative).

• Prefer contributing to SpecRef — localBiblio should be a last resort. Entries in SpecRef benefit all specs, not just yours.
• To override a SpecRef entry for this document only, use the same key with your custom values
• Keys are case-insensitive in citations ([[fetch]] and [[FETCH]] refer to the same entry)

• Setting logos replaces the default W3C logo — include the W3C logo explicitly if you need it alongside your custom logo
• SVG logos are recommended for crisp rendering at any size

• maxTocLevel: 0 (default) includes all heading levels in the ToC
• Use data-max-toc="N" on individual sections to override for that subtree
• For very large specs, limiting ToC depth improves readability

• MDN annotations are collapsed by default — click to expand a panel showing browser support and a link to MDN
• Each panel shows an engine support summary (✅ all engines / 🚫 limited) and per-browser version data
• Annotations appear next to relevant section IDs that match MDN's data — not all sections will have annotations
• To find the right key, look up your spec URL in SPECMAP.json

• Only used when making an in-place editorial correction to a published document (no new publication date)
• Format must be "YYYY-MM-DD"
• For substantive changes, use a new publishDate instead

• Web Monetization is an emerging payment standard for the web
• Setting false disables monetization and removes the default ReSpec pointer

• To exclude individual sections from the ToC rather than removing it entirely, add class="notoc" to the section — see notoc-class

Each entry in otherLinks is an object:

Each item in data:

• Appears in the document header alongside "Editors", "Authors", and "Feedback" links
• Multiple otherLinks entries each get their own section heading

• Pluralization uses an English pluralization library — it handles irregular forms reasonably well but may miss edge cases
• Plurals are only added for terms that are actually referenced — no overhead for unreferenced terms
• Use data-lt-no-plural to suppress pluralization for acronyms, brand names, or terms where pluralization would be wrong
• See also data-lt for manually defining alternative forms

Each function receives three arguments:

• Functions run in order, awaiting async functions before proceeding
• At this point: headings are numbered, ToC is built, dfn panels are generated, xrefs are resolved, boilerplate is inserted. You are working with the final output.
• Changes appear in both the live preview and the saved HTML export
• To be notified when ALL processing is complete (including postProcess), use document.respec.ready
• For pre-processing before ReSpec starts, see preProcess

Each function receives three arguments:

• Functions run in order, and ReSpec awaits each one before proceeding
• async functions are fully supported
• preProcess runs before any ReSpec transformation — the document is still in its original source form. Definitions, headings, and xrefs have not yet been processed.
• For post-processing after ReSpec is done, see postProcess

• Format must be "YYYY-MM-DD"
• For "ED" status, omit this — ReSpec uses the browser's last-modified date, which is always current
• For published documents ("WD", "CR", "REC", etc.), set this to the actual publication date
• The browser's last-modified date can occasionally be wrong due to server timezone issues — if you see wrong dates on "ED" specs, set publishDate explicitly

• Must match exactly the short name registered with W3C for published documents
• Used to construct: the TR URL, the Editor's Draft URL (when edDraftURI is not set), and the mdn annotation key (when mdn is true)
• For Community Group reports, use the CG's assigned short name
• Short names are typically lowercase with hyphens (e.g. "fetch", "web-animations", "css-color-5")

• "ED" is the default — it does not appear on W3C TR/; safe for active development
• Use noRecTrack if the document should not follow the Recommendation track
• For "unofficial", content is auto-licensed under CC-BY v3.0; use license to change this
• See W3C Standards and Draft document types for the normative definition of each document type

• Include brackets if you want them (e.g. "[my-spec]" not "my-spec")
• Only relevant when using a mailing list for feedback (via wgPublicList or similar)
• With github configured, GitHub issues are the preferred feedback channel

• For spec level numbers, prefer level which integrates with shortName and ToC numbering

• Required when using the wpt-tests-exist linting rule — ReSpec uses this URL to validate data-tests paths
• Can be a WPT URL (https://wpt.fyi/...), GitHub URL, or any test suite URL
• Use https://github.com/web-platform-tests/wpt/tree/HEAD/your-spec/ for the WPT GitHub tree view

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>

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.

• 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

• For W3C documents: appended to the standard W3C copyright notice ("Copyright © [year] W3C® and [holder]")
• For "unofficial" documents: replaces the default CC license text entirely
• The value is rendered as HTML — you can include links or special characters

• Each entry requires both label (display text) and uri (URL)
• Links appear in the document header under "Also available in:"
• You are responsible for generating and hosting the alternate format files — ReSpec only links to them

• Use "TR" for the published version to ensure search engines index the stable W3C TR/ URL rather than the Editor's Draft
• Omit for documents where canonicalization isn't needed (e.g. unofficial drafts)

• Only relevant for Interest Group Notes — ignored for all other document types
• Must point to the disclosure section in the group's charter document

• If copyrightStart equals the publishDate year, it has no effect (year range is suppressed)
• Safe to always set — if it matches the publish year, ReSpec ignores it
• Use the year the spec work first began, not when the first draft was published

• Required for "CR" and "CRD" — ReSpec will warn if missing
• Also required for "PR" (alongside prEnd)
• Format must be "YYYY-MM-DD"
• This is the date the group commits to maintaining the document at its current maturity level until

• Also requires canonicalURI and license to be set for the JSON-LD to be complete
• Generated metadata includes: document title, editors, abstract, citations, publish date, copyright
• The JSON-LD uses the TechArticle schema.org type

• Primarily used for "REC" documents that have accumulated corrections since publication
• For active specs still being edited, corrections go into the spec itself rather than a separate errata document

The group type determines which specStatus values are valid. Using the wrong combination produces an error.

var respecConfig = {
  group: "wicg",
  specStatus: "CG-DRAFT",  // NOT "ED" — that's for Working Groups
};

• Browse available group short names at respec.org/w3c/groups/
• The group option auto-populates patent policy, group homepage link, mailing list, and participant count
• For closed groups not listed at respec.org/w3c/groups/, use the type/shortname form (e.g. "wg/csv") and refer to w3.org/groups/ to find the correct values
• When a CG and WG share the same shortname, use the prefix form to disambiguate: "cg/wot" vs "wg/wot"
• Replaces: wg, wgId, wgURI, wgPatentURI, wgPublicList — do not use those deprecated options alongside group

• Required or strongly recommended for "CR" — reviewers need to see implementation status
• Can link to a wpt.fyi results page, a GitHub page, or a custom report

• For standard W3C Working Group specs, you normally don't need to set this
• Set to null to suppress the "Latest Published Version" link entirely
• For Community Groups publishing on GitHub Pages, set this to your GitHub Pages URL

• Appends "Level N" to the document title
• Appends the level number to shortName (e.g. css-color-5)
• Level must be a non-negative integer
• ⚠️ Use with care — leveled specs are hard to maintain if multiple levels evolve concurrently. Only use if your working group has a clear leveling policy (like CSS WG does).

• Use when specStatus is a Notes-track value ("DNOTE", "NOTE", "STMT") to make this explicit
• ReSpec warns if a Rec-track specStatus is set alongside noRecTrack: true

• Required for "PR" — ReSpec will warn if missing
• "PR" also requires crEnd
• Format must be "YYYY-MM-DD"

• Rarely needed — most specs stay in the same repository
• Use when a spec has genuinely moved and linking to the previous ED location helps readers find the history

• Rarely needed — most specs just diff against the immediately previous version
• Use when the default diff target isn't the version you want to compare against

• Always set together with previousPublishDate
• The value must be a valid specStatus identifier (e.g. "WD", "CR", "FPWD")
• ReSpec does not validate whether the progression makes sense — the W3C Link Checker will catch mismatches before publication
• For "FPWD" (first publication), omit both fields

• Always set together with previousMaturity
• For "FPWD" (first publication), omit both — there is no previous version
• Format must be "YYYY-MM-DD"

• Generates a "Previous Recommendation" link in the document header
• Use when the current spec supersedes a Recommendation under a different shortName
• Also see prevRecURI to specify the full URL instead of the shortName

• Prefer a dated URL over the /TR/shortname/ shortcut — if the Recommendation is later rescinded, the undated link may become stale or redirect
• If omitted but prevRecShortname is set, ReSpec auto-generates https://www.w3.org/TR/prevRecShortname/

• Generates a link to https://www.w3.org/Submission/[year]/[number]/Comment/ in the header
• W3C staff assigns this number as part of the submission process

Add class="override" to take full control and write your own conformance text without any generated boilerplate:

<section id="conformance" class="override">
  <h2>Conformance</h2>
  <p>This document defines requirements for implementations. An implementation
  is conformant if it satisfies all the normative requirements herein.</p>
</section>

• Required for specifications that contain normative material (MUST, SHALL, etc.)
• The boilerplate includes the RFC 2119 keyword definitions ("MUST", "SHOULD", "MAY", etc.)
• Your custom text follows the boilerplate — it can include additional conformance classes, profiles, or requirements
• If the section is empty, only the boilerplate is shown
• class="override" skips all generated content — the section is left exactly as authored

• Contributors are sorted alphabetically by GitHub username or display name
• Requires github to be configured in respecConfig
• Fetches contributor data from the GitHub API — contributors list may be large for active repositories

Add class="exclude" to any <pre class="idl"> to keep it out of the IDL index — useful for non-normative illustrative examples:

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

IDL blocks inside non-normative sections (class="informative") are automatically excluded.

• Collects every normative <pre class="idl"> block in the document and combines them
• IDL blocks with class="exclude" or inside informative sections are skipped
• If the spec has no normative WebIDL, the section shows: "This specification doesn't normatively declare any Web IDL."
• Add custom content (heading, intro paragraph) before the IDL — ReSpec appends the IDL after it
• Typically placed as an informative appendix

• Shows both locally defined terms (<dfn>) and externally referenced terms (via xref)
• Clicking a term in the index jumps to its definition or first use in the document
• Adding class="prefer-full-spec-title" shows full spec titles (e.g., "DOM Standard") instead of shortnames (e.g., "[DOM]")
• Typically placed as an informative appendix

• Collects all elements with class="issue" across the document
• Each entry includes the issue number (if data-number is set), the title (if title attribute is set), and a link back to the issue in the document
• Useful for tracking all open issues in a spec at a glance during review
• Typically placed as an informative appendix

• If you don't add <section id="references">, ReSpec still generates the references section automatically
• Custom content is placed before the auto-generated reference lists
• References are generated from [[CITE]] usage throughout the document plus any localBiblio entries

• All <figure> elements with a <figcaption> are included — ReSpec auto-generates IDs from the caption text if no id is set
• ReSpec auto-generates a "Table of Figures" heading if none is provided
• Typically placed as an appendix: <section id="tof" class="appendix">
• Also see the auto-numbering of figures — empty <a href="#figure-id"> links auto-fill with "Figure N"

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

This uses the official W3C dark stylesheet from tr-design and respects the user's prefers-color-scheme preference.

The ReSpec pill includes a dark mode toggle that overrides the system preference. This toggle injects a .darkmode class on <body> via JavaScript.

Because the manual toggle uses a JavaScript-injected class rather than a CSS media query, custom CSS must target both approaches:

/* System preference */
@media (prefers-color-scheme: dark) {
  .my-custom-element { background: #1a1a1a; }
}

/* ReSpec manual toggle */
body.darkmode .my-custom-element { background: #1a1a1a; }

• Dark mode styles are part of the W3C TR design system — only available for W3C specs
• The .darkmode class limitation is a known architectural issue; the CSS prefers-color-scheme media query does not respond to JS-injected class names
• For specs with heavy custom CSS, you will need to duplicate your dark-mode rules to cover both the media query and the .darkmode class

<figure id="flowchart">
  <img src="flowchart.svg" alt="Water flows from bucket A to bucket B" />
  <figcaption>The water flows from bucket A to bucket B.</figcaption>
</figure>

<p>As shown in <a href="#flowchart"></a>, the flow is one-directional.</p>

The empty <a href="#flowchart"> auto-fills with "Figure N" text.

• Figures are numbered automatically ("Figure 1", "Figure 2", …)
• A <figcaption> is required — figures without one generate a ReSpec warning
• Empty links to a figure's id auto-populate with "Figure N"
• A self-link (§) is generated so readers can link directly to a specific figure
• Generate a list of all figures with tof (Table of Figures)
• The <figcaption> should be a proper caption describing the figure, not just a title

• ReSpec warns if the <title> element text and the <h1 id="title"> text content don't match — keep them in sync
• Only one <h1 id="title"> is allowed
• The <title> element is still required for the HTML document — the <h1> overrides the rendered title only

abnf, css, html, http, javascript (js), json, xml, webidl

• Highlighting is done in a Web Worker and is non-blocking
• Language is auto-detected if no class is specified
• Use nohighlight to disable for a block
• Use nolinks to prevent auto-linking of URLs inside code blocks (Markdown mode)