ReSpec Documentation

1.1 Including ReSpec📝 Edit

The following code is used to include a ReSpec document:

  <script src="https://www.w3.org/Tools/respec/respec-w3c" class="remove" defer></script>
  <script class="remove">
   var respecConfig = {
     // configuration options
   }
  </script>

ReSpec is regularly updated and this will allow you to automatically benefit from bug and security fixes and enhancements.

1.2 Specifying Configuration via JS📝 Edit

ReSpec is configured using a JSON-like object, which is assigned to a respecConfig JavaScript variable:

  <script class="remove">
   var respecConfig = {
     // configuration options
   }
  </script>

1.3 Structure📝 Edit

This chapter covers all the aspects of a ReSpec document's structure that were not covered as part of the very basics. As usual, let's start with an example. It is fairly long as it needs a decent amount of content in order to exemplify some features, but it should nevertheless be easy to understand. Go on, open the example in new tab (omitted here for brevity).

<h1 id="title">The <code>Foo</code> API</h1>

<h2 id="subtitle">Subtitle here</h2>

1.3.2 Editors & Authors📝 Edit

Every specification must have some editors (at least one) and may have some authors (and maybe some former editors/authors also). Editors and authors are specified as Person objects.

Editors are the people in charge of the document. Authors are people who produced substantial contributions, but did not manage the document per se. Most of the time authors are not specified, but that practice varies between groups:

Example 4: Specifying editors and authors.

var respecConfig = {
  // ...
  editors: [
    {
      name: "Robin Berjon",
      url: "https://berjon.com/",
      company: "W3C",
      companyURL: "https://w3c.org/",
      mailto: "robin@berjon.com",
      note: "A Really Cool Frood",
    },
    {
      name: "Billie Berthezène-Berjon",
      company: "Catwoman",
    },
  ],
  authors: [
    {
      name: "Ada Lovelace",
      url: "https://findingada.com/",
      company: "Aristocracy",
      retiredDate: "1852-11-27",
    },
  ],
  // ...
};

Is rendered as:

1.3.3 Sections📝 Edit

ReSpec-based specifications require you to wrap your content in <section> elements. We provide specific information and examples on how to use <section> elements.

Sections, subsections, appendices, and whatever other structural items are marked up in ReSpec using <section> elements.

Example 5: Sections and sub-sections.

<section>
  <h2>A section</h2>
  <p>Some text.</p>
  <section class="informative">
    <h3>I'm a sub-section</h3>
    <p>Subsetion text.</p>
  </section>
</section>

Which is rendered as:

As shown, sections are automatically numbered. If you wish a section to have a specific ID, then simply use an id attribute on it. If you don't, ReSpec will generate one for you based on the section title, and will ensure that it is unique.

ReSpec sections understand some specific CSS classes: introductory, informative, and appendix.

If you wish to link to a section and have its number and title automatically appear as part of the link, then you can use the special syntax[[[!#some-id]]].

1.3.5 Figures📝 Edit

Figures are also supported natively, using the <figure> and <figcaption> elements, and exhibit some features similar to sections. They are automatically granted an ID, and the caption is remembered for use elsewhere, as described below.

Example 6: Figure and list of figures.

<figure id="figure">
  <img src="figure.svg" alt="W3C Logo" />
  <figcaption>The W3C logo</figcaption>
</figure>

Which renders as:

Automatic linking to figures works just as it does for sections, with [[[!#some-figure]]].

The "List of Figures" is not generated by default: to add one, include <section id="tof"> anywhere in the document. ReSpec will do its best to guess if it should be an appendix, introductory, or just a regular section.

Example 7: Generating a list of figures

<section id="tof"></section>

Renders as:

1.3.8 Common Inline Processing📝 Edit

Many repetitive tasks happen at the level of inline text, and ReSpec helps with those as well. This chapter covers references, along with the SpecRef database, the handling of abbreviations and acronyms, automatic RFC 2119 keyword detection, dfn definitions, and easier in-document linking.

RFC2119 Keywords📝 Edit

ReSpec specifications are RFC2119 keyword aware (i.e., it knows about "MUST", "SHOULD NOT", etc.).

Adding a <section id="conformance"> tells ReSpec that the specification is dealing with "normative" statements. ReSpec can then warn if RFC2119 keywords are accidentally used in informative/non-normative contexts.

Example 8: Using RFC2119 keywords

<section>
  <h2>Requirements</h2>
  <p>A user agent MUST do something.</p>
</section>
<section id="conformance"></section>

Renders as:

Abbreviations & Acronyms📝 Edit

HTML supports functionality to mark abbreviations and acronyms (using <abbr>), using the title attribute to provide the expanded version. This is something that's nice to do once, but tedious to repeat every time that a given term is used. What ReSpec does is that it allows you to do it just once, and it will detect all other uses of the same in the text and will automatically mark them up in the same way.

<p>The <abbr title="world wide web">WWW</abbr>.</p>
<p>The WWW.</p>

Inline Code📝 Edit

To mark some text as code, we need to wrap it in <code> elements. ReSpec lets you wrap text in backticks (`) to mark it as code, which is usually more comfortable.

<dfn>some concept</dfn>

<a>some concept</a>

or 

[=some concept=]

<dfn>banana</dfn>
<!- these are the same -->
These [=bananas=] are better than those <a>bananas</a>

<dfn
  data-lt="the best fruit|yellow delicious">
  banana
</dfn>

<p>[=the best fruit=] or the [=yellow delicious=].</p>

<script>
  var respecConfig = {
    xref: ["WebIDL"],
  };
</script>
<a>default toJSON steps</a>

<script>
  var respecConfig = {
    xref: ["webidl", "payment-request"],
  };
</script>
<section>
  <!--
    Here, we reference the "default toJSON steps" concept defined in [[WebIDL]] standard,
      and the PaymentRequest interface (WebIDL) defined in [[payment-request]] standard.
  -->
  <p>[=default toJSON steps=] for the {{PaymentRequest}} interface are ...</p>

  <!-- We also define a concept "feline", and an interface "Cat". -->
  <p>A <dfn>feline</dfn> has 4 legs and makes sound.</p>
  <pre class="idl">
  interface Cat {}
  </pre>

  <!-- ...and we can reference them as: -->
  <p>A {{Cat}} is a [=feline=] if it meows.</p>
</section>

This is normative and MUST be followed. But, sometimes we need a non-normative
example reference [[?FOO]].

1.4 Essential W3C Boilerplate📝 Edit

W3C boilerplate is extremely repetitive, but beneath the tedium is a wealth of options and subtle variations that are precisely what makes crafting the boilerplate by hand so hard to get right. This covers options for specification maturity, publication dates, alternatives (editor's drafts, other versions, other formats...), legalese variants, the various W3C specification URLs, the people writing it, information about the working group, and core sections such as Abstract, Status of this Document (SotD), and Conformance.

We will start by using an example of a basic specification very similar to the one used in the previous section.

<div class="practice">
  <p>
    <span id="some-practice" class="practicelab">Title of the practice</span>
  </p>
  <p class="practicedesc">
    More detailed description of the practice.
  </p>
</div>

<section id="bp-summary"></section>

1.5 WebIDL Guide📝 Edit

To specify an interface using WebIDL, you define a <pre class="idl"> block. For example:

<pre class="idl">
interface Request {
  readonly attribute ByteString method;
  readonly attribute USVString url;
};
</pre>

<section data-dfn-for="ExampleInterface">
  <h2><dfn>ExampleInterface</dfn> interface</h2>
  <pre class="idl">
  interface ExampleInterface {
    void exampleMethod();
    readonly attribute USVString url;
  };
  </pre>
  <section>
    <h2><dfn>exampleMethod()</dfn> method</h2>
    <p>Define {{ExampleInterface/exampleMethod()}} here...</p>
  </section>
  <section>
    <h2><dfn>url</dfn> attribute</h2>
    <p>Define {{ExampleInterface/url}} attribute here...</p>
  </section>
</section>
<section>
  <h2>Here is how you link!</h2>
  <p>The {{ExampleInterface}} or the {{ExampleInterface/exampleMethod()}}.</p>
</section>

<section>
  <h2><dfn>Request</dfn> interface</h2>
  <pre class="idl">
    interface Request {};
  </pre>
  <p>An instance of {{Request}} allows you to make a request.</p>
</section>

<section data-dfn-for="Request">
  <h2>`Request` interface</h2>
  <pre>
  interface Request {
    readonly attribute ByteString method;
    readonly attribute USVString url;
  };
  </pre>
  <p>The <dfn>clone()</dfn> method. The <dfn>url</dfn> attribute.</p>
  <p>
    Links to {{Request/clone()}} method. Links to the {{Request/url}} attribute.
  </p>
</section>

<pre class="idl">
interface Request {
  readonly attribute USVString url;
};
interface Response {
  readonly attribute USVString url;
};
</pre>

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

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

2.1 Using Browser📝 Edit

To save a snapshot from browser itself, click the ReSpec menu button on top-right side of page and select "Export" to open the export menu. Unless you know what you are doing, pick "HTML" as export format. This will produce a dump of the processed source, which you can download as a HTML file for your specification snapshot. The process is a little bit tedious, but normally you should only need to do it very rarely. You can hit Esc to hide the menu.

2.2 Using Spec Generator service📝 Edit

To produce static output for your spec source from the command line, you can use a command-line HTTP client such as wget or curl and POST your ReSpec source document to the W3C https://labs.w3.org/spec-generator/ spec-generator service as a file upload; for example:

curl -F "file=@source.html" https://labs.w3.org/spec-generator/ > index.html

That command causes curl to read the source.html file from the current directory, send an HTTP POST request with the contents of that file as the value of the file field in the request, and then write the response to the index.html file.

That index.html file is a dump of the source.html file’s DOM, generated by processing the source with ReSpec — that is, exactly the same output you get by manually picking "Export -> HTML" to save the output.

You can use additional -F flags with curl to specify particular ReSpec configuration options:

curl -F "file=@source.html" -F "shortName=dahut" -F specStatus="ED" \
     -F "publishDate=2020-02-21" https://labs.w3.org/spec-generator/ > index.html

One limitation of the service above is that it only supports single source file, i.e., we can't use data-include or split respecConfig in a separate file. Fret not, we got a CLI you can run locally!

2.3 Using CLI📝 Edit

If you want to generate your spec locally, we got a CLI tool for that! The tool, which is the official CLI for ReSpec — called respec2html — requires Node.js and npm installed on your computer.

To install the CLI, run:

npm install --global respec

Then use the CLI to generate a snapshot as:

respec2html --src source.html --out index.html

# "respec2html" is an alias for "respec". You can also run:
respec --src source.html --out index.html

If you wish to run above as a one-off script:

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

One benefit of using npx (apart from being shorter) is that you will always get the latest version of respec2html.

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"

For more options, run respec --help.

3.1 WebIDL📝 Edit

On the Web, and in Web Standards, WebIDL is a meta language that we use to define Javascript APIs. Please see our WebIDL Guide. Please see the WebIDL spec for more info.

To link to something in WebIDL, you need to know its identifier. An identifier is the name of the interface, dictionary, or enum.

For example, {{PaymentRequest}} links to the PaymentRequest interface.

You can link attributes, methods, or members by using the interface name, /, and the name of the thing you want to link to. For example, {{PaymentRequest/show()}} links to the show() operation of the PaymentRequest interface.

3.2 Concepts📝 Edit

Concepts include: ideas, named algorithms, useful terms, and/or non-webIDL things that are defined in a spec.

Basically, "defined" means that a thing is within <dfn> tags. For example, <dfn>success</dfn> and <dfn>the steps to make a great meal</dfn> are defined concepts.

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

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

3.3 Variables in algorithms📝 Edit

The syntax is |name|, where name is the name of the variable.

Let |value| be the {{DOMString}} "hello". ... If |value| is not "hello", then
do…

3.4 HTML Elements and attributes📝 Edit

To reference HTML elements, use the following syntax: [^tagname^]. * Here, the tagname is a valid HTML tag that is defined in the HTML spec or some other spec that defines the tag.

You can also link to particular content attributes of HTML elements by using a / after then tag name, followed by the name of the attribute you'd like to link to.

For example, [^iframe/allow^] links to the allow attribute for an iframe in the HTML spec.

3.5 Referencing other specifications📝 Edit

To reference another specification, just write [[FOO]] - where FOO is the short name or id of a specification. If you are don't know the the short name or id, please search for the spec at SpecRef.

5.1 a11y📝 Edit

Lints for accessibility issues using axe-core: "Axe is an accessibility testing engine for websites and other HTML-based user interfaces".

Basic example, runs all default plugins with a exception of a few slow ones.

var respecConfig = {
  a11y: true,
};

Example with Axe configuration, as per Axe's configuration options.

var respecConfig = {
  a11y: {
    runOnly: ["image-alt", "link-name"],
  },
};

Another example:

var respecConfig = {
  a11y: {
    // run all rules, except "image-alt" and slow rules (but run "color-contrast")
    rules: {
      "color-contrast": { enabled: true }, // disabled by default, enable it
      "image-alt": { enabled: false },
    },
  },
};

If the document has accessibility issues, they will show up as ReSpec warnings:

In an actual document, you can expand the details to get more information about each issue along with a link to the specific HTML element causing the issue.

5.2 addSectionLinks📝 Edit

Controls if linked "§" section markers are added to a document. This is enabled by default for W3C documents.

var respecConfig = {
  // turns off the § section markers
  addSectionLinks: false;
}

5.3 authors📝 Edit

Similar to editors, an array of person objects describing the authors of the document.

var respecConfig = {
  authors: [
    {
      name: "Marcos Caceres",
      company: "Mozilla Corporation",
      companyURL: "https://mozilla.org/",
      w3cid: 39125,
    },
    {
      name: "Kenneth Rohde Christiansen",
      company: "Intel Corporation",
      companyURL: "https://intel.com",
      w3cid: 57705,
    },
  ],
};

5.4 caniuse📝 Edit

Adds a Can I Use support table in the document header.

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

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

It renders as:

5.5 edDraftURI📝 Edit

The URL of the Editor's Draft, used in the header. This is required for when specStatus is "ED".

var respecConfig = {
  specStatus: "ED",
  edDraftURI: "https://www.w3.org/TR/example",
};

5.6 editors📝 Edit

An array of person objects describing the editors of the document. Editors have the same responsibility as authors, and are preferred in specifications.

var respecConfig = {
  editors: [
    {
      name: "Marcos Caceres",
      company: "Mozilla Corporation",
      companyURL: "https://mozilla.org/",
      w3cid: 39125,
    },
    {
      name: "Kenneth Rohde Christiansen",
      company: "Intel Corporation",
      companyURL: "https://intel.com",
      w3cid: 57705,
    },
  ],
};

5.7 format📝 Edit

Tells ReSpec to treat the document as being in a format other than HTML. Supported formats:

markdown

Interpreted as GitHub flavored markdown (GFM).

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

See: Using Markdown with ReSpec Guide.

5.8 formerEditors📝 Edit

An array of person objects describing the past editors of the document. formerEditors were added so as to avoid cluttering the present editors list and are shown just below the list of present editors.

var respecConfig = {
  formerEditors: [
    {
      name: "Marcos Caceres",
      company: "Mozilla Corporation",
      companyURL: "https://mozilla.org/",
      w3cid: 39125,
    },
    {
      name: "Kenneth Rohde Christiansen",
      company: "Intel Corporation",
      companyURL: "https://intel.com",
      w3cid: 57705,
    },
  ],
};

5.9 github📝 Edit

The github option allows you associate your specification with a repository on GitHub.

It takes either a string (URL to your repo or a string of format: org/repo) or an object with the following properties:

• repoURL - the URL for the repository (e.g., https://github.com/w3c/browser-payment-api)
• branch - optional, the branch you are using for GitHub pages. It defaults to "gh-pages".

This automatically generates:

• githubAPI
• issueBase
• edDraftURI

It also adds an object to otherLinks for under "Participate", with the appropriate links to your GitHub repository.

This is normally what you want:

var respecConfig = {
  github: "w3c/browser-payment-api",
};

var respecConfig = {
  github: "https://github.com/w3c/browser-payment-api",
};

This example shows a repository whose specs are being served from a "public-docs" branch.

var respecConfig = {
  github: {
    repoURL: "https://github.com/w3c/browser-payment-api",
    branch: "public-docs", // alternative branch
  },
};

5.10 highlightVars📝 Edit

With long algorithms in a specification, it can be useful to allow readers to click on variables marked up with <var> (e.g., Let <var>elem</var> be ...). By setting the respecConfig.highlightVars configuration option, readers can now click on vars in an algorithm to see where they are used.

var respecConfig = {
  highlightVars: true,
};

It renders as:

5.11 isPreview📝 Edit

The isPreview adds an annoying red box to your document, warning unsuspecting readers that they should not cite or reference this version of the specification.

This adds a big red ugly box to your document.

var respecConfig = {
  isPreview: true,
};

5.12 license📝 Edit

license can be one of the following:

cc-by

Experimentally available in some groups (but likely to be phased out).

Note that this is a dual licensing regime.

cc0

An extremely permissive license.

It is only recommended if you are working on a document that is intended to be pushed to the WHATWG.

w3c-software

A permissive and attributions license (but GPL-compatible).

w3c-software-doc

The W3C Software and Document License.

This is default for the W3C profile.

5.13 lint📝 Edit

A boolean used to enable/disable ReSpec's built-in linter for W3C documents. The linter is enabled by default, and warns you about:

• URLs in the config that are not HTTPS.
• Missing Privacy and/or Security sections.
• Possibly other useful things...

If you want to turn off the linter:

var respecConfig = {
  lint: false,
};

You can also enable or disable certain rules:

var respecConfig = {
  "no-http-props": false, // disable a rule that enabled by default
  "no-unused-vars": true, // enable a rule that disable by default
};

5.13.1 no-http-props📝 Edit

Enable this lint rule to get a warning if there exists some URL in respecConfig that starts with http://.

For example:

Example 46: A failing URL in respecConfig.

<script>
  var respecConfig = {
    implementationReportURI: "http://w3c.github.io/payment-request/reports/implementation.html",
                              ^^^^^
  };
</script>

You'll receive a warning pointing you to the violating properties in respecConfig.

Example 47: Enable no-http-props linter rule.

var respecConfig = {
  lint: {
    "no-http-props": true,
  },
};

5.13.2 local-refs-exist📝 Edit

Enable this lint rule to get a warning if there are some href's that link to nonexistent id's in a spec.

For example:

Example 48: Broken local reference.

<section id="foo"><!-- content --></section>

<a href="#bar">baz</a>
<!-- #bar doesn't exist in document -->

You'll receive a warning pointing you to the links that are broken.

Example 49: Enable local-refs-exist linter rule.

var respecConfig = {
  lint: {
    "local-refs-exist": true,
  },
};

5.13.3 no-headingless-sections📝 Edit

Enable this lint rule to get a warning if there is some <section> in the document that does not start with a heading element (h1-h6).

For example:

Example 50: A section that doesn't start with a heading.

<section id="foo">
  <!-- should've begun with a heading -->
  <p>content begins</p>
</section>

You'll receive a warning pointing you to the heading-less sections.

Example 51: Enable no-headingless-sections linter rule.

var respecConfig = {
  lint: {
    "no-headingless-sections": true,
  },
};

<section id="foo">
  <p>|varA| is defined here.</p>
  <ol class="algorithm">
    <li>|varA| is used here.</li>
    <li>|varB| is unused.</li>
    <li>|varC| is not unused as it's used again as |varC|.</li>
  </ol>
</section>

var respecConfig = {
  lint: {
    "no-unused-vars": true,
  },
};

<var data-ignore-unused>someUnusedVar</var> is unused, but warning is ignored.

<p>This has no punctuation at the end</p>

var respecConfig = {
  lint: {
    "check-punctuation": true,
  },
};

var respecConfig = {
  lint: {
    "privsec-section": false,
  },
};

<p id="a" data-tests="test.html,404.html"></p>
<!-- 404.html does not exist -->

var respecConfig = {
  testSuiteURI: "https://github.com/web-platform-tests/wpt/tree/HEAD/webrtc/",
  // alternatively:
  // testSuiteURI: "https://wpt.fyi/webrtc/",

  lint: {
    "wpt-tests-exist": true,
  },
};

5.14 localBiblio📝 Edit

If you need to include a one-off reference that isn't in the SpecRef database or if you need to override an existing reference with specific content, then you can use this configuration option.

You can find the format for these entries in the SpecRef repository.

var respecConfig = {
  localBiblio: {
    WEREWOLF: {
      title: "Tremble Puny Villagers",
      href: "https://w3.org/werewolf",
      status: "RSCND",
      publisher: "W3C",
    },
  },
};

5.15 logos📝 Edit

Overrides the standard W3C logo with one or more other logos.

The logos property takes an array that contains a set of objects. Each of these objects contains:

src

URL to the source.

alt

The alt attribute value.

height

The height of the image.

width

The width of the image.

id

The id of the image element.

url

Where to navigate to when the logo is pressed.

var respecConfig = {
  logos: [
    {
      src: "https://example.com/logo.gif",
      url: "https://example.com",
      alt: "The Example company",
      width: 100,
      height: 42,
      id: "example-company-logo",
    },
  ],
};

Would output:

<a class="logo" href="https://example.com">
  <span id="example-company-logo">
    <img
      src="https://example.com/logo.gif"
      width="100"
      height="42"
      alt="The Example company"
    >
  </span>
</a>

5.16 maxTocLevel📝 Edit

A number indicating the maximum depth of the table of contents, in case you wish to limit it so as to keep it more readable. Defaults to 0 which includes all levels.

var respecConfig = {
  maxTocLevel: 2,
};

5.17 mdn📝 Edit

The mdn option allows a spec to be annotated with links to MDN developer documentation.

If a boolean is provided, it uses spec's shortName to match data over on MDN.

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

If the shortName doesn't match the MDN key, you can provide a key as:

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

The key can be found at https://w3c.github.io/mdn-spec-links/SPECMAP.json. For example, the key is "image-capture" in the following entry:

"https://w3c.github.io/mediacapture-image/": "image-capture.json",

It renders as panels near relevant definitions in the right-side of the document:

5.18 modificationDate📝 Edit

A YYYY-MM-DD date. The in-place edit date of an already published document. Used in conjunction with publishDate, as per Pubrules.

var respecConfig = {
  publishDate: "2020-03-30",
  modificationDate: "2020-04-13",
};

5.19 noTOC📝 Edit

When this configuration variable is set to true, no table of contents is generated in the document.

var respecConfig = {
  noTOC: true,
};

There is a corresponding class of notoc.

5.20 otherLinks📝 Edit

Adds additional links to the header of the document. This is useful if you want to link to other resources, like a news feed, a GitHub repository, or a relevant website.

The otherLinks property takes an array that contains a set of objects. Each of these objects contains a key and a data property. The key is the text that will contain the links to the relevant resources. The data is another array of objects that contain the data describing the resource (with the properties value which is a string, and href which is the URL you want to link to). If a href is not provided, value is displayed as text.

var respecConfig = {
  otherLinks: [
    {
      key: "Implementation status",
      data: [
        {
          value: "Gecko",
          href: "https://bugzilla.mozilla.org/show_bug.cgi?id=xxxx",
        },
        {
          value: "Blink",
          href: "https://code.google.com/p/chromium/issues/detail?id=xxx",
        },
      ],
    },
  ],
};

Above is rendered as:

5.21 pluralize📝 Edit

Adds automatic pluralization support for <dfn>, so that you don't have to manually define data-lt attributes for plurals.

This is enabled by default for W3C specs.

var respecConfig = {
  pluralize: true,
};

You can define a term as <dfn>fetch</dfn> and reference it as either <a>fetch</a> or <a>fetches</a>. Below are some more examples:

<dfn>user agent</dfn> can be referenced as:
  • <a>user agents</a>
  • <a>user agent</a>
  • <a data-lt="user agent">browser</a>.

<dfn data-lt="pub">bar</dfn> can be referenced as:
  • <a>pub</a>
  • <a>bar</a>
  • <a>bars</a>
  • <a data-lt="pub">drinking establishment</a>
  • <a data-lt="bar">drinking establishment</a>
  • <a data-lt="bars">drinking establishment</a>

If you want to selectively disable pluralization on certain <dfn>, you can make use of data-lt-no-plural attribute like:

<dfn data-lt-no-plural>html</dfn>

5.22 postProcess📝 Edit

Takes an array of JavaScript functions. The functions are invoked in the order after ReSpec has processed the HTML source. The function’s signature includes a reference to the config object (i.e., the initial configuration object in the ReSpec source, plus some additional internal data) and the reference to the DOM Document element.

The following examples shows two functions run in order after processing.

function doThing(config, document){...}
function doOtherThing(config, document){...}

var respecConfig = {
  // After processing, run the following
  postProcess: [doThing, doOtherThing]
}

5.23 preProcess📝 Edit

Expects an array of JavaScript functions. ReSpec invokes these functions in order before any other processing on the HTML occurs. The function’s signature includes a reference to the config object (i.e., the initial configuration object in the ReSpec source, plus some additional internal data) and the reference to the DOM Document element.

function doThing(config, document){...}
function doOtherThing(config, document){...}

var respecConfig = {
  // Before processing, run the following
  preProcess: [doThing, doOtherThing]
}

5.24 publishDate📝 Edit

A YYYY-MM-DD date. The publication date of the present document. For documents that are in flux, such as Editor's Drafts or unofficial documents, this is best left unspecified as ReSpec will use the document's last modification date (as provided by the browser) in order to set this. For documents intended for official publication, this is normally required.

Note that the last modified date provided by the browser can at times be wrong. This often happens when the server is itself providing a broken value, or at times when differences in time-zones (that are not always well accounted-for by servers or browsers) cause the day to shift by one.

var respecConfig = {
  publishDate: "2021-01-02",
};

5.25 shortName📝 Edit

The specification's "short name", which is the name used in W3C URLs such as "https://www.w3.org/TR/short-name" (and several other generated URLs).

var respecConfig = {
  shortName: "awesome-api",
};

5.26 specStatus📝 Edit

The specification's type, which can be a maturity level (e.g. Working Draft) if it is on a publication track, but can also take other values for other types of documents (e.g. "unofficial" for unofficial documents).

var respecConfig = {
  specStatus: "unofficial",
};

5.27 subjectPrefix📝 Edit

If you wish feedback to your mailing list about this specific document to have a specific prefix subject in its subject line, then specify this (including the [ and ] if you want them). The various of the heading matter that refer to the mailing list will use this information.

var respecConfig = {
  subjectPrefix: "[Foopy-Spec-Feedback]",
};

5.28 subtitle📝 Edit

A simple string that will be used as a subtitle for the specification, right under the title.

var respecConfig = {
  subtitle: "The spec to end all specs.",
};

5.29 testSuiteURI📝 Edit

The URL of your test suite, gets included in the specification's headers.

var respecConfig = {
  testSuiteURI: "https://example.com/test/suite/",
};

Also see: wpt-tests-exist lint rule.

5.30 tocIntroductory📝 Edit

A boolean, which when set to true, will cause the introductory sections to also show up in the table of contents. This is rarely needed, but some groups prefer to have it.

var respecConfig = {
  tocIntroductory: true,
};

5.31 xref📝 Edit

The xref option allows you to configure automatic external reference linking (xref). A detailed explanation on how to use xref in specifications is given here. This page describes the various configurations available.

xref can be configured as:

var respecConfig = {
  // See all config options below!
  xref: "web-platform", 
};

And then simply write the terms you want to link to:

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

And ReSpec will know what to do. If ReSpec can't find a term, it will show an error. If you are unsure if a term is exported, head over to https://respec.org/xref/ to see if it's exported.

If a term is not exported, ask the Editors of that spec to export the term by using data-export="".

var respecConfig = {
  xref: true,
};

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

var respecConfig = {
  xref: ["spec1", "spec2"],
};

var respecConfig = {
  xref: {
    specs: ["spec1", "spec2"],
    profile: "web-platform",
  },
};

6.1 additionalCopyrightHolders📝 Edit

For regular documents, this is used to specify that additional parties hold a copyright jointly with W3C on this document. This is typically used when publishing documents that were developed in cooperation with other friendly standard consortia such as the IETF.

The option is simply some text giving the additional copyright holders. For unofficial documents, this string is used to replace the default CC license.

var respecConfig = {
  additionalCopyrightHolders: "Internet Engineering Task Force",
};

You can preview this feature in live examples:

• Regular document
• Unofficial document

6.2 addPatentNote📝 Edit

Content that gets inserted at the end of the SotD. Used in case the patent situation of your specification requires some specific mentions (e.g. for an ongoing PAG).

var respecConfig = {
  addPatentNote: "Please be aware that Company X has excluded some patents.",
};

6.3 alternateFormats📝 Edit

Shows links to alternate formats (such as PDF, ePub) in the document header.

This option accepts an array of objects, each of which has two required fields:

uri

for the link to the alternate document

label

for a human readable string that matches it. This is used to link to alternate formats for the same content (e.g. PDF, ePub, PS).

var respecConfig = {
  alternateFormats: [
    {
      label: "PDF",
      uri: "https://example.w3.org/TR/example.pdf",
    },
    {
      label: "XML",
      uri: "https://example.w3.org/TR/example.xml",
    },
  ],
};

6.4 canonicalURI📝 Edit

The canonicalURI lets you indicate either a URL or a keyword to use as the canonical link of the document. Search engines, like Google, can make use of this information to help determine which version of document is authoritative.

Following keywords automatically generate a corresponding URL. However, you are free to include your own URL.

var respecConfig = {
  shortName: "fooAPI",
  canonicalURI: "TR",
};

6.5 charterDisclosureURI📝 Edit

This configuration option must be specified for Interest Group Notes (IG-NOTE), where it must point at the disclosure section of the group charter, per publication rules. This option is ignored for all other documents.

var respecConfig = {
  charterDisclosureURI: "https://www.w3.org/2019/06/me-ig-charter.html#patentpolicy",
};

6.6 copyrightStart📝 Edit

ReSpec knows to include a copyright year that matches the publishDate in the copyright notice. However, for documents developed over a period of several years it is preferable to indicate the first year during which the copyright started by setting this option.

Note that this can always be safely specified since if copyrightStart is the same as the publishDate's year it is ignored.

The following appears as "Copyright © 1977-2016".

var respecConfig = {
  copyrightStart: 1977,
  publishDate: "01-01-2016",
};

6.7 crEnd📝 Edit

Documents that are in Candidate Recommendation (CR) are required to indicate a date before which the group guarantees that it will not move to the next step on the track (PR or RE) so that implementers know how long they have.

Use this option to provide that date, in YYYY-MM-DD format.

var respecConfig = {
  specStatus: "CR",
  crEnd: "2014-01-04",
};

6.8 doJsonLd📝 Edit

Adds a JSON-LD script element containing schema.org information, which can be useful for search engines.

The following entry in respecConfig can be used to configure JSON-LD support, which currently defaults to false.

var respecConfig = {
  doJsonLd: true,
};

In addition, you will also need to provide a canonicalUri and a license in your respecConfig for the JSON-LD data to be generated.

When configured, a script element similar to the following will be added:

<script type="application/ld+json">
  {
    "@context": [
      "https://schema.org",
      {
        "@vocab": "https://schema.org/",
        "@language": "en",
        "w3p": "https://www.w3.org/2001/02pd/rec54#",
        "foaf": "http://xmlns.com/foaf/0.1/",
        "datePublished": { "@type": "xsd:date" },
        "inLanguage": { "@language": null },
        "isBasedOn": { "@type": "@id" },
        "license": { "@type": "@id" }
      }
    ],
    "id": "https://w3c.github.io/some-API/",
    "type": ["TechArticle"],
    "name": "Replace me with a real title",
    "inLanguage": "en",
    "license": "https://www.w3.org/Consortium/Legal/2015/copyright-software-and-document",
    "datePublished": "2018-02-22",
    "copyrightHolder": {
      "name": "World Wide Web Consortium",
      "url": "https://www.w3.org/"
    },
    "discussionUrl": "https://github.com/w3c/some-API/issues/",
    "description": "Abstract \n bla bla",
    "editor": [
      {
        "type": "Person",
        "name": "Your Name",
        "url": "https://your-site.com"
      }
    ],
    "citation": [
      {
        "id": "https://berjon.com/",
        "type": "TechArticle",
        "name": "The Dahut Specification Example From the Higher Circle",
        "url": "https://berjon.com/"
      }
    ]
  }
</script>

6.9 errata📝 Edit

An URL to a document capturing errata for the specification. Generally, this only applies to documents with a "REC" and "PER" specStatus.

var respecConfig = {
  status: "REC",
  errata: "https://www.w3.org/XML/xml-V10-5e-errata",
};

6.10 group📝 Edit

For W3C, it allows you to associate a specification with a particular working group. Supported group short-names can be found at: https://respec.org/w3c/groups/.

Specifying the group will also figure out all the patent policy related things for your particular specification.

var respecConfig = {
  group: "payments",
};

You can also specify multiple groups:

var respecConfig = {
  group: ["group1", "group2"],
};

If a Community Group (CG) and a Working Group (WG) are using the same shortname, e.g. "wot", you can specify the group type as:

var respecConfig = {
  group: "wg/wot",
};

6.11 implementationReportURI📝 Edit

The URL of the implementation report (documenting how your test suite fares with implementations). It gets included in the specification's headers.

var respecConfig = {
  implementationReportURI: "https://example.com/imp-report/",
};

6.12 lcEnd📝 Edit

A date in the format YYYY-MM-DD. Documents that are in Last Call (specStatus is "LC") are required to indicate an end date for the review period.

var respecConfig = {
  specStatus: "LC",
  lcEnd: "2016-01-03",
};

6.13 level📝 Edit

"Leveled" specs are generally specs that build on each other in a backwards compatible way. They generally include the text from each previous level. This is used a lot by the W3C's CSS Working Group.

The level configuration options automatically appends the level to your spec’s title and shortName. The level is an integer value greater than or equal to 0.

var respecConfig = {
  level: 2,
  shortName: "payment-request",
};

Which results in:

• Level 2 is appended to the title, so Payment Request Level 2.
• The short-name becomes payment-request-2.

Which would render as, for example:

6.14 noRecTrack📝 Edit

A boolean indicating that a document is not intended to become a W3C Recommendation. Used for Notes while in unfinished maturity states.

var respecConfig = {
  noRecTrack: true,
};

6.15 prevED📝 Edit

Sometimes it happens that a document is moved in the version control system, passed from one group to another, or split into several smaller documents. In such cases since the version control information is harder to find, this option can be used to point to a previous Editor's Draft. Rarely used.

var respecConfig = {
  prevED: "https://example.com/old/ed",
};

6.16 previousDiffURI📝 Edit

When producing a diff-marked version, ReSpec uses the previousURI as the old version by default. Use this configuration option if you wish to override this to a specific URL.

var respecConfig = {
  previousURI: "https://www.w3.org/TR/2014/WD-FOO-20140327/",
  // Diff against the first version instead
  previousDiffURI: "https://www.w3.org/TR/2014/WD-FOO-20130101/",
};

6.17 previousMaturity📝 Edit

A YYYY-MM-DD date. When a previousPublishDate is specified, this is typically required as well in order to generate the "Previous Version" link since it includes an indication of the previous document's maturity level, which cannot be guessed. The values are the same as for specStatus.

Please note that some values of this option make no sense depending on the current document specStatus but that the rules for validating consistency are convoluted enough that ReSpec does not try to check them. If you pick the wrong value (typically by forgetting to change it), the Link Checker will most likely catch the error before publication (the same goes for previousPublishDate).

var respecConfig = {
  previousPublishDate: "2014-05-01",
  previousMaturity: "LC",
};

6.18 previousPublishDate📝 Edit

A YYYY-MM-DD date. When there is a previous release of a given specification, this is used to generate the "Previous Version" link. It is required for Recommendation Track documents.

var respecConfig = {
  previousPublishDate: "2014-05-01",
  previousMaturity: "LC",
};

6.19 prevRecShortname📝 Edit

If you are working on a new version of an existing Recommendation, use this to indicate what its shortName was.

var respecConfig = {
  shortName: "fancy-feature-l2",
  prevRecShortname: "fancy-feature",
};

6.20 prevRecURI📝 Edit

If you are working on a new version of an existing Recommendation, use this to indicate what its URL was.

If a prevRecURI is not specified but prevRecShortname is, the latter will be used to generate the former by prefixing "https://www.w3.org/TR/" to it. Note however that while in the overwhelming majority of cases this works, it is not recommended to use this approach since if the Recommendation is later Rescinded, the link will be stale. Instead, use the dated link to the Recommendation.

var respecConfig = {
  prevRecURI: "https://www.w3.org/TR/2014/example-20140327/",
};

6.21 submissionCommentNumber📝 Edit

Allows W3C staff to link to a comment number.

var respecConfig = {
  specStatus: "Member-SUBM",
  submissionCommentNumber: "03",
};

Which shows up as:

<a href="https://www.w3.org/Submission/2018/03/Comment/">
  W3C Team Comment
</a>

6.22 wgPatentPolicy📝 Edit

The wgPatentPolicy is a string indicates patent policy the group operates under.

Possible values are:

• "PP2020"
• "PP2017"

var respecConfig = {
<div class="note">

  // Note: the "group" option sets this automatically for you! </div>
  wgPatentPolicy: "PP2020",
}

6.23 wgPublicList📝 Edit

The short name of the mailing list on which the group conducts its public discussion.

var respecConfig = {
  wgPublicList: "public-device-apis",
};

7.1 conformance📝 Edit

When present, a section with id conformance tells ReSpec to add the standard boilerplate to the document:

The author can add any additional conformance clause(s) which will follow this boilerplate.

This section is required for specifications that contain normative material.

<section id="conformance">
  <!-- boilerplate will be added here -->
  <p>The specification specific conformance text…</p>
</section>

7.2 gh-contributors📝 Edit

Add an element with id="gh-contributors" to show a list of people who have contributed to the GitHub repository.

The list is sorted by names (or GitHub username).

<section>
  <h2>Contributors</h2>
  <ul id="gh-contributors">
    <!-- list of contributors will appear here,
         along with link to their GitHub profiles -->
  </ul>
</section>

<p>
  We'd also like to thank the following contributors: <span id=
  "gh-contributors"><!-- filled by ReSpec --></span>.
</p>

7.3 idl-index📝 Edit

Giving a <section id=idl-index> instructs ReSpec to gather all the Web IDL in your specification into a single section. This is convenient in that it gives readers a nice view of the overall shape of your API.

If you don't have any IDL in your spec, then it's probably best not to include this. ReSpec will still produce the section with a heading, but will inform the reader that you don't actually have any Web IDL in your spec.

<section id="idl-index" class="appendix">
  <!-- All the Web IDL will magically appear here -->
</section>

You can also add a custom header and content to your idl-index:

<section id="idl-index" class="appendix">
  <h2>The Whole API!</h2>
  <p>This is what the whole thing looks like!</p>
  <!-- All the Web IDL will magically appear here -->
</section>

7.4 index📝 Edit

Adding a <section id="index"> in your document instructs ReSpec to gather all the terms defined in your specification, as well as all the terms referenced by your specification into a single section. The index lets you conveniently search for all defined/referenced terms, as well as find their usage in the document.

<section id="index" class="appendix">
  <!-- All the terms will magically appear here -->
</section>

You can also add a custom header and content to your index:

<section id="idl-index" class="appendix">
  <h2>List All The Terms!</h2>
  <p>Wow, that's a lot of terms!</p>
  <!-- All the terms will magically appear here -->
</section>

7.5 issue-summary📝 Edit

When present, the issue-summary id tells ReSpec to gather all issues found throughout your spec and display them.

<div class="issue" data-number="123" title="This is issue!">
  <p>It clear that this is an issue.</p>
</div>
<section class="appendix" id="issue-summary">
  <!-- A list of issues will magically appear here -->
</section>

7.6 references📝 Edit

You can add an explicit <section id="reference"> in cases where you need to add custom content to the references section of a document.

<section id="references">
  <p>Citations are great!</p>
  <!-- normative and informative references will appear below -->
</section>

7.7 tof📝 Edit

Automatically generate a Table of Figures by adding a <section id="tof">.

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

<section id="tof">
  <!-- a table of figures will be added here -->
</section>

8.1 <figure>📝 Edit

Specification figures are indicated using the <figure> element, with a nested <figcaption>. They can occur anywhere.

<section id="buckets">
  <figure id="flowchart">
    <img src="flowchart.svg" alt="" />
    <figcaption>The water flows from bucket A to bucket B.</figcaption>
  </figure>
  <p>The flowchart shown in <a href="#flowchart"></a> is quite impressive.</p>
</section>

Figures can be automatically linked to using a link pointing to their ID with no content (e.g. <a href='#foo-figures'></a>).

You can also automatically generate a table of figures.

8.2 <h1 id="title">📝 Edit

The recommended way to set the title of a specification is via a <title> element. However, in cases where you might need markup in a spec's title (e.g., for i18n reasons), you can use a single <h1 id="title"> element.

ReSpec warns if the <title> and the <h1> text content do not match.

<body>
  <h1 id="title">The <code>Whatever</code> Interface</h1>
  <section id="abstract">
    <p>...</p>
  </section>
</body>

8.3 <pre>/<code>📝 Edit

ReSpec provides code highlighting for blocks of code marked up with the <pre> or <code> elements. ReSpec will try to guess the code language, or it can be added as a class:

<pre> <!-- or <pre class="html"> -->
<script>
function magic() {
  const noop = "this";
  doThat(noop);
}
</script>
</pre>

Respec supports the following languages by default:

• ABNF
• CSS
• HTML
• HTTP
• JavaScript
• JSON
• XML

To highlight code in other languages you need to define a function that loads a highlighter.js package for the language you want, and to request the language be loaded as a respec preProcess option:

async function loadSolidity() {
  //this is the function you call in 'preProcess', to load the highlighter
  const worker = await new Promise(resolve => {
    require(["core/worker"], ({ worker }) => resolve(worker));
  });
  const action = "highlight-load-lang";
  const langURL =
    "https://rawgit.com/pospi/highlightjs-solidity/master/solidity.js";
  const propName = "hljsDefineSolidity"; // This funtion is defined in the highlighter being loaded
  const lang = "solidity"; // this is the class you use to identify the language
  worker.postMessage({ action, langURL, propName, lang });
  return new Promise(resolve => {
    worker.addEventListener("message", function listener({ data }) {
      const { action: responseAction, lang: responseLang } = data;
      if (responseAction === action && responseLang === lang) {
        worker.removeEventListener("message", listener);
        resolve();
      }
    });
  });
}

var respecConfig = {
  // i.e. add this line to your existing configuration
  preProcess: [loadSolidity],
  // ... other configuration information
};

8.4 <section>📝 Edit

Specification sections are indicated using the <section> element. They can be nested arbitrarily in order to indicate sub-sections.

The first h* child element is taken to be the section's title. You do not need to worry about nesting depth: ReSpec will take any element in the h1-h6 range and renumber it to match the section's nesting depth correctly. It is a common convention (though by no means a requirement) to use h2 for all sections.

If you nest deeper than the h6 level, apart from having a hard-to-navigate document you will keep getting h6 elements.

Section can be automatically linked to using a link pointing to their ID with no content (e.g. <a href='#foo-section'></a>).

<section>
  <h2>The <code>foo</code> Element</h2>
  <p>The <code>foo</code> Element allows you too...</p>
</section>

8.5 <title>📝 Edit

ReSpec uses the <title> element to generate the title of your specification. The <title> element is left untouched, but its content is used to create a <h1> title for the specification.

<!DOCTYPE html>
<html>
  <title>The Super Duper Spec</title>
  <body>
    <!-- The title will magically be placed here with other useful stuff -->
    <section id="abstract"></section>
  </body>
</html>

9.1 appendix📝 Edit

Marks a section as being an appendix (which will be numbered with letters). Note that this does not make it informative as some appendices can contain normative material.

It is important to know that every section following an appendix will also be made to be an appendix.

<section class="appendix">
  <h2>Acknowledgements<h2>
  <p>This spec would not be possible without...</p>
</section>

9.2 ednote📝 Edit

Marks the contents of an element as an "Editor's Note". If the element is a 'block' element (e.g., div or p) then the Editor's Note will be emitted in a block that includes an Editor's Note "header" and the contents of the element as the text of the note. If the element also has a title attribute, the content of the title will be appended to the header (e.g., "Editor's Note: This is my note").

Note that the content of the title attribute will be interpreted as HTML markup. See title attributes for details.

<p class="ednote" title="This section will be reformatted">
  We are aware that the formatting of this section isn't great. We will fix it
  in the next revision!
</p>

Would be emitted as:

<div class="ednote">
  <div class="ednote-title">
    <span>Editor's Note: This section will be reformatted</span>
  </div>
  <p>
    We are aware that the formatting of this section isn't great. We will fix it
    in the next revision!
  </p>
</div>

9.3 example📝 Edit

Marks a pre, or aside as being an example. This wraps the element in a header with an example number. Use the title attribute to add text alongside the example number. Aside elements may contain nested pres.

For a contra-example, replace the example class with illegal-example.

Note that the content of the title attribute will be interpreted as HTML markup. See title attributes for details.

<aside class="example" title="Fat arrows (<code>=></code>)">
  <p>Here we see how to use a fat arrow in ES.</p>
  <pre>
  const sum = [...items]
    .map(item => item * 2)
    .reduce((sum, next) => sum + (next || 0) );
  </pre>
</aside>

9.4 informative📝 Edit

Used for regular sections or appendices that are not meant to contain normative material. It will automatically preface its content with the well-known “This section is non-normative” paragraph.

<section class="informative">
  <h2>A bit of history!</h2>
  <p>A really cool thing is that ...</p>
</section>

9.5 introductory📝 Edit

When set on a section, introductory indicates that it is meant as introductory material that need not be linked to from the table of contents. The abstract, SotD, and ToC sections automatically fall into this category (but you need not worry about flagging them as such).

If you do wish all the introductory sections to be present in the ToC, see tocIntroductory.

<section class="introductory">
  <p>This document can be folded into a paper airplane.</p>
</section>

9.6 issue📝 Edit

Provided you've added the github configuration option, you can easily reference GitHub issues in your spec as:

<div class="issue" data-number="363"></div>

ReSpec will automatically download the issue details and include them for you.

Additionally, you can gather all referenced issues in a list with issue-summary.

9.7 no-link-warnings📝 Edit

Setting "no-link-warnings" class on a <pre> element stops ReSpec from warning you if you have missing links.

In the following example, the semantics of the attributes is the same in both the dictionary and the interface. As such, it might not make sense to provide formal definitions for the dictionary items.

<pre class="idl no-link-warnings">
dictionary PointerEventInit: MouseEventInit {
  long pointerId = 0;
  double width = 1;
};

interface PointerEvent: MouseEvent {
  constructor(DOMString type, optional PointerEventInit eventInitDict);
  readonly attribute long pointerId;
  readonly attribute double width;
};
</pre>

9.8 nohighlight📝 Edit

Indicates that a code block should not be syntax highlighted.

This block will not be syntax highlighted:

<pre class="nohighlight">
function foo(){
  const a = "foo!";
}
</pre>

But this one will be syntax-highlighted by default:

<pre>
function foo(){
  const a = "foo!";
}
</pre>

9.9 nolink📝 Edit

When using markdown, nolinks disables automatic linking within code blocks.

<pre code="nolink">
Prevents the following from becoming a hyperlink: https://example.com
</pre>

9.10 note📝 Edit

Marks the contents of an element as a "Note". If the element is a 'block' element (e.g., div or p) then the Note will be generate in a block that includes a Note "header" and the contents of the element as the text of the note. If the element also has a title attribute, the content of the title will be appended to the header (e.g., "Note: This is my note").

Note that the content of the title attribute will be interpreted as HTML markup. See title attributes for details.

<p class="note" title="Always rely upon native semantics">
  Remember - if you are using the <code>role</code> attribute to say that a
  paragraph is a button, you are probably doing it wrong!
</p>

Would be exported as:

<div class="note">
  <div class="note-title">
    <span>Note: Always rely upon native semantics</span>
  </div>
  <p>
    Remember - if you are using the <code>role</code> attribute to say that a
    paragraph is a button, you are probably doing it wrong!
  </p>
</div>

9.11 notoc📝 Edit

When this class is specified on a section element, that section will be omitted from the Table of Contents.

<section class="notoc" id="mySection">
  <h1>Some section I do not want in the ToC</h1>
  ...
</section>

Also see: noTOC configuration option.

9.12 override📝 Edit

The override css class allow spec editors to completely override a section that would normally be dynamically filled with ReSpec generated content.

Sections you can override include:

• <section id="sotd">
• <section id="conformance">

<section id="sotd" class="override">
  <h2>Status of this document</h2>
  <p>Exploring new ideas...</p>
</section>

9.13 practice📝 Edit

A <div> containing a best practice description.

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

9.14 practicedesc📝 Edit

A paragraph containing the description of a best practice, inside a practice <div>.

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

9.15 practicelab📝 Edit

A <span> containing the title of a best practice, inside a <p class=practicedesc>.

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

9.16 remove📝 Edit

If you want to include content that is used during the generation of the specification but must be removed from the output, then add the remove class to it. That is used for instance for all the script elements that pull in ReSpec and define its configuration.

<div class="remove">
  <p>This will be removed at build time.</p>
</div>

9.17 removeOnSave📝 Edit

If you want to include content that is used during the generation of the specification but must be removed from the exported output, then add the removeOnSave class to it.

<div class="removeOnSave">
  <p>This will be removed at export time.</p>
</div>

10.1 data-abbr📝 Edit

The data-abbr can be used on dfn elements that are used as abbreviations throughout your spec.

You can either set the abbreviation explicitly, or ReSpec can figure it out for you.

You can also set the abbreviation by yourself.

10.2 data-cite📝 Edit

Using data-cite, allows you to cite a spec directly in text by using a spec's id. You can look up an id either directly in ReSpec (using the ReSpec pill > "Search SpecRef DB") - or on specref.org.

Add "!" on the front of the spec ID makes it a "normative" citation. Excluding it, makes it informative.

It is currently supported on <a> and <dfn> elements:

The syntax for data-cite value is:

spec-id[optional "/" path-to-document]#fragment

<a data-cite="rfc2119#some-section">some text</a>
<dfn data-cite="spec/some.html#fragment">some text</a>

10.3 data-dfn-for📝 Edit

The data-dfn-for attribute links a WebIDL attribute or method to a definition.

The following example automatically links up the bar attribute and the doTheFoo() method to the Foo interface.

<section data-dfn-for="Foo" data-link-for="Foo">
  <h2><code>Foo</code> interface</h2>
  <pre class="idl">
  interface Foo {
    attribute Bar bar;
    void doTheFoo();
  };
  </pre>
  <p>The <dfn>Foo</dfn> interface is nice. Lets you do stuff.</p>
  <p>The <dfn>bar</dfn> attribute, returns 🍺.</p>
  <p>The <dfn>doTheFoo()</dfn> method, returns nothing.</p>
</section>

10.4 data-dfn-type📝 Edit

You can add a data-dfn-type attribute on <dfn> elements to declare the type of definition. This is used in conjunction with data-link-type to allow linking to a definition of particular type.

In many cases, you do not need to provide this value. If a <dfn> has a data-dfn-for context, data-dfn-type is treated as "idl". Otherwise, it is to be "dfn".

Currently, only two values: "idl" and "dfn" are supported. In future, more values might be supported.

<p>
  The document has visibility state of
  <dfn id="dfn-hidden" data-dfn-type="dfn">hidden</dfn>.
</p>
<p>
  `visibilityState` attribute has value
  <dfn id="idl-hidden" data-dfn-type="idl">hidden</dfn>.
</p>

<p>
  {{ hidden }} links to dfn with id="idl-hidden". This is same
  <a data-link-type="idl">hidden</a>, but above syntax is preferred.
</p>
<p>
  [= hidden =] links to dfn with id="dfn-hidden". This is same
  <a data-link-type="dfn">hidden</a>, but above syntax is preferred.
</p>

10.5 data-export📝 Edit

Use the data-export to export a <dfn> definition to W3C's Shepherd database.

If you'd like to have your specification indexed in Shepherd, please email marcos@marcosc.com.

<p>The <dfn data-export="">fancy thing</dfn> can be used by other specs.</p>

Then other specs can use "fancy thing" using xref, like so:

<script>
  var respecConfig = {
    xref: ["spec-shortname"],
  };
</script>

<p>We can now link to <a>fancy thing</a> in another spec.</p>

10.6 data-format📝 Edit

The data-format attribute allows sections, or other block-level elements, of your spec to be treated as markdown. It takes only one value: "markdown". Other formats may be supported in the future.

The following would generate a H2 element (which ReSpec would automatically number).

<section data-format="markdown">

## This is level 2

This is a paragraph with some `code`.

</section>

10.7 data-include📝 Edit

A URL pointing to a resource, relative to the including document. The content will get included as a child of the element on which the inclusion is performed (unless data-include-replace is used, in which case it replaces the element), replacing its existing content.

The include filter does not run recursively - data-include attributes on included content will not work.

In the processing pipeline, inclusion happens right after everything to do with the document's headers, style, and transformations have happened, which means that all the processing to do with structure, inlines, WebIDL, and everything else is applied to the included content as if it had always been part of the source.

<section data-include="section/theFooElement.html"></section>

10.8 data-include-format📝 Edit

Data is normally included as HTML (injected into the DOM as such). There are times when you want to include content as text. If so, set this attribute to "text".

If you want to include as markdown, use "markdown" as attribute value. The default value is "html".

<section
  data-include="some.txt"
  data-include-format="text">
</section>

10.9 data-include-replace📝 Edit

By default inclusion happens by placing the content inside the including element. At times, you will actually want the element to be replaced by the inclusion. If so, simply set this attribute to any truthy value.

Pretending that "section.frag" is a <section> element, the <div> below would be replaced with a <section>.

<div data-include="section.frag" data-include-replace="true">
  <!-- this all gets replaced, including the div. -->
</div>

10.10 data-link-for📝 Edit

The data-link-for attribute allows you to link to a definition with same data-dfn-for value.

<p>
  <dfn>bar</dfn> is a global definition.
  <a>bar</a> links to bar.
  Prefer using [= bar =] syntax for linking.
</p>

<p>
  <dfn data-dfn-for="Foo">bar</dfn> is defined in scope of "Foo".
  <a data-link-for="Foo" data-link-type="dfn">bar</a> links to `bar` in scope of `Foo`.
  Following syntax is preferred: [= Foo/bar =]
</p>

It works with IDL definitions also:

<p>
  <dfn data-dfn-type="idl" data-dfn-for="Foo">bar</dfn> is defined in scope of "Foo".
  <a data-link-for="Foo" data-link-type="idl">bar</a> links to `bar` in scope of `Foo`.
  Following syntax is preferred: {{ Foo/bar }}
</p>

The data-link-for attribute also allows you to link to one or more aspects of an interface at once.

In this example, we link to Request's definition of url, but not Response's.

<pre class="idl">
  interface Request {
    readonly attribute USVString url;
  };
  interface Response {
    readonly attribute USVString url;
  };
</pre>
<p data-dfn-for="Request">
  The <dfn data-lt="clone()">clone</dfn> method.
  The <dfn>url</dfn> attribute.
</p>
<!-- Linking to definitions works the same -->
<p data-link-for="Request">
  Links to <a>clone()</a> method.
  Links to the <a>url</a> attribute.
</p>

10.11 data-link-type📝 Edit

The data-link-type attribute allows following values:

• "dfn", "idl": See data-dfn-type
• "biblio": Automatically added on bibliographic references through [[spec]] syntax.

10.12 data-local-lt📝 Edit

In general, you can provide alternative "linking text" ("lt"s) to a defined term by using the data-lt.

However, in the rare situation where you need to export via data-export a definition, you might want some shorthands to not be exported. In such a case, you can use data-local-lt.

In the following example, the following terms are exported for use with the xref linking system:

• installed web application
• installed

While, the following terms are not exported, but can be linked to internally:

• installing
• installation

<dfn
  data-export=""
  data-local-lt="installation|installing"
  data-lt="installed web application"
>installed</dfn>

<!-- These all link as expected -->
<a>installed web application</a>
[=installed=]
<a>installing</a>
[=installation=]

10.13 data-lt📝 Edit

data-lt allows you to define alternative terms for a definition (or link to a definition using an alternative name). This is great for some other variant that does not exactly match the dfn. Each term is separated by a |.

<dfn data-lt="best fruit|fruits of the gods">Apple</dfn>...

<!-- can be referenced by any of: -->
<a>best fruit</a>
<a>fruits of the gods</a>
[=fruits of the gods=]

See also: Automatic pluralization with pluralize and data-local-lt.

10.14 data-lt-no-plural📝 Edit

If you want to selectively disable pluralization on certain <dfn>, you can make use of data-lt-no-plural attribute like:

<dfn data-lt-no-plural>html</dfn>

10.15 data-lt-noDefault📝 Edit

Allow you to ignore data-lt-noDefault definition of a defined term. This is sometimes useful if you need to disambiguate two terms.

<dfn>The Foo</dfn>
<!-- the text content definition is not used -->
<dfn data-lt="other foo" data-lt-noDefault>The Foo</dfn>

10.16 data-max-toc📝 Edit

Limit depth of table to contents section to section, without adding a global depth limit using maxTocLevel.

<section data-max-toc="2">
  <h2>Section 1</h2>
  <section>
    <h2>Section 1.1</h2>
    <section>
      <h2>Section 1.1.1 (skipped)</h2>
    </section>
  </section>
</section>

data-max-toc=0 is equivalent to adding a notoc class to current section:

<section data-max-toc="0">
  <h2>I'm skipped from ToC</h2>
</section>

10.17 data-number📝 Edit

Can be used in conjunction with the configuration option github and with a paragraph with a class set to issue. The issue number is added to the header of the paragraph, and linked to the issue by concatenating the values of issueBase and data-number. This is particularly useful when using GitHub to link into the discussion thread of a particular issue.

A typical example for a file in the Github repository https:/github.com/w3c/dpub-pwd would include, for example:

<script>
  var respecConfig = {
    github: "w3c/dpub-pwd",
  };
</script>

<p class="issue" data-number="1">
  Will be automatically titled "ISSUE 1", with a link to the corresponding
  Github issue.
</p>

10.18 data-oninclude📝 Edit

This is a list of white space separated JavaScript function names that will be called in turn in order to transform the content inside the given element. The functions need to be globally available.

Each function gets called with three arguments:

• ReSpec utils object.
• a string of the content to transform.
• the URL of the loaded content.

Each function must return the transformed content.

<script>
  // Adds rainbows where appropriate.
  function toRainbows(utils, content, url) {
    return content.replace(/rainbow/gi, "🌈");
  }

  // Replaces unicorns rainbows where appropriate.
  function replaceUnicorns(utils, content, url) {
    return content.replace("🦄", "🐴");
  }
</script>

<!-- Include content.fragment file, but then process it on include. -->
<section
  data-oninclude="toRainbows replaceUnicorns"
  data-include="content.fragment"
></section>

10.19 data-sort📝 Edit

By using data-sort="ascending" or "descending", ReSpec can shallow sort lists of type ol, ul, and dl elements. Shallow sort meaning that only the first level of the list is sorted, and any nested lists are left alone. This is nice for Dependency sections, IDL member definitions, etc.

You can also just write data-sort and exclude the attribute value, and it will default to "ascending" (i.e., from A-to-Z).

<ul data-sort="descending">
  <li>W</li>
  <li>Z</li>
  <li>A</li>
</ul>

<ul>
  <li>Z</li>
  <li>W</li>
  <li>A</li>
</ul>

<dl data-sort>
  <dt>Bananas</dt>
  <dd>Are the best!</dd>

  <dt>Zebra</dt>
  <dd>Are quite stripy.</dd>

  <dt>Apples</dt>
  <dd>🍎s are delicious.</dd>
  <dd>🍏s are great in a pie!.</dd>
</dl>

<dl>
  <dt>Apples</dt>
  <dd>🍎s are delicious.</dd>
  <dd>🍏s are great in a pie!.</dd>

  <dt>Bananas</dt>
  <dd>Are the best!</dd>

  <dt>Zebra</dt>
  <dd>Are quite stripy.</dd>
</dl>

10.20 data-tests📝 Edit

The data-tests attribute takes a list of comma-separated URLs, allowing you to link tests to testable assertions. This will add a details drop down to the testable assertion, with an unordered list of tests.

The data-test works together with the testSuiteURI config option, so it must be present or ReSpec will yell at you.

It's best used with <p> and <li> elements.

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

<p data-tests="test-1.html, test-2.html">
  The user agent MUST do this stuff...
</p>

10.21 dir📝 Edit

ReSpec defaults the dir attribute of the HTML element to ltr. If you are writing in a language that requires a different directionality, simply set this attribute to another value.

<html dir="rtl"></html>

10.22 lang📝 Edit

ReSpec defaults the lang attribute on <html> element to "en" (English). If you are writing in another language, simply set this attribute to another value.

<!DOCTYPE html>
<html lang="fr"></html>

11.1 <rs-changelog>📝 Edit

The <rs-changelog> custom element to show a list of commits between two commits/tags. This list of commits is shown from newest to oldest. Each commit message is linked to the commit.

function respecChangelogFilter(commit) {
  // commit.hash = commit hash
  // commit.message = commit message headline
  // Return `true` if commit is to be shown, false otherwise.
  return !commit.message.startsWith("chore");
}

<p>Commits since "CR":</p>
<rs-changelog from="CR"></rs-changelog>

<p>All commits between "CR" tag and a commit "5b1a9da":</p>
<rs-changelog from="CR" to="5b1a9da"></rs-changelog>

<p>
  Show commits since "CR", but filter the commits to be shown using a function
  called `respecChangelogFilter` which is defined globally:
</p>
<rs-changelog from="CR" filter="respecChangelogFilter"></rs-changelog>

12.1 processVersion📝 Edit

ReSpec knows to include an indication of the W3C process under which the document was developed. This indication appears at the end of the Status of This Document section. By default it indicates the new 2018 process. You can override this by setting the processVersion configuration option to anything other than 2018. The previous process documents were 2015, 2014, and 2005.

var respecConfig = {
  // Generally, you want ReSpec to set this for you
  // unless there is a good reason to use an old
  // process!
  processVersion: 2015,
};

12.2 wg📝 Edit

The full public name of the group, including "Working/Interest/Incubator/etc. Group" as applicable.

12.3 wgId📝 Edit

The numeric W3C Working Group identifier. This is used when publishing NOTEs to create the data-deliverer attribute in the Status of this Document section.

var respecConfig = {
  wgId: 107714,
};

12.4 wgPatentURI📝 Edit

The URL of the public list of patent disclosures for the group.

12.5 wgURI📝 Edit

The URL to the public page of the working group that is working on the spec.