ReSpec Documentation

W3C Document

Editor:
ReSpec
Participate:
GitHub w3c/respec
File a bug
Commit history
Pull requests
Edit this documentation:
GitHub Wiki
Single Page

Abstract

ReSpec is a JS library that makes it easier to write technical specifications, or documents that tend to be technical in nature in general. It was originally designed for the purpose of writing W3C specifications, but has since grown to be able to support other outputs as well.

1. Getting Started📝 Edit

This User's Guide is organized in such a way that a complete newcomer may read it linearly and understand everything. That being said, read it in whatever order you like.

1.1 Basic Layout📝 Edit

A ReSpec document is a straightforward HTML document that brings in the ReSpec script, defines a few configuration variables, and follows a few conventions.

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 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>
  </section>
  <section id="conformance">
    <p>This is required for specifications that contain normative material.</p>
  </section>
</body>
</html>

That is essentially the smallest W3C specification you can write using ReSpec (in practice, you could eliminate a few things but then you would have a truly useless document). Some of the configuration may seem cryptic, but it is there because all W3C documents must have some specific information available — all will be explained soon.

1.2 The Very Basics📝 Edit

The document that is rendered in your browser is quite different from the one which is authored. Yet they are the same document, with a sprinkle of ReSpec on top. Using your browser's developer tools, you may wish to take a look at the real DOM that is being produced and compare it with the source.

Some basic things can be seen above. First, as you can see from the DOCTYPE and the section elements, ReSpec documents are built on HTML. This does not imply that you need to know the ins and outs of HTML — just a few simple bits will suffice. It also does not imply that the resulting document that you will produce at the end will be HTML (you can output a limited set of other formats).

Note that the title of the document is reused as the title of the specification in the resulting document's h1. It's a small win, but that's always something less to repeat.

1.2.1 Including ReSpec📝 Edit

You can see that the example above includes a script sourced at:

  • https://www.w3.org/Tools/respec/respec-w3c

You may also be tempted to save the script to your local directory and use it from there. That may on occasion be useful (e.g., if you're on a flight and your cache is busted), but it is recommend that you link to the canonical URL provided above. The code is regularly updated and this will allow you to benefit from bug fixes and enhancements without even having to think about it.

1.2.2 Specifying Configuration📝 Edit

In the example you can see a script element defining a respecConfig variable. This is the ReSpec configuration. There are many things that can be done there, but we won't get into the details right now, but rather explore it piece by piece as needed. No doubt you can guess what some of those fields do.

One thing to remember though is this: that is how configuration is specified in ReSpec. Whenever you will see an indication that you can set a configuration option to a given value, it will be by modifying this object, simply adding, removing, or changing one of its fields.

Also note that this is just a simple JavaScript variable: there is nothing magical about the way in which it is declared (it just needs to be fully defined when the load event triggers).

Note

Note: There's a nifty trick that you will likely want to keep in your toolbox: many of ReSpec's configuration options can be specified in the query string, and they override the options specified in the source. We will use it a lot in this documentation so as to avoid having to generate examples for each small change that is possible (there are quite a few). So if we want to test the subtitle option without generating a copy of the same example with just that option changed, instead of accessing examples/basic.built.html we can simply go to examples/basic.built.html?subtitle=This is a subtitle.

1.3 Structure📝 Edit

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

1.3.1 Title and Subtitle📝 Edit

As noted in the previous chapter, 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. However, if you need to add additional markup to your title, you can still use a <h1> with id="title".

Example 2: Specification title with custom markup.
<h1 id="title">The <code>Foo</code> API</h1>

Optionally, you can also specify a subtitle configuration option in the ReSpec config. The subtitle configuration option takes a simple string that will be used as a subtitle for the specification, right under the title. As with the title, you can also specify a subtitle as:

Example 3: Specification subtitle with custom markup.
<h2 id="subtitle">Subtitle here</h2>

1.3.2 Editors & Authors📝 Edit

Every specification must have some editors (at least one) and may have some authors (and maybe some former editors/authors also).

Editors are the people in charge of the document. Authors are people who produced substantial contributions, but did not manage the document per se. Most of the time authors are not specified, but that practice varies between groups (it was more common in W3C XGs for instance, or sometimes the whole group is mentioned to get academic credit). Here is an example of specifying two editors and one author (with the surrounding document clipped for readability):

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

Editors and authors are specified as Person objects.

1.3.3 Sections📝 Edit

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

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

The first child element of a section is expected to be one of the h1-h6 elements. Any odd one will do, since whichever one you pick will be renamed to use the level that matches the depth at which your section is nested . As you can see, the example uses only h2 elements, but that is not what appears in the output. Using h2 everywhere is sort of a tacit convention, but if you prefer h5 that'll work just the same.

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

ReSpec sections understand some specific classes. First is the introductory CSS class. It is used (rarely) for preliminary content that sits at the beginning of the document and which is not expected to be linked to from the table of contents. The abstract, SotD, and ToC sections automatically fall into this category (you need not worry about flagging them as such); the example above adds an “Overview” section exemplifying the behavior. If you do wish all the introductory sections to be present in the ToC, see tocIntroductory.

Then is the informative CSS class, as seen on “Introduction” section in the example. It is 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.

And finally is the appendix CSS class. It marks a section as being an appendix, as can be seen appearing at the end of the example. One important thing to know about appendix sections is that all the sections that follow an appendix will also be marked as appendices.

If you wish to link to a section and have its number and title automatically appear as part of the link, then you can use an empty anchor pointing to that ID, as in <a href='#foo'></a>. The “Overview” section contains an example of that.

A table of contents is generated automatically and placed right after the SotD. If you have a deeply nested document structure and find that the ToC is either too long or too deep, you can use the maxTocLevel option to limit how deep it goes. In the example used above, there is no limit and indeed one section is numbered 4.1.1.1.1.1 — rather deep. Setting maxTocLevel to other values will yield different results (other example with maxTocLevel: 2). If you only have some sections that you would like excluded from the ToC, you can add the class notoc to associated section element and it will be omitted.

The more observant readers will have noted that ReSpec also inserts some strange-looking comments in the generated source, that look like <!-- OddPage -->. These are present so that html2ps knows how to paginate correctly. Perhaps not useful to most but helpful to those who rely on it for printing, and harmless.

If for whatever reason you wish to have no table of contents, simply set the configuration option noTOC to true.

1.3.4 Figures📝 Edit

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

The Table of Figures is not generated by default, but making it happen is straightforward: all you need to do is add a section with 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. Because the list has no depth, there is no equivalent to maxTocLevel.

And finally, automatic linking to figures works just as it does for sections, with <a href='#foo-figures'></a>. All of the above is demonstrated in the example.

1.3.5 Examples & Syntax Highlighting📝 Edit

Any pre or aside element that has the example class on it will get the additional example header and style. Content inside pre elements is syntax highlighted. The syntax highlighter does not need to be instructed about which language it is highlighting and will try to do a decent job of guessing.

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

1.3.6 Inclusions & Transformations📝 Edit

At times you need to include an external resource directly into your document. This may be because your specifications have additional boilerplate, or (like it's done in this very guide) because you want examples to be both inlined and accessed directly without having to make sure that they are always in sync.

Inclusion of external content in ReSpec is done using the data-include attribute. It is expected to point to a resource, using its relative path from the including document. The content will get included as a child of the element on which the inclusion is performed, replacing its existing content (unless data-include-replace is used, in which case it replaces the element).

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.

At times however one does not wish included content to be processed as if it were intended to be ReSpec content. For instance, content containing HTML may be an example that should not be processed (the examples in this document are included that way). In such cases, you can specify data-include-format='text'. This will include the content as if it were text, and therefore only process it as much as text is expected to be. The only recognized value are "text" and "markdown", nominally you can always set it to "html" but that's the default value.

There is an important caveat to take into account with the data-include functionality. ReSpec is designed so as to make life easier on editors. Because of that, people who do not wish to run a local web server and simply want to edit and refresh the specification they're working on from their local drives, using a file:// URI in the browser, are generally supported in doing so (this involves some trickery behind the scenes since it would normally make it impossible to load some of the content that ReSpec uses — but that's not something you should ever have to know). When using data-include, this is no longer possible. You either have to serve your ReSpec content from a web server or the included content will get blocked by the same-origin policy (which applies to all things file://). There is, unfortunately, no easy way to work around this. Be sure to note however that if you're not using data-include, you never have to worry about this. Though, we will still recommend you to spin-up a local http server to serve static files.

Finally, at times, you may wish to perform a quick and dirty transformation of some of your content included with data-include. You can use data-oninclude for that. The way in which it is done is that you include a globally available Javascript function that takes the ReSpec utils object as its first parameter, a string of the content to be transformed as its second, and a third parameter indicating the relative URL from which content was loaded; then returns the processed value. The value of data-transform is a white space separated list of JavaScript function names. They are applied left to right, as if they were a pipeline.

1.3.7 Common Inline Processing📝 Edit

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

RFC 2119📝 Edit

A very common construct in specifications is to use keywords defined in RFC 2119 which indicate precisely, using commonly agreed conventions, what requirements are placed on an implementation with what degree of strength (e.g., MUST, SHOULD NOT). All you need to do as an author is to include an all-caps MUST in your source and it will automatically get marked up as such (with the accompanying style applied to it afterwards).

Abbreviations & Acronyms📝 Edit

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

Inline Code📝 Edit

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

1.3.8 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=]

For common nouns, ReSpec can handle pluralization automatically:

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

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>

The following all link back to "banana":

<p>[=the best fruit=] or the [=yellow delicious=].</p>
Referencing terms from other specifications📝 Edit

Often, you need to link to terms defined in other specifications. ReSpec makes it quite simple with its cross referencing (xref) feature. In short, you specify a list of specifications ReSpec may search a term from, and simply reference the term. For example, to reference "default toJSON steps" from the WebIDL standard:

Example 5: Referencing definitions from other specifications.
<script>
  var respecConfig = {
    xref: ["WebIDL"],
  };
</script>
<a>default toJSON steps</a>
Shorthands📝 Edit

Frequently, you might also need to specify the type and context of the definition. Specifying all such metadata becomes clumsy quickly (something like <a data-link-type="some-type" data-link-for="some-context">term</a>). This is where ReSpec's shorthands come in picture. There are two important shorthands when it comes to linking to definitions: [= term =] for linking regular concepts, and {{ term }} for linking IDL stuff.

You don't need to remember when to use standard HTML <a> or the shorthands. Shorthand syntax works for referencing external terms as well as locally defined terms. A good compromise is to use shorthands all the time. Lets go through an example where we try to link to link to a few locally defined terms and some external definitions.

Example 6: 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.9 References📝 Edit

Specifications typically need to have references to other specifications on which they build to define their own technology. Managing references is a pain, as is linking to them every time that they are mentioned.

ReSpec takes the pain out of this with multiple features that are used together. First, when you need to refer to a given specification in the body of the text, simply do so using [[FOO]], where FOO is the referenced specification's ID. ReSpec uses the context of the reference to work out if the reference is normative or informative. That is, 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. ReSpec will replace those with the link the reference and the appropriate markup around it.

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

Example 7: Non-normative reference in a normative section
This is normative and MUST be followed. But, sometimes we need a non-normative
example reference [[?FOO]].

You can also link to a specification directly in text by using [[[FOO]]], where FOO is the specification's id. When ReSpec finds the specification in the references database, this gets converted to a link to the specification in the text i.e. <a href="link-to-FOO">FOO Spec Title</a>.

The difference between triple and double brackets syntax is that [[[FOO]]] links directly to the referenced specification, whereas [[FOO]] links to the entry in the "References" section (see below). Normative and informative references work similarly for [[[FOO]]] as they work for [[FOO]], and [[[?FOO]]] can be used to have a non-normative reference in a normative section.

If you ever want to use some text in double brackets that doesn't represent a reference, for example to represent an ECMAScript internal slot, write it as [[\InternalSlot]] (note the leading backslash).

Then, using all the collected references from the document, ReSpec will generate a “References” section with subsections for normative and informative references (when they appear). Naturally, it will also fill in the references themselves, including the relevant bibliographical data, using the conventional markup. (Assuming they appear in our records.).

References are loaded from a shared database that is maintained by a group of volunteers. If you need a reference that is not in the database, then the right thing to do is to submit it for inclusion so that others can benefit from it too. However, if that is not possible then you can make use of the localBiblio configuration option.

The only things you therefore need to know for references are the reference names of the specifications you wish to refer to (as well as to how to add your own to the database). The names are usually rather logical, and most of the time can be guessed. In other cases, you can go look for them in the central bibliographical database that is maintained at specref.org.

1.3.11 Custom Styling📝 Edit

If you wish to add your own additional styles to your document, just use the regular <link> and <style> elements. Be warned however that the W3C styles will always be added after yours, so if you wish to override them you will need to use more specific selectors.

1.4 Essential W3C Boilerplate📝 Edit

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

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

1.4.1 shortName📝 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

W3C documents are produced by groups of some sort: Working Groups (WG), Interest Groups (IG), the TAG, and Community or Business Groups (CG, BG). For simplicity, we will be referring to all of the above as "Working Groups", since one should not be required to understand the many subtleties of the W3C Process in order to write a good specification. Which group a spec belongs to is denoted by the group configuration option. A list of valid group names can be found at: https://respec.org/w3c/groups/.

When these groups release a document, they must include some information that is relevant and specific to them — all of this information is required. Documents produced in other situations (e.g., Submissions, unofficial drafts, etc.) don't require these options.

The result of changing these configuration options can be seen in the "Status of this Document" section.

1.4.3 Specification Status📝 Edit

At any given time a specification must be in a given status. The specStatus option indicates which status that is. Typically, a status has implications in terms of what other options may be required. For instance, a document that is intended to become a Recommendation eventually and that is not the First Public Working Draft (FPWD) of that specification will require previousPublishDate and previousMaturity to be specified.

Note

Note: The process of publishing specifications typically involves releasing multiple versions in a row that have specific dates (so that people can see the evolution, and also for IP reasons). Additionally, some specification statuses involve delimited review periods. These are all specified using date-related options. The format used for all dates is YYYY-MM-DD, except when only year is required, in which case it is a 4-digit number.

The specStatus section list all the possible status values.

1.4.4 Editor's Drafts📝 Edit

Most groups maintain some form of version control system which is exposed over the web so that people can keep track of what edits are being made to a specification in between official releases. It is often useful to point to such documents, including from released specifications, so that people wishing to report issues can make sure that they aren't already fixed, and in general get the very latest version. In fact, Editor Drafts (ED) are often considered to be the most useful reference to have to a group's work.

1.4.6 Copyrights & Patents📝 Edit

All the best fun in standards brought to you neatly packaged in a single section!

By default, W3C specifications all get the regular W3C copyright notice and archaic document license, except for unofficial documents which are under CC-BY. In some cases however, you will want to modify that.

For all document types other than "unofficial", you can use additionalCopyrightHolders to indicate that the copyright is shared not just amongst the W3C's hosts but also with other organizations (typically this is used for documents developed jointly with another SDO such as the IETF). For unofficial documents, this simply replaces the default CC-BY license.

If you wish the copyright date to span several years rather than just the year matching publishDate (e.g., 2009-2013) then you can use copyrightStart.

At times, the patent situation of a specification may warrant being documented beyond the usual boilerplate. In such cases, use addPatentNote. Its content will get injected at the end of the SotD section (right after the patent policy paragraph).

1.4.7 Note & Recommendation Tracks📝 Edit

If you are working on a new version of an existing Recommendation, then it is required that your document point to that previous version. This is done using the prevRecShortname and prevRecURI options, which respectively provide the shortName for the existing Recommendation (e.g., "SVG", as opposed to "SVG2") and its URL. If 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.

The process for the publication of Notes has been a source of confusion. When producing multiple drafts of a Note in succession, some groups have traditionally simply published them all as Notes one after the other, indicating in the abstract or SotD if they intend to work further on this document or if it is final. Since Notes are not normative and entail no IP concerns, they don't need an elaborate process and this process was perhaps not entirely bad. However, that's not how Notes are commonly handled nowadays.

The currently recommended process for Notes is closer to that which is used for Recommendation Track documents, typically: FPWD -> WD (n times) -> LC -> Note. Given that any group may decide at any time to release a Rec-Track document as a Note instead (often because it has been abandoned), this is Process-correct but it does involve jumping through hoops (notably for IP) that likely should not be needed. It has been explained to me several times why this switch took place, but I can never recall the justification. At any rate, if you are confused with the Note track process but wish to stick to it, you can do so by setting noRecTrack to true.

1.4.8 Best Practice Documents📝 Edit

Best practices may be shown, numbered, and formatted using a div with class practice containing a p > span.practicelab with the practice's title and a p.practicedesc with description of the practice.

This feature is rarely used, and likely needs to be updated. If you wish to use it in anger, please contact me and we can improve support for it.

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

If a section element with id bp-summary is present, then a summary list of best practices will be placed in it, linked to the best practices that have an id on the span element.

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

1.5 WebIDL Guide📝 Edit

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

Example 8: Declaring a WebIDL block.
<pre class="idl">
interface Request {
  readonly attribute ByteString method;
  readonly attribute USVString url;
};
</pre>

tl;dr - ideal linking setup📝 Edit

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

Example 9: 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>Define {{ExampleInterface/exampleMethod()}} here...</p>
  </section>
  <section>
    <h2><dfn>url</dfn> attribute</h2>
    <p>Define {{ExampleInterface/url}} attribute here...</p>
  </section>
</section>
<section>
  <h2>Here is how you link!</h2>
  <p>The {{ExampleInterface}} or the {{ExampleInterface/exampleMethod()}}.</p>
</section>

Defining the interface📝 Edit

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

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

The data-dfn-for attribute allows you to describe one or more aspects of an interface at once within a section of your document.

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

Example 11: 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 12: 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 13: 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>

2. Creating Static Snapshots📝 Edit

Of course the downside of the approach taken by ReSpec is that the specification as it is expected to be, with all its bells and whistles, exists only in your browser's memory as a DOM. Publishing directly with the script would not work as the source would not pass PubRules. Also, as ReSpec processes the document each time a page is visited, it might not feel efficient or quick enough (although ReSpec does a great job caching things for repeated visits).

The good news is that ReSpec allows you to export a "static snapshot" of the processed document. There is no bad news here.

2.1 Using Browser📝 Edit

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

2.2 Using Spec Generator service📝 Edit

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

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

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

That index.html file is a dump of the source.html file’s DOM, generated by processing the source with ReSpec — that is, exactly the same output you get by manually using Ctrl+Shift+Alt+S within the document itself and picking "Save as HTML (Source)" to save the output.

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

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

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

2.3 Using CLI📝 Edit

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

To install the CLI, run:

npm install --global respec

Then use the CLI to generate a snapshot as:

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

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

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

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

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

Note

If you already have Chrome installed on your computer, you can speed up the process by not installing a new copy of Chrome on each install. To do so, add following two environment variables before installing or running above steps:

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

For more options, run respec --help.

3. Shorthands Cheat Sheet📝 Edit

Similar to markdown, shorthands are custom ways of writing things that 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 elements [^element^] [^iframe^]
HTML 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 to edit both ReSpec and BikeShed specifications at the same time.

3.1 WebIDL📝 Edit

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

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

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

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

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

See xref for more information.

Plural Forms📝 Edit

ReSpec supports automatically linking to plural forms. 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 15: 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 16: 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 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!)

4. Using Markdown with ReSpec📝 Edit

You can use markdown to write ReSpec based documents. To enable markdown globally, set respecConfig.format to "markdown". Markdown can also be enabled section by section using data-format="markdown".

The markdown is interpreted as GFM and you can mix HTML and markdown.

Now, we describe some of the ReSpec specific markdown behaviors and extensions.

Headings📝 Edit

When using markdown, you don't need to add <section> elements manually. Each heading automatically creates a structure of nested section elements around it. For example:

Example 17: Markdown headings and automatic section structure generation.
## Heading

Here's some text.

### Sub heading

More text.

will be transformed into:

<section>
  <h2>Heading</h2>
  <p>Here's some text.</p>
  <section>
    <h3>Sub heading</h3>
    <p>More text.</p>
  </section>
</section>

Custom Heading IDs📝 Edit

By default, ReSpec uses heading's text content to generate IDs for you. The IDs are mostly stable, i.e., we make sure updates to ReSpec do not change the IDs). Sometimes, you might want to add a different (perhaps shorter) ID. You can provide a custom heading ID as:

Example 18: Specifying a custom ID for a heading.
## I'm a heading {#custom-heading-id}

Code blocks📝 Edit

You can use triple-backticks to create code-blocks (<pre> elements). Syntax highlighting for various languages, including an advanced syntax highlighter for WebIDL is available out of the box.

Lets go through a few examples!

Example 19: A simple code-block.
```
// ReSpec will try its best to guess the language for syntax highlighting.
console.log("hey!");
```
Example 20: A simple code-block with language hint.
```js
// ReSpec will use the provided language hint for syntax highlighting.
// It's nice to be explicit.
console.log("hey!");
```
Example 21: A WebIDL block.
```webidl
[Exposed=Window]
interface Paint { };
```
Example 22: A pre.example.
```js "example": "I'm example title"
console.log(navigator.myAPI.rocks()); // of course
```

above is equivalent to writing:

<pre class="example js" title="I'm example title">
console.log(navigator.myAPI.rocks()); // of course
</pre>

HTML and Markdown📝 Edit

Please remember that markdown requires double newlines between an HTML tag and markdown text.

Example 23: Mixing HTML and markdown.
<aside class="note">

## Markdown inside HTML tags

This is the correct way to insert markdown inside HTML.

</aside>

5. Configuration Options

5.1 a11y📝 Edit

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

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 24: Run all default rules
var respecConfig = {
  a11y: true,
};

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

Example 25: Run only a specific rules
var respecConfig = {
  a11y: {
    runOnly: ["image-alt", "link-name"],
  },
};

Another example:

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

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

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.

5.3 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 28: 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.4 caniuse📝 Edit

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

Example 29: Caniuse table for payment-request
var respecConfig = {
  caniuse: "payment-request",
};
Example 30: 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 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
(For testing) 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.5 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 31: Add Editor's Draft URL
var respecConfig = {
  specStatus: "ED",
  edDraftURI: "https://www.w3.org/TR/example",
};

5.6 editors📝 Edit

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

Example 32: 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.7 format📝 Edit

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

markdown
Interpreted as GitHub flavored markdown (GFM).
Example 33: Interpret content as Markdown
var respecConfig = {
  format: "markdown",
};

See: Using Markdown with ReSpec Guide.

5.8 formerEditors📝 Edit

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

Example 34: 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.9 github📝 Edit

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

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

This automatically generates:

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

This is normally what you want:

Example 35: Set GitHub repository
var respecConfig = {
  github: "w3c/browser-payment-api",
};
Example 36: 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 37: 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.10 highlightVars📝 Edit

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

Example 38: Enable variable highlighting
var respecConfig = {
  highlightVars: true,
};

It renders as:

ReSpec highlightVars demo
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.11 isPreview📝 Edit

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

This adds a big red ugly box to your document.

Example 39: Add a 'preview' warning
var respecConfig = {
  isPreview: true,
};

5.12 license📝 Edit

license can be one of the following:

cc-by
Experimentally available in some groups (but likely to be phased out).
Note that this is a dual licensing regime.
cc0
An extremely permissive license.
It is only recommended if you are working on a document that is intended to be pushed to the WHATWG.
w3c-software
A permissive and attributions license (but GPL-compatible).
w3c-software-doc
The W3C Software and Document License.
This is default for the W3C profile.

5.13 lint📝 Edit

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

If you want to turn off the linter:

Example 40: Disable linter.
var respecConfig = {
  lint: false,
};

You can also enable or disable certain rules:

Example 41: 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.13.1 no-http-props📝 Edit

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

For example:

Example 42: 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 43: Enable no-http-props linter rule.
var respecConfig = {
  lint: {
    "no-http-props": true,
  },
};
example warning for no-http-props

5.13.2 local-refs-exist📝 Edit

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

For example:

Example 44: 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 45: Enable local-refs-exist linter rule.
var respecConfig = {
  lint: {
    "local-refs-exist": true,
  },
};
example warning for local-refs-exist

5.13.3 no-headingless-sections📝 Edit

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

For example:

Example 46: 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 47: Enable no-headingless-sections linter rule.
var respecConfig = {
  lint: {
    "no-headingless-sections": true,
  },
};
example warning for no-headingless-sectionsdeveloper console with warning for no-headingless-sections

5.13.4 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 48: 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 49: 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 50: 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.13.5 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 51: 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 52: Enable check-punctuation linter rule.
var respecConfig = {
  lint: {
    "check-punctuation": true,
  },
};

5.13.6 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 53: Disable privsec-section linter rule.
var respecConfig = {
  lint: {
    "privsec-section": false,
  },
};

5.13.7 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 54: 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 55: 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.14 localBiblio📝 Edit

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

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

Note

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

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

5.15 logos📝 Edit

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

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

src
URL to the source.
alt
The alt attribute value.
height
The height of the image.
width
The width of the image.
id
The id of the image element.
url
Where to navigate to when the logo is pressed.
Example 57: 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.16 maxTocLevel📝 Edit

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

Example 58: Set maximum ToC depth to 2 (i.e., skip §1.1.1).
var respecConfig = {
  maxTocLevel: 2,
};

5.17 mdn📝 Edit

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

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

Example 59: 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 60: 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",

5.18 modificationDate📝 Edit

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

Example 61: Add a modification date for an already published document.
var respecConfig = {
  publishDate: "2020-03-30",
  modificationDate: "2020-04-13",
};

5.19 noTOC📝 Edit

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

Example 62: Do not generate a Table of Contents.
var respecConfig = {
  noTOC: true,
};

There is a corresponding class of notoc.

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 64: 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 65: 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 66: Skip automatic pluralization per <dfn>.
<dfn data-lt-no-plural>html</dfn>

5.22 postProcess📝 Edit

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

Note

Note: We strongly discourage the use of jQuery. We are trying to eliminate it from ReSpec and encourage people to stop using it entirely. In modern browsers, jQuery is no longer a necessary for cross-browser interoperability. Additionally, modern DOM APIs are now good enough that jQuery should not be needed for manipulating or traversing DOM Nodes.

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

Example 67: Run two functions in order after processing.
function doThing(config, document){...}
function doOtherThing(config, document){...}

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

5.23 preProcess📝 Edit

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

Note

Note: We strongly discourage the use of jQuery. We are trying to eliminate it from ReSpec and encourage people to stop using it entirely. In modern browsers, jQuery is no longer a necessary for cross-browser interoperability. Additionally, modern DOM APIs are now good enough that jQuery should not be needed for manipulating or traversing DOM Nodes.

Example 68: 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 69: 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 70: Set 'awesome-api' as specification's short name.
var respecConfig = {
  shortName: "awesome-api",
};

5.26 specStatus📝 Edit

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

Value Meaning Must also include
base 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.
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.
unofficial An unofficial draft. Use this if you're producing a document outside of W3C but want 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).
ED Editor's Draft. Use this for documents that are maintained in the group's own repository.
  • edDraftURI.
  • You can skip the "Latest Published Version" link by using latestVersion: null (See #2968 for details).
FPWD First Public Working Draft. None.
WD Working Draft.
LC Last Call Working Draft.
LD Living Document.
LS Living Standard.
CR Candidate Recommendation.
PR Proposed Recommendation.
PER Proposed Edited Recommendation.
REC Recommendation.
RSCND Rescinded Recommendation.
FPWD-NOTE First Public Working Draft of a Note. None.
WG-NOTE Working 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.
IG-NOTE Interest Group Note.
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.
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.
finding TAG Finding. Same as above, but final. None.
Example 71: Set specification's status to 'unofficial'.
var respecConfig = {
  specStatus: "unofficial",
};

5.27 subjectPrefix📝 Edit

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

Example 72: 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 73: 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 74: 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 tocIntroductory📝 Edit

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

Example 75: Show introductory sections in Table of Contents.
var respecConfig = {
  tocIntroductory: true,
};

5.31 xref📝 Edit

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

xref can be configured as:

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

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

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

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

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

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 76: Enable xref.
var respecConfig = {
  xref: true,
};
Example 77: Search term in specs under 'web-platform' profile.
var respecConfig = {
  xref: "web-platform",
};
Example 78: 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 79: 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.

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

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 83: 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 84: 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.

The following appears as "Copyright © 1977-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 86: 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 87: 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:

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

6.9 errata📝 Edit

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

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

6.10 group📝 Edit

group is a shorthand configuration option for specifying wg, wgId, wgURI, wgPatentURI, and wgPatentPolicy options. It fetches working group details using the W3C API.

Example 89: Use Web Payments Working Group.
var respecConfig = {
  group: "payment",
  // is equivalent to:
  // wg: "Web Payments Working Group",
  // wgId: 83744,
  // wgPatentURI: "https://www.w3.org/2004/01/pp-impl/83744/status",
  // wgURI: "https://www.w3.org/Payments/WG/",
  // wgPatentPolicy: "PP2020", (or whatever the WG is using!)
};

You can also specify multiple groups:

Example 90: 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 91: Specify group type.
var respecConfig = {
  group: "wg/wot",
};

A list of valid group names can be found at: https://respec.org/w3c/groups/.

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 92: Add URL of the implementation report.
var respecConfig = {
  implementationReportURI: "https://example.com/imp-report/",
};

6.12 lcEnd📝 Edit

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

Example 93: Set Last Call review end date to January 3, 2016.
var respecConfig = {
  specStatus: "LC",
  lcEnd: "2016-01-03",
};

6.13 level📝 Edit

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

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 94: Set the current specification to level 2.
var respecConfig = {
  level: 2,
  shortName: "payment-request",
};

Which results in:

Which would render as, for example:

Screenshot 2020-02-21 18 54 02

6.14 noRecTrack📝 Edit

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

Example 95: Mark current spec not intended for Recommendation track.
var respecConfig = {
  noRecTrack: true,
};

6.15 prevED📝 Edit

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

Example 96: Specify URL to previous editor's draft.
var respecConfig = {
  prevED: "https://example.com/old/ed",
};

6.16 previousDiffURI📝 Edit

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

Example 97: 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.17 previousMaturity📝 Edit

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

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

Example 98: Set Last Call (LC) as document's previous maturity level.
var respecConfig = {
  previousPublishDate: "2014-05-01",
  previousMaturity: "LC",
};

6.18 previousPublishDate📝 Edit

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

Example 99: Set previous publish date to May 1, 2014.
var respecConfig = {
  previousPublishDate: "2014-05-01",
  previousMaturity: "LC",
};

6.19 prevRecShortname📝 Edit

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

Example 100: Set shortName for previous version of recommendation.
var respecConfig = {
  shortName: "fancy-feature-l2",
  prevRecShortname: "fancy-feature",
};

6.20 prevRecURI📝 Edit

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

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

Example 101: Set URL of previous version of Recommendation.
var respecConfig = {
  prevRecURI: "https://www.w3.org/TR/2014/example-20140327/",
};

6.21 submissionCommentNumber📝 Edit

Allows W3C staff to link to a comment number.

Which shows up as:

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

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

Usage example📝 Edit

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

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

6.23 wgPublicList📝 Edit

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

Example 103: Specify short name of public mailing for spec's group.
var respecConfig = {
  wgPublicList: "public-device-apis",
};

7. Special <section> IDs

7.1 conformance📝 Edit

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

As well as sections marked as non-normative, all authoring guidelines, diagrams, examples, and notes in this specification are non-normative. Everything else in this specification is normative.

The key words MAY, MUST, MUST NOT, NOT RECOMMENDED, RECOMMENDED, SHOULD, and SHOULD NOT are to be interpreted as described in [RFC2119].

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

This section is required for specifications that contain normative material.

Example 104: Add the RFC2119 conformance boilerplate, along with custom content.
<section id="conformance">
  <!-- boilerplate will be added here -->
  <p>The specification specific conformance text…</p>
</section>

7.2 gh-contributors📝 Edit

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

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

Example 106: Show names of contributors separated by commas.
<p>
  We'd also like to thank the following contributors: <span id=
  "gh-contributors"><!-- filled by ReSpec --></span>.
</p>

7.3 idl-index📝 Edit

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

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

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

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

Example 108: IDL index with custom header and content.
<section id="idl-index" class="appendix">
  <h2>The Whole API!</h2>
  <p>This is what the whole thing looks like!</p>
  <!-- All the Web IDL will magically appear here -->
</section>

7.4 index📝 Edit

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

Example 109: Index of locally defined and externally referenced terms.
<section id="index" class="appendix">
  <!-- All the terms will magically appear here -->
</section>

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

Example 110: Terms index with custom header and content.
<section id="idl-index" class="appendix">
  <h2>List All The Terms!</h2>
  <p>Wow, that's a lot of terms!</p>
  <!-- All the terms will magically appear here -->
</section>

7.5 issue-summary📝 Edit

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

Example 111: List of GitHub issues referenced in current document.
<div class="issue" data-number="123" title="This is issue!">
  <p>It clear that this is an issue.</p>
</div>
<section class="appendix" id="issue-summary">
  <!-- A list of issues will magically appear here -->
</section>

7.6 references📝 Edit

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

Example 112: List of normative and non-normative citations.
<section id="references">
  <p>Citations are great!</p>
  <!-- normative and informative references will appear below -->
</section>

7.7 tof📝 Edit

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

Example 113: Table of Figures
<section>
  ...
  <figure id="flowchart">
    <img src="flowchart.svg" alt="" />
    <figcaption>The water flows from bucket A to bucket B.</figcaption>
  </figure>
  ...
</section>

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

8. Special element behaviour

8.1 <figure>📝 Edit

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

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

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

You can also automatically generate a table of figures.

8.2 <h1 id="title">📝 Edit

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

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

Example 115: Using h1 as specification title.
<body>
  <h1 id="title">The <code>Whatever</code> Interface</h1>
  <section id="abstract">
    <p>...</p>
  </section>
</body>

8.3 <pre>/<code>📝 Edit

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

Example 116: A code block with HTML syntax highlighting.
<pre> <!-- or <pre class="html"> -->
<script>
function magic() {
  const noop = "this";
  doThat(noop);
}
</script>
</pre>

Respec supports the following languages by default:

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

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

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

8.4 <section>📝 Edit

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

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

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

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

Example 118: A section.
<section>
  <h2>The <code>foo</code> Element</h2>
  <p>The <code>foo</code> Element allows you too...</p>
</section>

8.5 <title>📝 Edit

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

Example 119: Specify a title for current document.
<!DOCTYPE html>
<html>
  <title>The Super Duper Spec</title>
  <body>
    <!-- The title will magically be placed here with other useful stuff -->
    <section id="abstract"></section>
  </body>
</html>

9. 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 120: 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 121: 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>

Would be emitted as:

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

9.3 example📝 Edit

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

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

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

Example 122: 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 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 123: 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.5 introductory📝 Edit

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

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

Example 124: Mark a section as introductory material.
<section class="introductory">
  <p>This document can be folded into a paper airplane.</p>
</section>

9.6 issue📝 Edit

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

Example 125: 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.8 nohighlight📝 Edit

Indicates that a code block should not be syntax highlighted.

This block will not be syntax highlighted:

Example 127: Disable syntax highlighting.
<pre class="nohighlight">
function foo(){
  const a = "foo!";
}
</pre>

But this one will be syntax-highlighted by default:

Example 128: All pre elements are syntax highlighted by default.
<pre>
function foo(){
  const a = "foo!";
}
</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 130: 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>

Would be exported as:

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

9.11 notoc📝 Edit

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

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

Example 132: 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 133: 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 134: Remove some content before export.
<div class="removeOnSave">
  <p>This will be removed at export time.</p>
</div>

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.

You can also set the abbreviation by yourself.

10.2 data-cite📝 Edit

Note

Note: this feature is mostly deprecated, and only supported for legacy specifications. Please use xref instead.

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 137: 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 138: 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 Shepherd database.

Note

Note: Only export things that other specifications might use (e.g., specific algorithms).

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

Note

Note: WebIDL things are automatically exported for you.

Example 139: 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 140: 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 141: 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 runs recursively so that included content that contains data-include attributes will work (just be sure not to build a circular loop in there, ReSpec won't detect it if only because it doesn't mind if you're shooting yourself in the foot).

By default the inclusion is asynchronous, which means that the included content may or may not be further processed by ReSpec after it gets added to the DOM (the result won't be deterministic and so is only useful if the content is not meant to be further processed).

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 142: 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 143: 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 144: 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.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:

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

Example 148: 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 149: 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 150: 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 151: 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 152: 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 153: 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 154: 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:

Each function must return the transformed content.

Example 155: 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 156: 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 157: 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.

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 159: 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 160: Set document language to French.
<!DOCTYPE html>
<html lang="fr"></html>

11. Custom Elements

11.1 <rs-changelog>📝 Edit

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

Attributes📝 Edit

  • from: a commit hash or git tag, from when (inclusive).
  • to: optional, a commit hash or git tag until when (inclusive). If omitted, it just does to the latest commit.
  • filter: the name of a JS function to call, which allows you to filter out commits.

Filtering📝 Edit

The filter function takes one argument, which is a commit object. The object is composed of two properties:

  • hash - the abbreviated commit hash.
  • message - the headline of the commit message.
Filtering example📝 Edit
function respecChangelogFilter(commit) {
  // commit.hash = commit hash
  // commit.message = commit message headline
  // Return `true` if commit is to be shown, false otherwise.
  return !commit.message.startsWith("chore");
}

Usage examples📝 Edit

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

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

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

Screenshot📝 Edit

image

12. Deprecated Options

12.1 processVersion📝 Edit

Warning: processVersion was removed from v19.5.0 onwards.

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

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

12.2 wg📝 Edit

Warning: This is deprecated. Use the group option instead.

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

12.3 wgId📝 Edit

Warning: This is deprecated. Use the group option instead.

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

Example 161: Specify W3C group ID.
var respecConfig = {
  wgId: 107714,
};

12.4 wgPatentURI📝 Edit

Warning: This is deprecated. Use the group option instead.

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

Note

Note: it is extremely easy to cut and paste this value from somewhere else and to fail to notice that you are using the wrong value. Given the legal patent implications in pointing to the wrong resource, please triple-check that you are using the link relevant to your group: locate your group, and click on its "(Status)" link.

12.5 wgURI📝 Edit

Warning: This is deprecated. Use the group option instead.

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

A. ReSpec Ecosystem📝 Edit

B. Person📝 Edit

A person object (used for editors, authors) contains the following fields (most of the fields are straightforward). Only the name field is required.

name
Name of the person
mailto
email address (turned into a mailto URL by respec)
url
home page of the author
company
company name
companyURL
url of the company
w3cid
identifier of the persons’ W3C account, if applicable. (This id can be found through the “my profile” URL that will be redirected to the user’s page; the id appears in the address bar).
orcid
identifier or full URL of the persons' ORCID account.
retiredDate
indicates the date in which an editor has retired from editing a specification. The format is yyyy-mm-dd. Additionally, if a person object is under editors and contains retiredDate, it will be automatically moved to formerEditors.
note
any text in this field will appear at the end of the person’s identification in parenthesis
extras
refers to an array of extras (see below) objects, displayed at the end of the person's identification

The “extras” are objects, each rendered as a separate span element, with the following fields:

name
the content of the resulting span; this can contain html elements
class
a value of the class attribute added to the enclosing span (can be used for styling)
href
if set, the content within the enclosing span is turned into an active link pointing to the value of href

A simple example:

Example 162: A simple person object.
{
    name:       "Benjamin Young",
    company:    "John Wiley & Sons, Inc.",
    companyURL: "https://www.wiley.com/",
    mailto:     "byoung@bigbluehat.com",
    w3cid:      65468
}

A more complex example, using the extras field to include a reference to the person’s ORCID id (with a logo):

Example 163: A more complex person object.
{
  name: "Ben De Meester",
  mailto: "ben.demeester@ugent.be",
  company: "Ghent University - iMinds - Data Science Lab",
  companyURL: "https://www.iminds.be/",
  url: "https://users.ugent.be/~bjdmeest/",
  retiredDate: "2020-03-26",
  orcid: "0000-0003-0248-0987",
  w3cid: "73403"
};

C. Common Errors📝 Edit

This page lists some common ReSpec errors and their mitigation.

Couldn't match TERM to anything in the document or in any other document cited in this specification📝 Edit

Screenshot of a ReSpec definition linking error

To fix this issue, follow these steps:

Is the term defined in some other document/specification?

  1. Search for the term using XRef Search UI. If the term is found:
    1. If the error message above does not contain the specification where term is defined, add the specification shortname to xref's specs.
    2. Otherwise, the error is due to an invalid for-context (i.e., term is defined in-context of some other term) or type-context (like referencing an exception using syntax meant for referencing concepts). Copy-paste the "How to Cite" of the relevant match from XRef Search UI.
  2. If the term is not found:
    1. Try searching for similar terms. The term might not be defined exactly. Use the shorthands syntax to alias the term in prose if needed.
    2. Check if the term is exported from the other spec, i.e., the <dfn> should have a data-export attribute.
      1. If the term is not exported, ask the specification editors to export it. Feel free to ping ReSpec maintainers if you need help.
      2. If the term is exported but not found through XRef Search UI, then the specification might not be in our database. Please file an issue at ReSpec repository or contact ReSpec maintainers by other means.
        1. Note: Terms from ECMA/IETF specifications are not presently available in the terms database. Use the data-cite attribute to reference those terms.

Is the term defined in same document?

  1. If it's a WebIDL term:
    1. Remember that WebIDL terms are case-sensitive.
    2. Use the WebIDL linking syntax.
    3. Provide proper for-context using either WebIDL linking syntax or data-link-for.
  2. If it's not a WebIDL term (i.e., it's a "concept"):
    1. Use the Concepts linking syntax
    2. Provide proper for-context using either Concepts linking syntax or data-link-for.

D. Editing this document

This document is generated directly from the content of the ReSpec project wiki on GitHub. Thus, it can be edited in two ways:

  1. The src.html for this document provides the structure. The src.html is available in the respec.org repository.
  2. The ReSpec project wiki. In addition, hovering over a section heading provides a link to directly edit the relevant page in the wiki.