ReSpec is a tool that makes writing specifications easier. Specifications tend to follow all manners of formalism, and in some cases will follow a strict set of conventions (e.g. W3C's "PubRules"). As an editor, you focus on actual features and correctness, ReSpec handle the likes of styling, referential integrity, bibliographical data, and a whole set of other dragons.

This chapter lists all the items (JS configuration, elements, attributes, classes) that can form the ReSpec language.

Configuration Options


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


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 SDOs such as the IETF. The option is simply some text giving the addition copyright holders. For unofficial documents, this string is used to replace the default CC licence. Example for regular documents and example for unofficial documents.


An array of objects, each of which has two required fields: uri, for the link to the alternate document, and 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).


An array of objects describing the authors of the document. See editors for details on the objects.


For IG-NOTEs, this must be specified. It is the URL of IP disclosure as per the IG's charter.


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. See an example.


A YYYY-MM-DD date. Documents that are in Candidate Recommendation (specStatus is "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 REC) so that implementers know how long they have. Use this to provide that date.


If you want to produce a diffmarked version of your specification, you can use this setting to point to a specific diff tool. It should expect to receive parameters called oldfile, newcontent, and base. By default it is set to


A setting indicating what version of RDFa to use when annotating the specification with semantic information that is compatible with RDFa Processors as used in the major search engines. Legal values are "1.0" to generate RDFa 1.0-compatible semantic markup, "1.1" to generate RDFa 1.1-compatible semantic markup, and false to indicate that no RDFa information should be included at all. Defaults to "1.1".

The values "1.0" and "1.1" must be included in quotation marks. Also, the value "1.0" should not be used in new specifications - it is only supported for legacy reasons.


The URI of the Editor's Draft, used in the header. This is required for specStatus = "ED". Any good old URL will do the trick.


An array of objects describing the editors of the document (in order). Each object must follow the structure below:

The name of the person. This field is required (and the only required one).
The URL for the person, can be used to point to the person's personal site.
The company for which the person is working.
The URL for the above company.
An email with which to contact the person.
Additional information on the person, often used to indicate a former employer (if the person switched companies during edition) or to clarify that an editor is no longer active even if her name is still attached to the document out of respect for her past contributions.
Numeric id of the editor profile in W3C (W3C account holders can find their id by visiting their W3C profile); it is used by the W3C publication system to associate specifications with their editors.
Array of objects consisting of the name, href, and class entries. The generated content is a sequence of elements the form <span class="class><a href=" href">name</a></span> added to the end of the person's entry. Can be used to add, e.g., the twitter account, ORCID ID, etc., of the person.


An URL providing a link to a document capturing errata for the specification.


Deprecated. An array of links to additional style sheets to include. This is one of the very few configuration options that is not backwards-compatible with v1 as support for it was completely removed (because almost everyone used it wrong, and it was not very useful).

format (markdown)

ReSpec writing specifications using GitHub flavored markdown.. Simply set the format option to "markdown".

var respecConfig = {
format: "markdown",

And now you can use a mix of HTML and markdown:

## Using markdown
<pre class="example" title="A markdown example">
function thisIsNice(){

// And using markdown is pretty sweet!
const foo = "FOO";

ReSpec will do its best to correctly format the markdown. Please remember that markdown is supposed to be placed flush against the left margin - but we do support it in sections

See also: nolink class to disable automatic linking in code blocks, if needed.


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


An option that tells the system to add a 'permalink' to each non-introductory section of your document assuming the section or heading element has an explicit ID. The permalink will show as an indicator on the same line as the section heading, by default immediately after the heading text. Options include:

The character(s) to use for the permalink indicator. The default symbol is '§'.
Setting this to true tells the system to place the permalink indicator on the right edge of the page. The default is to put the indicator immediately after the heading text.
Setting this to true tells the system to hide the permalink symbol unless the heading is being hovered over. The default is to show the symbol at all times.

Finally, if you do not want a section to have a permlink indicator, a class of "nolink" on that heading will exclude it.


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


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.

Its value is an object that has the reference names as its keys and specific objects describing the references as its values. Keys include authors (an array of names), href (a link to the reference), title (the reference's name), status (its maturity as a standard), and publisher (the organisation publishing it). Only title is required.

    localBiblio:  {
        "WEREWOLF": {
            title:    "Tremble Puny Villagers"
        ,   href:     ""
        ,   authors:  [
                "Dominique Hazael-Massieux"
            ,   "Doug the Simple Villager"
        ,   status:   "RSCND"
        ,   publisher:  "W3C"


logos gives you the ability to override 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 at least a `src` or an `alt` property, along with optional `height`, `width`, `id`, and `url` properties that can be used to further customize the included logo.

The above makes more sense when seen in an example:

logos: [
      src: '',
      href: "",
      alt: "",
      width: 100,
      height: 42,
      id: 'something'

This causes the standard logo to replaced with

  <a href="">
    <span id="something">
      <img src="" width='100' height='42' alt='' />


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.


A boolean indicating that automatically generated legacy DOM-style sections (Attributes and Methods) following the WebIDL blocks are removed. Setting this boolean true brings the document style closer to that of used by Anolis. If you are migrating a document that uses the legacy DOM-style, you need to manually move the prose from Attributes and Methods sections and put it below the IDL markup definition into its own paragraph(s). Additionally, you need to link the IDL members back to the prose; ReSpec automatically generates fragment identifiers that start with #widl-, and you must manually add corresponding ids to appropriate parts in your prose.


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


When set to true, no table of contents is generated.


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

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

The above makes more sense when seen in an example:

otherLinks: [{
    key: "Version history:",
    data: [{
      value: "Commit History.",
      href: ""
 }, {
      value: "Github commits on Twitter.",
      href: ""


Version Histroy:
Commit History.
Github commits on Twitter:
Github commits on Twitter.


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.


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


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


When producing a diffmarked 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.


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


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.


Not normally required, as this is typically defaulted properly for you. However, if the previous version of a document happened not to live on the W3C site (or not at a regular location) then you can set this.


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 "2014" process. You can override this by setting the processVersion configuration option to anything other than "2014". The previous process document, for example, was "2005".


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 timezones (that are not always well accounted-for by servers or browsers) cause the day to shift by one.


The text of a note to include at the beginning of the References section.


The specification's "short name", which is the name used in W3C URLs such as "" (and several other generated URLs).


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
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. Example
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. Example
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 licences the content under CC-BY v3.0. If you want a different copyright, you will need to set the various copyright configuration options. Example
ED Editor's Draft. Use this for documents that are maintained in the group's own repository. Requires edDraftURI to be specified. This is the default value. Example
FPWD First Public Working Draft. Example
WD Working Draft. Requires previousPublishDate and previousMaturity. Example
LC Last Call Working Draft. Requires previousPublishDate, previousMaturity, and lcEnd. Example
CR Candidate Recommendation. Requires previousPublishDate, previousMaturity, and crEnd. Example
PR Proposed Recommendation. Requires previousPublishDate and previousMaturity. Example
PER Proposed Edited Recommendation. Requires previousPublishDate and previousMaturity. Example
REC Recommendation. Requires previousPublishDate and previousMaturity. Example
RSCND Rescinded Recommendation. Requires previousPublishDate and previousMaturity. I wish there were more of those. The style is so edgy. Example
NOTE Deprecated. A note. It is unclear to me how this differs from the more specific WG-NOTE and friends. Do not use this. Example
FPWD-NOTE First Public Working Draft of a Note (of any kind, it would seem). Example
WG-NOTE Working Group Note. Example
BG-DRAFT, BG-FINAL Business Group Draft or Final Report. Example Draft Report
CG-DRAFT, CG-FINAL Community Group Draft or Final Report. Example Draft Report
IG-NOTE Interest Group Note. For this, charterDisclosureURI is required. Example
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. Example
Team-SUBM Team Submission. Example
XGR Deprecated. Incubator Group Report. Requires xgrGroupShortName and xgrDocShortName. Example
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 don'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 "", that the latest version is at "", and that the dated versions are at "shortName-YYYYMMDD". Example
finding TAG Finding. Same as above, but final. Example


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.


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


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


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


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


The URL of the public list of patent disclosures for the group, e.g. "".

PLEASE 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. In order to find your group's link, go to, locate your group, and click on its "(Status)" link.


The short name of the mailing list on which the group conducts its public discussion. E.g. "public-device-apis".


The URI to the public page of the group. E.g. "".


Deprecated. The short name of the group report, e.g. "mbui". Since XGs typically produce a single report, it is typical to use the same short name for the report as is used for the group, therefore this option defaults to xgrGroupShortName.


Deprecated. The short name of the group, as included in its URI, e.g. "model-based-ui". This is required for XGs.



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

A Table of Figures is generated and inserted in the document if you include an element with ID tof.

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


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

Special sections

Some sections with specific IDs have special meanings.

Required. The specification's abstract, which should contain a paragraph. You shouldn't include the "Abstract" title.
If present, its content will be set to a summary of the list of best practices described in the document.
Specifications often have "Conformance Requirements", which are made of free-form text and some boilerplate mentioning RFC 2119. A section with this ID will add the title and the boilerplate, while keeping the content you include in it. The added paragraphs are essentially boilerplate but are useful in clarifying the normative status of specific sections and listing the RFC 2119 keywords that are normally used for testable assertions in the specification. The part that you write is dedicated to providing more information about how conformance works for your given specification, it is often used to define product conformance classes. If testable assertions and conformance classes sound like gibberish to you, it is highly recommended that you read In fact, even if you understand what those are but haven't read this document, go read it.
Required. The "Status of this Document" section. Obviously, you do not need to include the endless reams of boilerplate that that section normally contains: that's generated for you. However, the PubRules require that part of that boilerplate be "a custom paragraph". The content you include in this section is therefore injected as that custom paragraph (you can have several, in fact any markup you want is used). Don't spend too much time putting together the best of your prose for this, it is almost certain that no one will ever read it.


The title element is left untouched, but its content is used to also set the h1 title for the specification.



Data is normally included as HTML (injected into the DOM as such) but there are time when you want to include content as text. If so, set this attribute to text. That is the only supported value (you can also use html, but that's the default behaviour).


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


Inclusion is normally asynchronous, which means that the content may or may not get further processed by ReSpec depending on the point at which it gets inserted (which isn't deterministic). If you need to ensure that content gets injected before the rest of the pipeline runs, set this to any truthy value.

Be warned that there is a steep performance penalty in doing so, since all ReSpec processing will effectively pause until the content has been fully fetched and inserted.


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). If you wish to ensure that ReSpec processing is applied to the content, use data-include-sync

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.


This is a list of white space separated WebIDL identifiers that you wish to have merged into the current WebIDL section, so as to have them all described together rather than as separate sections. This is typically used to bring the definition for one or more dictionaries into the same section as an interface.


Can be used in conjunction with the configuration option issueBase and with a paragraph with class value 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:/ would include, for example:

   <p class="issue" data-number="1">Change the terminology to "Portable Web Publication"<\p>

If the configuration of the file includes issueBase:"https:/", then the paragraph will be automatically entitled "ISSUE 1", with a link to the corresponding Github issue.


Behaves in the same way as data-transform, applied to the included content. The functions receive a third parameter giving the URL of the loaded content.


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 the ReSpec utils object and a string of the content to transform.

Each function must return the transformed content.


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


ReSpec defaults the lang attribute on your root element to en. If you are writing in another language, simply set this attribute to another value.



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.


Marks the contents of an element as a "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").

A block example:

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

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>

If the element is an 'inline' element (e.g., span) then the element is left as is and any title attribute does not effect the appearance of the note.

An inline example:

<p>Sometimes, when you are looking at an URL
<span class="note" title="Should this be 'an'?">I pronounce this
as 'earl', so 'An Earl' feels right.  But if I said the letters it is
'you are ell', so 'A You Are Ell' would be better.  Help?<span>
note that the 'scheme' helps understand the rest of the syntax.<p>

Would be emitted as:

<p>Sometimes, when you are looking at an URL
<span class="ednote" title="Should this be 'an'?">I pronounce this
as 'earl', so 'An Earl' feels right.  But if I said the letters it is
'you are ell', so 'A You Are Ell' would be better.  Help?<span>
note that the 'scheme' helps understand the rest of the syntax.<p>

In other words, the title attribute is ignored when the containing element is "inline".


Marks a pre or aside as being an example. This provides it with a specific styling and header.


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


When set on a section 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.


Indicates that a code block should not be syntax highlighted.


When using markdown, you can disable automatic linking within code blocks.

URLs are linked by default:


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

A block example:

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

Would be emitted 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>

An inline example:

<p>This is really important: 
<span class="note" title="PAY ATTENTION!">Try to imagine all
life as you know it stopping instantaneously and every molecule
in your body exploding at the speed of light<span> 
Don't cross the streams!<p>

Would be emitted as:

<p>This is really important: 
<span class="note" title="PAY ATTENTION!">Try to imagine all
life as you know it stopping instantaneously and every molecule           
in your body exploding at the speed of light<span>                       
Don't cross the streams!<p>

In other words, the title attribute is ignored when the containing element is "inline".


A div containing a best practice description.


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


A span containing the title of a best practice, inside a practice description.


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.

Getting Support

The source code for ReSpec is maintained in its GitHub repository. Feel free to fork and improve it! If you find a bug, you can consult the list of known issues and file a new issue if needed.

The official support channel for ReSpec is The mailing list archives are available. You can subscribe by sending email to with "subscribe" as the subject line.

In the extremely unlikely event that you would find a problem with this documentation, you can find the repository on GitHub. That is also the place where issues are handled (and discussion is also on spec-prod).


A list of contributors can be found on GitHub.

Thanks to Expway, Vodafone, W3C, and Mozilla, for their direct support of this project.

Based on Bert Bos' CSS pre-processor and Geoffrey Sneddon's Anolis.