ReSpec Documentation

Abstract

ReSpec makes it easier to write technical documents. It was originally designed for writing W3C specifications, but now supports many output formats.

1. Getting Started 📝 Edit

A ReSpec document is a HTML document that brings in the ReSpec script, defines a few configuration variables, and follows a few conventions. A very small example document would be:

Example 1: A basic ReSpec document.

<!DOCTYPE html>
<html>
  <head>
    <meta charset="utf-8" />
    <title>Replace me with a real title</title>
    <script
      src="https://www.w3.org/Tools/respec/respec-w3c"
      class="remove"
      defer
    ></script>
    <script class="remove">
      // All config options at https://respec.org/docs/
      var respecConfig = {
        specStatus: "ED",
        editors: [{ name: "Your Name", url: "https://your-site.com" }],
        github: "some-org/mySpec",
        shortName: "dahut",
        xref: "web-platform",
        group: "my-working-group",
      };
    </script>
  </head>
  <body>
    <section id="abstract">
      <p>This is required.</p>
    </section>
    <section id="sotd">
      <p>This is required.</p>
    </section>
    <section class="informative">
      <h2>Introduction</h2>
      <p>Some informative introductory text.</p>
      <aside class="note" title="A useful note">
        <p>I'm a note!</p>
      </aside>
    </section>
    <section>
      <h2>A section</h2>
      <aside class="example">
        <p>This is an example.</p>
        <pre class="js">
        // Automatic syntax highlighting
        function someJavaScript(){}
        </pre>
      </aside>
      <section>
        <h3>I'm a sub-section</h3>
        <p class="issue" data-number="121">
          <!-- Issue can automatically be populated from GitHub -->
        </p>
      </section>
    </section>
    <section data-dfn-for="Foo">
      <h2>Start your spec!</h2>
      <pre class="idl">
        [Exposed=Window]
        interface Foo {
        attribute DOMString bar;
        undefined doTheFoo();
        };
      </pre>
      <p>The <dfn>Foo</dfn> interface represents a {{Foo}}.</p>
      <p>
        The <dfn>doTheFoo()</dfn> method does the foo. Call it by running
        {{Foo/doTheFoo()}}.
      </p>
      <ol class="algorithm">
        <li>A |variable:DOMString| can be declared like this.</li>
      </ol>
    </section>
    <section id="conformance">
      <p>
        This is required for specifications that contain normative material.
      </p>
    </section>
  </body>
</html>

1.1 Including ReSpec in HTML documents 📝 Edit

The following code is used to include a ReSpec document, usually in the <head>:

Example 2: Including ReSpec into a HTML 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 Configuring ReSpec 📝 Edit

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

Example 3: The respecConfig global configuration object.

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

All the configurations options are listed in this document.

1.3 Structure 📝 Edit

ReSpec documents are just HTML document and rely on HTML structural elements, in particular <section>, <aside>, <h2>-<h6>, <dl>, <ol> etc. In this section, we discuss how to specify various aspects of a typical document.

1.3.1 Title 📝 Edit

The <title> of the document is reused as the title of the specification in the resulting document's h1. That way, they are always in sync and you need not worry about specifying it twice.

Example 4: Setting a title

<title>The Best Specification</title>

If you need to add additional markup to your title, you can still use a <h1> with id="title".

Example 5: Specification title with custom markup.

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

1.3.2 Subtitle 📝 Edit

As with the title, you can also specify a subtitle as:

Example 6: Specification subtitle with custom markup.

<h1 id="title">The <code>Foo</code> API</h1>
<h2 id="subtitle">Subtitle here</h2>

Which is rendered as:

Screenshot of subtitle

You can also specify a subtitle configuration option in the ReSpec config, but using the markup above is preferred.

1.3.3 Editors & Authors 📝 Edit

Every specification will likely have editors (at least one) and/or authors. It is left to users or standards organizations to differentiate between editors and authors (e.g., from W3C, what does an editor do?).

See the Person objects for the full list of properties you can assign.

Example 7: 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.4 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 8: Sections and sub-sections.

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

Which is rendered as:

Screenshot of a section and a sub-section=

As shown, sections are automatically numbered and uniquely id's for you. Use <section id="my-id"> specify your own id.

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

Note

Note: To you can use the special syntax [[[!#some-id]]] to link to a section.

1.3.5 Table of Contents 📝 Edit

In W3C specs, a table of contents (ToC) is generated automatically and placed after the "Status of This Document".

See also the maxTocLevel option to limit how deep the ToC is.

Set the configuration option noTOC to true to remove the table of content.

1.3.6 Figures & table of figure 📝 Edit

To include a figure, use the <figure> and <figcaption> elements. They automatically get an id and figure number.

Example 9: Figure and list of figures.

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

Which renders as:

Screenshot of a figure and figure caption

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

To add a "List of Figures", 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 10: Generating a list of figures

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

Renders as:

1.3.7 Examples 📝 Edit

Any <pre class="example"> or <aside class="example"> gets the additional example header and style. Content inside pre elements is syntax highlighted. You can specify the language in the class attribute, for example <pre class="js">.

Example 11: Creating an example

<aside class="example" title="How to use it">
  <p>
    This is how to use it.
  <p>
  <pre class="js">
    function myCoolFunction() {
      // stuff goes here...
    }
  </pre>
</aside>

which is rendered as:

Supported highlighters:

abnf
css
http
js or javascript
json
xml

You can disable syntax highlighting on a pre element by adding a "nohighlight" class.

1.3.8 External Includes 📝 Edit

Including external content into ReSpec is done using the data-include attribute, which points to a URL.

Example 12: Including external content

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

You can specify data-include-format='text' to include content as text, and therefore only process it as much as text is expected to be. The only recognized value are "text", "markdown", and "html" (default).

Note

Note: data-include relies on the browser's ability to retrieve the resource and is governed by CORS (and the browser's security model in general). Browsers will generally block cross origin request, which means file:// URLs will likely fail. For more information, please see "Cross-Origin Resource Sharing (CORS)". You can usually get around this by starting a local web server (e.g., by running python -m http.server 8000 from the command line).

Use data-oninclude to perform transformation on content included with data-include.

1.3.9 Conformance section 📝 Edit

ReSpec specifications are RFC2119/RFC8174 keyword aware.

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 13: Using RFC2119 keywords

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

Renders as:

1.3.10 Abbreviations 📝 Edit

Mark abbreviations using <abbr title="abbreviation">abbr</abbr>. ReSpec will then wrap all matching instances abbreviations with <abbr>.

<p>
 The <abbr title="World Wide Web">WWW</abbr>.
</p>
<p>
 ReSpec will automatically wrap this WWW in an abbr.
</p>

1.3.11 Inline Code 📝 Edit

To mark some text as code, use <code> or backticks (`).

1.3.12 Definitions and linking 📝 Edit

To define a term, simple wrap it in a <dfn> element.

<dfn>some concept</dfn>

Then, to link to it, just do:

<a>some concept</a>

or 

[=some concept=]

1.3.13 Automatic pluralization 📝 Edit

For simple/single nouns, ReSpec handles pluralization automatically:

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

1.3.14 Aliases and synonyms 📝 Edit

Sometimes a defined terms needs additional related terms or synonyms. In those cases, you can use the data-lt attribute on the dfn element:

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

Note

Note: "lt" stands for "linked term".

The following all link back to "banana":

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

Referencing terms from other specifications 📝 Edit

The powerful (xref) feature let's you reference terms and concepts in other specifications. For example, to reference "default toJSON steps" from the WebIDL standard:

Example 14: Referencing definitions from other specifications.

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

To search for terms + specs your can link to, you can use the XREF UI at http://respec.org/xref/. Below is a screenshot of what the UI looks like:

Linking shorthands 📝 Edit

There are two important shorthands for linking to definitions:

[=term=] for linking regular concepts,
{{IdlThing}} for linking WebIDL.

Shorthand syntax works for referencing external terms as well as locally defined terms. It's best practice is to use shorthands all the time.

Example 15: Linking using shorthands.

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

Read more about linking and other shorthands in the Shorthands Guide.

1.3.15 References 📝 Edit

To reference another specification use the [[SPEC-ID]] syntax, where SPEC-ID is the referenced specification's in the Specref ecosystem - which includes most W3C, WHATWG, ECMA, and IETF documents.

When you reference a specification, your document automatically gets a bibliography section.

Example 16: Reference to HTML spec

The [^link^] element is defined in the [[HTML]] spec.

Which renders as:

Screenshot to text above and automatically generated References section

If you would like the reference a specification by its full name, you can use the three square brackets to "expand it":

<p>
  The [^link^] element is defined in the [[[HTML]]].
</p>

Renders as:

The link element is defined in the HTML Standard.

Normative VS informative references 📝 Edit

ReSpec uses the context of the reference to work out if the reference is normative or informative: if the reference is in a section marked "informative", or an example, note, or figure, then ReSpec automatically makes the reference non-normative. Otherwise, the reference is treated as normative.

If you need a non-normative reference in a normative section, you can use a ? like so:

Example 17: Non-normative reference in a normative section

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

1.3.16 Escaping references 📝 Edit

To escape a reference, use a backslash "[[\". For example, "[[\InternalSlot]]".

1.3.17 Adding missing references 📝 Edit

If a reference is missing, please submit it to Specref. This helps the whole community.

If that is not possible, you can use of the localBiblio configuration option to define your own references.

1.3.18 Extra links at top of the document 📝 Edit

ReSpec supports adding additional links by specifying an otherLinks property in the configuration. The values for this configuration option are rich and complex, so are detailed in the reference section for otherLinks.

1.3.19 Custom Styles 📝 Edit

If you wish to add your own additional styles to your document, just use the regular <link> and <style> elements.

1.3.20 Advanced: Specifying Configuration via URL 📝 Edit

Some of ReSpec's configuration options can be specified in the query string, and they override the options specified in the source. For example, you can override the subtitle by, for example, doing the following: index.html?subtitle=This is a subtitle.

This is useful for quickly overriding configuration options without needing to directly edit the document itself (e.g., for the purpose of exporting a document draft with a different specStatus).

1.4 W3C Documents 📝 Edit

ReSpec provides useful options to handle the creation of the W3C boilerplate that goes into the "status of this document" and other key sections.

1.4.1 Short name 📝 Edit

Specifications typically require having a "short name", which is the name used (amongst other places) in the canonical "https://w3.org/TR/short-name/" URLs. This is specified using the shortName option, as seen in the example above.

1.4.2 Working Group Information 📝 Edit

The group configuration option lets you state to which working/business/community group your specification belongs to. The list of group identifiers can be found at: https://respec.org/w3c/groups/.

Setting the group option sets the IPR Policy for your document, which is reflected in the "Status of this Document" section.

1.4.3 Non-Recommendation track docs 📝 Edit

If your document is not intended to be on the W3C Recommendation Track, set noRecTrack to true.

1.4.4 Specification Status 📝 Edit

The specStatus option denotes the status of your document, per the W3C Recommendation track. Typically, a status has implications in terms of what other options required. For instance, a document that is intended to become a Recommendation will require previousPublishDate and previousMaturity.

The specStatus section list all the possible status values.

1.4.5 Copyrights & Patents 📝 Edit

By default, W3C specifications all get the regular W3C copyright notice. In some cases however, you will want to modify that.

For all document types, you can add your own copyright by using <p class="copyright">.

At times, the patent situation of a specification may warrant being documented beyond the usual boilerplate. In such cases, simply add your own <p> to the Status of this Document section.

1.5 WebIDL Guide 📝 Edit

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

Example 18: Declaring a WebIDL block.

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

Ideal linking setup 📝 Edit

The recommended way to code up your WebIDL is as follows:

Example 19: WebIDL definitions and linking.

<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>The {{ExampleInterface/exampleMethod()}} method steps are:</p>
    <ol class="algorithm">
      <li>Let |x| be ...</li>
    </ol>
  </section>
  <section>
    <h2><dfn>url</dfn> attribute</h2>
    <p>The {{ExampleInterface/url}} attribute...</p>
  </section>
</section>
<section>
 <h2>Here is how you link!</h2>
 <p>
  The {{ExampleInterface}} 
  or the {{ExampleInterface/exampleMethod()}} method
  or the {{ExampleInterface/url}} attribute.
 </p>
</section>

Defining the interface 📝 Edit

Given interface Request {};, you can define the interface inside a heading like so:

Example 20: Defining WebIDL interfaces.

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

The above provides convenient linking to the section where the interface is defined.

Using `data-dfn-for`📝 Edit

When defining things, the data-dfn-for creates child-parent relationships (e.g., a .method() is "for", or part of, SomeInterface).

For example, the following defines both the url and the clone method.

Example 21: Using data-dfn-for.

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

Multiple interfaces with same attributes/methods 📝 Edit

If, for instance, you have two interfaces with methods or attributes that are the same:

Example 22: Multiple interfaces with same attributes/methods.

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

You explicitly distinguish between them like so:

Example 23: Distinguishing between multiple interfaces with same attributes/nodes.

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

3. Shorthands Cheat Sheet 📝 Edit

Similar to markdown, shorthands trigger special behavior in ReSpec. The most commonly used one you've likely seen is [[Reference]]. Shorthands save you time and work: you write a lot less HTML, and ReSpec does all the linking and error checking for you.

Each of these special character combinations, as well as what behavior they trigger, are detailed below.

Note

Note: Only WebIDL identifiers are case sensitive.

Type	Syntax	Examples
WebIDL	`{{WebIDLThing}}`	`{{PaymentRequest}}` `{{PaymentRequest/show()}}`
Concepts in specs	`[=normal link=]`	`[=queue a task=]`
Variable in an algorithm	`\|variable:Type\|`	Let `\|p:Promise\|` be a new `{{Promise}}`
HTML/SVG elements	`[^element^]`	`[^iframe^]`
Element attributes	`[^element/attribute^]`	`[^iframe/allow^]`
References	`[[shortName]]`	`[[RFC2119]]`
Expansions	`[[[#some-id]]]`	`[[[#example-2]]]` expands and links to `"Example 2"`

By design, we also share a lot of syntax with the BikeShed document processor. This makes it easier for everyone in the standards community to edit ReSpec and BikeShed specifications.

3.1 WebIDL 📝 Edit

WebIDL is a meta language that used to define Javascript APIs for Web browsers. Please see our WebIDL Guide or 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.

Examples 📝 Edit

Type	Syntax	Examples
[Interface], [Dictionary], [Enum] or [IDL type]	`{{Identifier}}`	`{{PaymentRequest}}` `{{unrestricted double}}` `{{long long}}`
[Attribute]	`{{Identifier/attributeName}}`	`{{PaymentRequest/id}}`
[Operation or Method]	`{{Identifier/methodName()}}` `{{Identifier/methodName(someArg)}}`	`{{PaymentRequest/show()}}` `{{PaymentRequest/show(detailsPromise)}}`
[Static Attribute]	`{{Identifier.attribute}}`	`{{SomeInterface.someAttribute}}`
[Static Operation or Static Method]	`{{Identifier.methodName()}}` `{{Identifier.methodName(arg)}}`	`{{URL.createObjectURL()}}` `{{URL.createObjectURL(obj)}}`
[Enum Value]	`{{Identifier/"value"}}`	`{{PaymentComplete/"success"}}`
[DOM Exception]	`{{"Identifier"}}`	`{{"NotAllowedError"}}`

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.

Linking to concepts 📝 Edit

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:

Example 24: Linking to concepts with xref and shorthands.

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

Plural Forms 📝 Edit

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

Aliasing concepts 📝 Edit

Warning: Aliasing is not recommended.

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 🙇‍♂️).

Examples 📝 Edit

Type	Syntax	Examples
Concept	`[=concept=]`	`[=queue a task=]`
Aliased concept	`[=concept\|some alias=]` `[=convoluted thing\|simpler thing=]`	`[=queue a task\|task queuing=]`

Scoped concepts 📝 Edit

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:

Example 25: Concepts scoped to other concepts.

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.

Examples 📝 Edit

Type	Syntax	Examples
Concept for thing	`[=concept/sub concept=]`	`[=list/for each=]` `[=map/for each=]` `[=Document/visible=]`

3.3 Variables in algorithms 📝 Edit

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

Example 26: Shorthand syntax for declaring a variable 'value'.

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

Giving variables data types 📝 Edit

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

Examples 📝 Edit

Type	Syntax	Examples
Variable	`\|variable\|`	`\|value\|`
Variable with a data type	`\|variable:dataType\|`	`\|value:DOMString\|`

3.4 HTML/SVG 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.

Examples 📝 Edit

Type	Syntax	Examples
Element	`[^element^]`	`[^iframe^]`
Element with Content Attribute	`[^element/contentAttribute^]`	`[^iframe/allow^]`

Note

Note: To link to an IDL attribute on a HTML element's interface, which is different from an element attribute, you would do, for example {{HTMLIframeElement/allow}}.

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.

Examples 📝 Edit

Type	Syntax	Examples
Normal Reference	`[[SHORTNAME]]`	`[[HTML]]`
Expanded Reference	`[[[SHORTNAME]]]`	`[[[FULLSCREEN]]]`, `[[[fullscreen API]]]` are expanded and rendered as `Full Screen API`
Informative spec	`[[?SHORTNAME]]`	Payments can be useful `[[?PAYMENT-REQUEST]]`.
Escaped reference	`[[\anything]]`	This is not a reference. It is `[[\something else]]`.
Inner-document expansion	`[[[#fragment]]]`	`See [[[#installability-signals]]]` is expanded and rendered as `See § 2.6 Installability signals`.
Multi-page reference	`[[SHORTNAME/page#fragment]]`	`[[SOMESPEC/foo.html#bar]]` (Not recommended, use only if you really need it!)

5. Configuration Options

5.1 `addSectionLinks`📝 Edit

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

Example 33: Turn off § section markers

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

5.2 `authors`📝 Edit

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

Note

Note: In most cases, editors is preferred over authors.

Example 34: List of authors

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.3 `caniuse`📝 Edit

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

Example 35: Caniuse table for payment-request

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

Example 36: Caniuse with specific browsers

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

Note

Note: This feature is only available in "live" Editor's Drafts. Because this feature relies on JavaScript, it's not exported out when a document is saved as HTML. In exported document, the table is replaced by a link to caniuse.com.

It renders as:

Can I Use preview for Payment Request API

Configuration Options:📝 Edit

feature

(required) Can I Use feature key

browsers

Array of browsers to show support for.
Default: ["chrome", "firefox", "safari", "edge"]
Supported Values:

and_chr - Chrome (Android)
and_ff - Firefox (Android)
and_uc - UC Browser (Android)
android - Android
bb - Blackberry
chrome - Chrome
edge - Edge
firefox - Firefox
ie - IE
ios_saf - Safari (iOS)
op_mini - Opera Mini
op_mob - Opera Mobile
opera - Opera
safari - Safari
samsung - Samsung Internet

versions

Number of browser versions to show
Default: 4

maxAge

Cache duration (in ms).
Set to 0 to get fresh data each on each request.
Default: 86400000 // 24 hours

apiURL

(INTERNAL, for testing only) Use a custom URL that returns a JSON response with stats key as the browser data object.
Use {FEATURE} as placeholder in URL to replace it by a value of caniuse.feature

5.4 `edDraftURI`📝 Edit

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

Note

Note: it is strongly recommended that you don't publish Editor's drafts, and instead auto-publish your specification using the W3C's Echidna workflow.

Example 37: Add Editor's Draft URL

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

5.5 `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.

Example 38: List of editors

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.6 `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).

Example 39: Interpret content as Markdown

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

See: Using Markdown with ReSpec Guide.

5.7 `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.

Example 40: List of former 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.8 `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:

It adds "Feedback:" to the header of the document, with the appropriate links to your GitHub repository.

feedback header, with links to pull request, open issues, and create new issue on Github

This is normally what you want:

Example 41: Set GitHub repository

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

Example 42: Set GitHub repository as a URL

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.

Example 43: Set GitHub repository with a different default branch

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

5.9 `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.

Example 44: Enable variable highlighting

var respecConfig = {
  highlightVars: true,
};

It renders as:

Note

Note: This feature is only available in "live" Editor's Drafts. Because this feature relies on JavaScript, it's not exported out when a document is saved as HTML.

5.10 `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.

Example 45: Add a 'preview' warning

var respecConfig = {
  isPreview: true,
};

5.11 `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: CC0 is an extremely permissive license. It is only recommended if you are working on a document that is intended to be pushed to the WHATWG. Not supported for W3C documents.
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.
document: NOT RECOMMENDED - the W3C document license. Please use the "w3c-software-doc" license instead.
dual: W3C dual license - uses W3C document license + cc-by (recommended you use "w3c-software-doc" instead)

5.12 `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:

Example 46: Disable linter.

var respecConfig = {
  lint: false,
};

You can also enable or disable certain rules:

Example 47: Enable or disable certain linter 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.12.1 `a11y`📝 Edit

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

Note

Note: Using this on hosted documents (e.g., on GitHub pages) can slow down the rendering and may make the page unresponsive. Please only enable only the rules you need.

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

Example 48: Run all default rules

var respecConfig = {
  lint: {
    a11y: true,
  }
};

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

Example 49: Run only a specific rules

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

Another example:

Example 50: Enable or disable certain rules

var respecConfig = {
  lint: {
    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:

Accessibility warnings in ReSpec

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.

You can also use respecConfig.a11y to define the linter config (instead of respecConfig.lint.a11y). This lets us quickly run the linter by adding a URL param ?a11y=true.

5.12.2 `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 51: 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 52: Enable no-http-props linter rule.

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

5.12.3 `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 53: 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 54: Enable local-refs-exist linter rule.

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

5.12.4 `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 55: 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 56: Enable no-headingless-sections linter rule.

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

example warning for no-headingless-sections

developer console with warning for no-headingless-sections

5.12.5 `no-unused-vars`📝 Edit

Enable this lint rule to get a warning if a variable is defined but not used. The first use of variable (<var>) is considered its definition. Only unused variables in sections that contain a <ol class="algorithm"></ol> are reported.

For example:

Example 57: Used and unused variables.

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

You'll receive a warning pointing you to the unused <var>s.

Example 58: Enable no-unused-vars linter rule.

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

`data-ignore-unused` attribute 📝 Edit

To ignore warning on per-variable basis, add a data-ignore-unused attribute to <var> as:

Example 59: Use data-ignore-unused attribute to ignore the warning.

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

Note that the |someVar| shorthand does not support this attribute.

5.12.6 `check-punctuation`📝 Edit

Enable this lint rule to check for punctuation. It checks for:

Punctuation mark at the end of <p> tag.

For example:

Example 60: A paragraph with bad punctuation.

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

You will receive a warning that your <p> tag should end with punctuation mark.

Example 61: Enable check-punctuation linter rule.

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

5.12.7 `privsec-section`📝 Edit

For certain types of documents, this lint rule warns if the documents is missing a Privacy and/or Security considerations section. This rule is on by default for W3C documents.

Example 62: Disable privsec-section linter rule.

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

5.12.8 `wpt-tests-exist`📝 Edit

Enable this lint rule to get a warning if any of the tests mentioned in data-tests does not exist in the WPT repository.

For example:

Example 63: data-tests with a missing test.

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

You'll receive a warning listing all the missing tests.

Example 64: Ensure all data-tests WPT exist for WebRTC.

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.13 `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.

Note

Note: use of localBiblio is strongly discouraged. Please contribute references back to the SpecRef database instead.

Example 65: A sample localBiblio entry.

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

5.14 `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.

Example 66: Add a custom logo at top of page.

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.15 `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.

Example 67: Set maximum ToC depth to 2 (i.e., skip §1.1.1).

var respecConfig = {
  maxTocLevel: 2,
};

5.16 `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.

Example 68: Add MDN tables with shortName as MDN key.

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

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

Example 69: Add MDN tables with specific MDN key.

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:

MDN panel demo in ReSpec

5.17 `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.

Example 70: Add a modification date for an already published document.

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

5.18 `monetization`📝 Edit

Adds a "monetization" <meta> tag to enable Web Monetization.

This options takes either a boolean, a string (a payment pointer), or an object with a paymentPointer (string) and removeOnSave (boolean) property.

By default, the meta tag is added only to "live" documents, and is removed from generated static documents.

Example 71: Add a monetization meta tag with a custom payment pointer.

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

If you do not explicitly disable this feature or set a different payment pointer, it uses ReSpec's payment pointer by default.

To disable web monetization entirely:

Example 72: Disable web monetization.

var respecConfig = {
  monetization: false,
};

To keep the payment pointer in a generated snapshot:

Example 73: Using removeOnSave.

var respecConfig = {
  monetization: {
     paymentPointer: "$customPointer",
     removeOnSave: false,
  }
};

5.19 `noTOC`📝 Edit

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

Example 74: Do not generate a Table of Contents.

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.

Example 75: Use otherLinks to add links to implementation status.

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.

Example 76: Enable automatic pluralization.

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:

Example 77: Automatic pluralization in action.

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

Note

Note: We tried to make the pluralization as smart as possible, so that it won't break existing specs easily. It adds plurals only for those terms which are referenced. So in the above example if you don't reference <a>fetches</a> or <a data-lt="fetches">fetch request</a>, we won't add a pluralization of fetch.

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

Example 78: Skip automatic pluralization per <dfn>.

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

5.22 `postProcess`📝 Edit

Takes an array of JavaScript functions which ReSpec then runs in order. Each function is called with the ReSpec config object (i.e., the var respecConfig object, plus some additional internal data).

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

Example 79: Run two functions in order after processing.

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

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

Note

Note: there are no special requirements or "best practices" for how you process HTML either before or after ReSpec has finished doing its thing. Once ReSpec is finished processing the document, it stops running and you a free to do whatever you like to your document. Having said that, you should follow web development best practices for Web Development when manipulating any generated document (i.e., "it's just HTML, JS, and CSS").

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.

Example 80: Run two functions in order before processing.

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.

Example 81: Set January 2, 2021 as publish date.

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

Example 82: Set 'awesome-api' as specification's short name.

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

5.26 `specStatus`📝 Edit

Specifications can be given a status (e.g. a Working Draft, an Unofficial document, etc). However, what that status means is up to the publisher, or standards body, that is publishing the specification.

Example 83: Set specification's status to 'unofficial'.

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

Default Status
Value	Meaning	Must also include
base (default)	Just the basic template, not a specification. Use this for public documentation produced by a group that has no current clear plan to be officially published.	None.
unofficial	An unofficial draft. Use this if you're producing a document to use styles that match those of W3C specifications, for instance to propose a new document while hosting it on your own server. Note that this automatically licenses the content under CC-BY v3.0. If you want a different copyright, you will need to set the various copyright configuration options.	xref (required only if linking built-in IDL types).

W3C 📝 Edit

For W3C documents, the following status are supported.

W3C Status
Value	Meaning	Must also include
MO	Member-Only Document. Similar to base, but for documents that need to be clearly flagged as being restricted in access to W3C Members. This is rarely, if ever, useful.	None.
ED	Editor's Draft. Use this for documents that are maintained in the group's own repository.	Note: You can exclude the "Latest Published Version" link by using `latestVersion: null` (See #2968 for details).
FPWD	First Public Working Draft.	None.
WD	Working Draft.	previousPublishDate previousMaturity.
LC	Last Call Working Draft.	previousPublishDate previousMaturity lcEnd
LD	Living Document.
LS	Living Standard.
CR	Candidate Recommendation.	previousPublishDate previousMaturity crEnd implementationReportURI
CRD	Candidate Recommendation Draft.	Same as CR above.
PR	Proposed Recommendation.	previousPublishDate previousMaturity
PER	Proposed Edited Recommendation.	previousPublishDate previousMaturity
REC	Recommendation.	previousPublishDate previousMaturity
RSCND	Rescinded Recommendation.	previousPublishDate previousMaturity
STMT	Statement.	previousPublishDate previousMaturity
DNOTE	Draft Group Note.	None.
NOTE	Group Note.	None.
BG-DRAFT, BG-FINAL	Business Group Draft or Final Report.	None.
CG-DRAFT, CG-FINAL	Community Group Draft or Final Report.	None.
Member-SUBM	Member Submission. Note that ReSpec uses the default W3C copyright for this, but that you are entitled to retain your own copyright instead of transferring it to W3C. Use the copyright options for this.	submissionCommentNumber
draft-finding	Draft TAG Finding. If you are one of the Nine and working on a Finding, this is for you. Note that for findings, ReSpec currently does not support very robust SotD generation (there doesn't seem to be solid rules for what constitutes a valid Finding SotD) so you'll have to specify your own. If there are rules that could be used, please report a bug. ReSpec further assumes some conventions for finding URLs that are not consistent throughout all of the TAG's repository, specifically that all findings live in "https://www.w3.org/2001/tag/doc/", that the latest version is at "https://www.w3.org/2001/tag/doc/shortName", and that the dated versions are at "shortName-YYYYMMDD".	None.
editor-draft-finding	Editor Draft TAG Finding. If you're working on a TAG document maintained on GitHub rather than in the old datedspace system, use this.	None.
finding	TAG Finding. Same as above, but final.	None.

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.

Example 84: Add a prefix for mailing list subjects.

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.

Example 85: Add a specification subtitle.

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.

Example 86: Add a test suite URL to be included in page header.

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

Also see: wpt-tests-exist lint rule.

5.30 `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="".

xref configuration options 📝 Edit

The following configurations are available:

Boolean value. Setting xref: true simply enables the xref feature.
Array of specification short-names. This option enables xref, but also adds the specification short-names in the array to the data-cite attribute of the document's <body>. ReSpec then uses these specifications for disambiguation.
Profile name (string). Specification Profiles are described below.
Object with the optional properties url, specs and profile.
1. url is used to link to a custom references API.
2. specs is used to specify an array of specification short-names. This array is added to the data-cite attribute of the document's <body> and used for disambiguation.
3. profile is used to specify profile.

Note that when using the object configuration, if both profile and specs properties are specified, then the specification short-names in specs combined with the ones in the profile used, are used for disambiguation.

xref profiles 📝 Edit

Profiles are pre-defined lists of specifications. Using a profile means adding all of its specification short-names to the data-cite attribute of the document's <body>.

Following profiles are currently available:

web-platform: Specifications included: "HTML", "INFRA", "URL", "WEBIDL", "DOM", "FETCH"

Example 87: Enable xref.

var respecConfig = {
  xref: true,
};

Example 88: Search term in specs under 'web-platform' profile.

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

Example 89: Search for terms in 'spec1' and 'spec2' specifications.

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

Using the specs spec1 and spec2 along with specs in the web-platform profile to look for references.

Example 90: Specify profile and use additional specs. for searching

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

6. W3C Specific Configuration Options

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.

Example 91: Add an additional copyright holder.

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

You can preview this feature in live examples:

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

Example 92: Add a patent note.

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

Example 93: Show links to PDF and XML versions of current document.

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.

Keyword	Generated URL
`"edDraft"`	Use the `edDraftURI` as the canonical URL.
`"TR"`	Use the "TR" location for this document, using the `shortName`.

Example 94: The following will result in a canonical URL of https://www.w3.org/TR/fooAPI.

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.

Example 95: Add charter disclosure URL for IG-NOTE.

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.

Example 96: Set the copyright start year to 1977.

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.

Example 97: Set January 4, 2014 as CR end date.

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.

Example 98: Enable JSON-LD data generation.

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:

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.

Example 99: Add URL to errata.

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.

Example 100: Use Web Payments Working Group.

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

You can also specify multiple groups:

Example 101: 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:

Example 102: Specify group type.

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.

Example 103: Add URL of the implementation report.

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

6.12 `latestVersion`📝 Edit

For W3C Community Groups and Business Groups, it allows you to specify a URL for where the "Latest Version" of a specification can be found (e.g., on GitHub, using GitHub pages).

For regular W3C Working Groups,latestVersion is automatically set. However, in rare cases, you can override the "Latest Version" to point to a different path or URL.

Note

Note: The latestVersion URL is resolved using https://www.w3.org/ as the base URL.

Example 104: Adding a latest version

var respecConfig = {
  latestVersion: "https://respec.org/docs/";
}

6.13 `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.

Example 105: Set Last Call review end date to January 3, 2016.

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

6.14 `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.

Note

Note: Refrain using a level unless you've considered all the implications of doing so. Levels can be very hard to maintain, specially if levels are evolving concurrently.

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.

Example 106: Set the current specification to level 2.

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.15 `noRecTrack`📝 Edit

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

Example 107: Mark current spec not intended for Recommendation track.

var respecConfig = {
  noRecTrack: true,
};

6.16 `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.

Example 108: Specify URL to previous editor's draft.

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

6.17 `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.

Example 109: Specify the previous URL for diff generation.

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.18 `previousMaturity`📝 Edit

A specStatus identifier (e.g., "CR"). 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).

Example 110: Set Last Call (LC) as document's previous maturity level.

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

6.19 `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.

Example 111: Set previous publish date to May 1, 2014.

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

6.20 `prevRecShortname`📝 Edit

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

Example 112: Set shortName for previous version of recommendation.

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

6.21 `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.

Example 113: Set URL of previous version of Recommendation.

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

6.22 `submissionCommentNumber`📝 Edit

Allows W3C staff to link to a comment number.

Example 114: Link to submission comment number 03.

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.23 `wgPatentPolicy`📝 Edit

Note

Note: If you're using the group configuration option, this is set automatically for you.

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

Possible values are:

"PP2020"
"PP2017"

Usage example 📝 Edit

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

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

6.24 `wgPublicList`📝 Edit

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

Example 115: Specify short name of public mailing for spec's group.

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

9. CSS classes

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.

Example 132: Mark a section as being 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.

Example 133: An Editor's note.

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

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.

Example 134: Mark an aside as example.

<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 `exclude`📝 Edit

The exclude CSS class allows HTML tags to opt-out of being processed by ReSpec.

It is only supported on the following elements:

<abbr class="exclude">TEXT</abbr> - excludes the element from automatic abbreviation generation, such that TEXT won't be wrapped in <abbr>.
<pre class="idl exclude">, excludes the WebIDL block from the IDL index. This is useful if you want to have an WebIDL example that is not actually part of your specification.

Some examples of usage:

Example 135: Excluding things

<p>
 <abbr class="exclude" title="Ay-Bee-See">ABC</abbr>,
 but this won't be wrapped ABC.
</p>

<aside class="example" title="A hypothetical API">
  <pre class="idl exclude">
    interface ItsTwentyTwenty {
      undefined cantSeeNobody();
    };
  </pre>
</aside>

9.5 `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.

Example 136: Mark a section as non-normative.

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

9.6 `issue`📝 Edit

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

Example 137: Reference GitHub issue #363 in-place.

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

Note

Note: We discourage the use of this feature, because you could miss defining important things. However, if you know you don't want to link certain things (e.g., a Dictionary and an interface).

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.

Example 138: Disable warnings about missing or broken links.

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

Example 139: Disable syntax highlighting.

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

But this one will be syntax-highlighted by default:

Example 140: All pre elements are 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.

Example 141: Disable 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.

Example 142: Treat given paragraph as a note.

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

9.11 `notoc`📝 Edit

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

Example 143: Skip a section from 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

Warning: only use this as a last resort. This feature is not recommended.

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

Example 144: Completely override the content of 'Status of this Document' section.

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

Example 145: Remove some content once ReSpec has finished processing.

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

Example 146: Remove some content before export.

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

9.18 W3C Specific

9.18.1 `updateable-rec`📝 Edit

For W3C Proposed Recommendations, declaring class="updateable-rec" on the Status of This Document <section> indicates the specification intends to allow new features once it becomes a W3C Recommendation. This will include the appropriate boilerplate text for you.

Example 147: using updateable-rec

<section id="sotd" class="updateable-rec">
  <p>Other status related stuff here...</p>
</section>

10. HTML Attributes

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.

Example 148: Generate abbreviation automatically.

<!-- these two are the same -->
<dfn data-abbr>user agent</dfn>
<dfn data-abbr="">user agent</dfn>

Becomes:

<dfn>user agent</dfn> (<abbr title="user agent">UA</abbr>).

You can also set the abbreviation by yourself.

Example 149: Explicitly specify an abbreviation.

<dfn data-abbr="PoS">point of sale</dfn>

Becomes:

<dfn>point of sale</dfn> (<abbr title="point of sale">PoS</abbr>)

10.2 `data-cite`📝 Edit

Note

Note: This is not the recommended way of linking to terms in other specs. Please use xref whenever possible.

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.

Example 150: Using data-dfn-for for defining 'scope'.

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

Example 151: Specifying data-dfn-type.

<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 Webref database.

Note

Note: Your spec needs to be part of the browser specs to be indexed by Webref.

Note

Note: Only export things that other specifications need! (e.g., special objects, specific algorithms).

Note

Note: WebIDL things are automatically exported for you.

Example 152: Explicitly export a definition.

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

Example 153: Using definitions exported from other specs using xref.

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

Example 154: Interpret content of given section as markdown.

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

Example 155: Include content from another file.

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

Example 156: Treat the content of some.txt as plain text.

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

Example 157: Replace element with data-include with included content.

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

Example 158: A comparison of linking global and scoped definitions

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

Example 159: Linking scoped IDL definitions.

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

Example 160: Using data-link-for to link under given scope.

<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

Note

Note: This is mostly internal. Prefer Shorthands Syntax, as they automatically add this attribute to relevant elements.

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

Example 161: Providing alternate linking text with data-local-lt and data-lt.

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

Example 162: Providing alternate linking terms for a definition.

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

Example 163: Disable automatic pluralization for specific definition.

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

Example 164: Only data-lt is used for referencing the second definition.

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

Example 165: Skip sections with depth more than 2 from ToC.

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

Example 166: Skip current section from ToC.

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

Example 167: Embed content of a GitHub issue in-place.

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

Example 168: Transforming content included via data-include before further processing.

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

Regular list 📝 Edit

Example 169: Sorting an unordered list in descending order.

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

becomes:

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

Definition list 📝 Edit

Sorting a definition list ("ascending" by default, so A-to-0Z locale dependent). The corresponding dds for any dt are also moved, but not sorted.

Example 170: Sorting a definition list in ascending order of definition terms.

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

becomes:

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

Example 171: Link tests to the prose.

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

Example 172: Set directionality to right-to-left.

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

Example 173: Set document language to French.

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

D. Developers Guide

Clone the repo and install the needed dependencies:

git clone git@github.com:w3c/respec.git
npm install

Now you can start the local development servers:

npm start -- --browser Chrome

Note

Note: You can use Firefox and ChromeCanary in the above.

That will start up "Karma" and a local http server for you.

Open the url given (usually http://127.0.0.1:8000). And go to "examples".

Usually "basic.html" is a good place to start hacking from.

D.1 ReSpec's architecture

ReSpec is an application that runs mostly synchronous bits of JS after a Document loads. These JavaScript fragments are referred to as "plugins". When a bunch of plugins are combined together, they create a "profile".

Generally, a "profile" is only created for a real-world organization or company. So, for instance, the W3C's profile, located at profiles/w3c.js, loads the following plugins (not the full list, just for illustrative purposes):

core/base-runner
core/include-config,
core/style,
w3c/style,
core/markdown,
w3c/headers,
...

What each plugin above does doesn't matter, though you can deduce what each does by the name. What matters is that ordering is important - and we mix together W3C plugins and "core" plugins. And that it's these plugins coming together that form a profile, in this case the "W3C profile". Each of the plugins are run only once - and the thing that runs them is the core/base-runner plugin.

See profile/w3c.js for the actual details of how the profile is set up. But it's essentially:

Load the profile + all the plugins (but don't "run" them yet!).
Wait for the document's "DOMContentLoaded" event to fire.
Once DOM is ready, run each plugin in order, waiting for each plugin to finish.

D.2 Core Base runner (`core/base-runner.js`)

The first and most important plugin (core/base-runner), is actually the "brains" of ReSpec: it is the thing that "runs" all other plugins in order.

Before any plugins are run, however, it adds the following property to the document object:

// The following only resolves once all plugins have run
// and ReSpec has finished doing whatever it needs to do.
document.respec.isReady;

After that, the Base Runner starts looping over an array of given plugins: literally just a call to a .runAll(arrayOfPlugins) method. For each plugin, it waits until a plugin has finished doing its work before continuing to the next plugin. It does this by calling the run() function exported from a plugin, and awaiting for that function to finish. Some plugins may export a Plugin class with a run() method instead.

Once all the plugins have "run", ReSpec resolves the respec.isReady promise on the Document object.

document.respec.isReady.then(() => {
  console.log("ReSpec has finished processing this document");
});

This is potentially useful for scripts that depend on ReSpec's output. They can wait for the promise to settle before doing their own work.

Alternatively, if you really need to run things immediately before or after ReSpec runs the plugins, you can define preProcess or postProcess properties on the configuration object. See preProcess and postProcess more details and for examples.

D.3 Plugins

Plugins are simple ES6 modules that live in the "src/" folder. They have two parts: A synchronous initialization, and an optionally exported run() function that is called asynchronously.

A plugin looks like this:

// import other things you need
import utils from "core/utils";

// This part runs synchronously and an indeterminate order.
// do any plugin specific setup here. Note, the document
// can be in an unstable state here - so don't manipulate
// the DOM here!

// Optionally, export "run" function
// See below for description of arguments.
export async function run(conf) {
  if ("something" in conf || document.querySelector("#important-element")) {
    await someAsyncTask();
  }
}

async function someAsyncTask() {
  // Your code here
}

The exported run method SHOULD have arguments (conf):

conf: is the ReSpec configuration object (window.respecConfig) - which the user defined. Be careful not to modify this object.

Warning users of errors

If you are creating a plugin that needs to show warnings to a user, you can use the "core/pubsubhub" utility. As the name suggests, this is a simple pub-sub-hub dispatcher. You should use this to dispatch "warn" or "error" messages to a user:

import { pub } from "./core/pubsubhub.js";
export async function run(conf) {
  if (!"something" in conf) {
    pub("warn", "Markdown that represents a warning");
  }
}

These "warn" and "error" messages will be picked up by ReSpec's UI (the "pill"), and displayed to the end-user. You should only "error" on things that the user needs to fix to successfully publish their document. Likewise, only warn on things the user SHOULD fix.

IMPORTANT: Don't show JavaScript errors to the user - as they won't be able to fix these, and the minified JS output will make these messages really unhelpful!

D.4 `npm start`

The start script in package.json contains the commands useful during development. It runs a static HTTP server, watches files for change and re-build the profile, and run unit tests.

D.5 Built-in HTTP server

You can launch a built in HTTP server during development by simply typing: npm start. If you wish not to run tests and other parts of start script, you can alternatively run npm run server.

Testing

ReSpec's unit tests are written using Jasmine and run on Karma. To start the testing server:

npm start -- --browser Firefox

You can run test in different browsers by setting browsers value above to any of: Firefox, FirefoxHeadless, Chrome, ChromeHeadless, Safari. Same can be set using the BROWSERS environment variable:

BROWSERS="ChromeHeadless Firefox" npm start

For debugging purposes, you can click on the Debug button when the tests start in the browser - this will allow you to see the tests summary in browser itself as well as allow you to re-run any particular test.

Please refer to Jasmine documentation regarding focused specs (fdescribe(), fit()) to see how to run only specific tests when running npm run karma. This will save you a lot of time and pain.

You can also select individual tests by filtering those which match a particular pattern:

npm start -- --grep="SEO"

If you want to run all tests whose description includes "SEO".

Interactive mode

You can also run start in "interactive" mode. This gives you more control over when tests are run and, by default, turns off automatic file watching.

npm start -- --interactive

This is useful for more advanced debugging sessions, and can be combined with --grep to test just what you want, when you want.

Testing without opening browser window

You can also run tests without opening a full browser window. Test results will be visible in your terminal.

npm start -- --browser FirefoxHeadless
# or use ChromeHeadless

Look at the help dialog when you run npm start for more options.

Custom profiles

If you are a company, standards consortium, or government entity, you might want to consider maintaining your own ReSpec profile. That allows you have your own content templates, load whatever plugins you need, and generally keep control over how ReSpec runs.

To create a custom profile:

Make a copy of "profiles/w3c.js", but rename it "YOUR-PROFILE-NAME.js".
Open "YOUR-PROFILE-NAME.js", and remove, add, etc. any plugins you want.
run: node ./tools/builder.js YOUR-PROFILE-NAME. That will generate a bundle in the build directory.

If the profile is popular, then please send a pull request to the main repository and we can host as part of the main project.

Working with your new profile

In examples/, make a copy of "basic.html" and point the <script> tag at your new profile. Now run:

npm start -- --profile YOUR_PROFILE_NAME --browser Chrome

That will start a web server, so you can now load up http://localhost:8000/examples and have play with your custom profile.

Testing your profile

If you are writing custom Jasmine tests, simply place them into tests/spec/YOUR-PROFILE-NAME/. And then run:

npm start -- --interactive --profile=YOUR-PROFILE-NAME --browser Chrome

If you prefer to use a different browser, that's ok too.

ReSpec Documentation

Abstract

1. Getting Started📝 Edit

1.1 Including ReSpec in HTML documents📝 Edit

1.2 Configuring ReSpec📝 Edit

1.3 Structure📝 Edit

1.3.1 Title📝 Edit

1.3.2 Subtitle📝 Edit

1.3.3 Editors & Authors📝 Edit

1.3.4 Sections📝 Edit

1.3.5 Table of Contents📝 Edit

1.3.6 Figures & table of figure📝 Edit

1.3.7 Examples📝 Edit

1.3.8 External Includes📝 Edit

1.3.9 Conformance section📝 Edit

1.3.10 Abbreviations📝 Edit

1.3.11 Inline Code📝 Edit

1.3.12 Definitions and linking📝 Edit

1.3.13 Automatic pluralization📝 Edit

1.3.14 Aliases and synonyms📝 Edit

Referencing terms from other specifications📝 Edit

Linking shorthands📝 Edit

1.3.15 References📝 Edit

Normative VS informative references📝 Edit

1.3.16 Escaping references📝 Edit

1.3.17 Adding missing references📝 Edit

1.3.18 Extra links at top of the document📝 Edit

1.3.19 Custom Styles📝 Edit

1.3.20 Advanced: Specifying Configuration via URL📝 Edit

1.4 W3C Documents📝 Edit

1.4.1 Short name📝 Edit

1.4.2 Working Group Information📝 Edit

1.4.3 Non-Recommendation track docs📝 Edit

1.4.4 Specification Status📝 Edit

1.4.5 Copyrights & Patents📝 Edit

1.5 WebIDL Guide📝 Edit

Ideal linking setup📝 Edit

Defining the interface📝 Edit

Using data-dfn-for📝 Edit

Multiple interfaces with same attributes/methods📝 Edit

2. Creating Static Snapshots📝 Edit

2.1 Using command line📝 Edit

3. Shorthands Cheat Sheet📝 Edit

3.1 WebIDL📝 Edit

Examples📝 Edit

3.2 Concepts📝 Edit

Linking to concepts📝 Edit

Plural Forms📝 Edit

Aliasing concepts📝 Edit

Examples📝 Edit

Scoped concepts📝 Edit

Examples📝 Edit

3.3 Variables in algorithms📝 Edit

Giving variables data types📝 Edit

Examples📝 Edit

3.4 HTML/SVG Elements and attributes📝 Edit

Examples📝 Edit

3.5 Referencing other specifications📝 Edit

Examples📝 Edit

4. Using Markdown with ReSpec📝 Edit

Automatic sectioning📝 Edit

Custom Heading IDs📝 Edit

Code blocks📝 Edit

HTML and Markdown📝 Edit

5. Configuration Options

5.1 addSectionLinks📝 Edit

5.2 authors📝 Edit

5.3 caniuse📝 Edit

Configuration Options:📝 Edit

5.4 edDraftURI📝 Edit

5.5 editors📝 Edit

5.6 format📝 Edit

5.7 formerEditors📝 Edit

5.8 github📝 Edit

5.9 highlightVars📝 Edit

5.10 isPreview📝 Edit

5.11 license📝 Edit

5.12 lint📝 Edit

5.12.1 a11y📝 Edit

5.12.2 no-http-props📝 Edit

1. Getting Started 📝 Edit

1.1 Including ReSpec in HTML documents 📝 Edit

1.2 Configuring ReSpec 📝 Edit

1.3 Structure 📝 Edit

1.3.1 Title 📝 Edit

1.3.2 Subtitle 📝 Edit

1.3.3 Editors & Authors 📝 Edit

1.3.4 Sections 📝 Edit

1.3.5 Table of Contents 📝 Edit

1.3.6 Figures & table of figure 📝 Edit

1.3.7 Examples 📝 Edit

1.3.8 External Includes 📝 Edit

1.3.9 Conformance section 📝 Edit

1.3.10 Abbreviations 📝 Edit

1.3.11 Inline Code 📝 Edit

1.3.12 Definitions and linking 📝 Edit

1.3.13 Automatic pluralization 📝 Edit

1.3.14 Aliases and synonyms 📝 Edit

Referencing terms from other specifications 📝 Edit

Linking shorthands 📝 Edit

1.3.15 References 📝 Edit

Normative VS informative references 📝 Edit

1.3.16 Escaping references 📝 Edit

1.3.17 Adding missing references 📝 Edit

1.3.18 Extra links at top of the document 📝 Edit

1.3.19 Custom Styles 📝 Edit

1.3.20 Advanced: Specifying Configuration via URL 📝 Edit

1.4 W3C Documents 📝 Edit

1.4.1 Short name 📝 Edit

1.4.2 Working Group Information 📝 Edit

1.4.3 Non-Recommendation track docs 📝 Edit

1.4.4 Specification Status 📝 Edit

1.4.5 Copyrights & Patents 📝 Edit

1.5 WebIDL Guide 📝 Edit

Ideal linking setup 📝 Edit

Defining the interface 📝 Edit

Using `data-dfn-for`📝 Edit

Multiple interfaces with same attributes/methods 📝 Edit

2. Creating Static Snapshots 📝 Edit

2.1 Using command line 📝 Edit

3. Shorthands Cheat Sheet 📝 Edit

3.1 WebIDL 📝 Edit

Examples 📝 Edit

3.2 Concepts 📝 Edit

Linking to concepts 📝 Edit

Plural Forms 📝 Edit

Aliasing concepts 📝 Edit

Examples 📝 Edit

Scoped concepts 📝 Edit

Examples 📝 Edit

3.3 Variables in algorithms 📝 Edit

Giving variables data types 📝 Edit

Examples 📝 Edit

3.4 HTML/SVG Elements and attributes 📝 Edit

Examples 📝 Edit

3.5 Referencing other specifications 📝 Edit

Examples 📝 Edit

4. Using Markdown with ReSpec 📝 Edit

Automatic sectioning 📝 Edit

Custom Heading IDs 📝 Edit

Code blocks 📝 Edit

HTML and Markdown 📝 Edit

5.1 `addSectionLinks`📝 Edit

5.2 `authors`📝 Edit

5.3 `caniuse`📝 Edit

5.4 `edDraftURI`📝 Edit

5.5 `editors`📝 Edit

5.6 `format`📝 Edit

5.7 `formerEditors`📝 Edit

5.8 `github`📝 Edit

5.9 `highlightVars`📝 Edit

5.10 `isPreview`📝 Edit

5.11 `license`📝 Edit

5.12 `lint`📝 Edit

5.12.1 `a11y`📝 Edit

5.12.2 `no-http-props`📝 Edit

5.12.3 `local-refs-exist`📝 Edit

5.12.4 `no-headingless-sections`📝 Edit

5.12.5 `no-unused-vars`📝 Edit

`data-ignore-unused` attribute 📝 Edit