Copyright ยฉ 2025 World Wide Web Consortium. W3Cยฎ liability, trademark and permissive document license rules apply.
ReSpec makes it easier to write technical documents. It was originally designed for writing W3C specifications, but now supports many output formats.
A ReSpec document is a HTML document that brings in the ReSpec script, defines a few configuration variables, and follows a few conventions. A very small example document would be:
html>
<html>
<head>
<meta charset="utf-8" />
<title>Replace me with a real titletitle>
<script
src="https://www.w3.org/Tools/respec/respec-w3c"
class="remove"
defer
>script>
<script class="remove">
// All config options at https://respec.org/docs/
var respecConfig = {
specStatus: "ED",
editors: [{ name: "Your Name", url: "https://your-site.com" }],
github: "some-org/mySpec",
shortName: "dahut",
xref: "web-platform",
group: "my-working-group",
};
script>
head>
<body>
<section id="abstract">
<p>This is required.p>
section>
<section id="sotd">
<p>This is required.p>
section>
<section class="informative">
<h2>Introductionh2>
<p>Some informative introductory text.p>
<aside class="note" title="A useful note">
<p>I'm a note!p>
aside>
section>
<section>
<h2>A sectionh2>
<aside class="example">
<p>This is an example.p>
<pre class="js">
// Automatic syntax highlighting
function someJavaScript(){}
pre>
aside>
<section>
<h3>I'm a sub-sectionh3>
<p class="issue" data-number="121">
p>
section>
section>
<section data-dfn-for="Foo">
<h2>Start your spec!h2>
<pre class="idl">
[Exposed=Window]
interface Foo {
attribute DOMString bar;
undefined doTheFoo();
};
pre>
<p>The <dfn>Foodfn> interface represents a {{Foo}}.p>
<p>
The <dfn>doTheFoo()dfn> method does the foo. Call it by running
{{Foo/doTheFoo()}}.
p>
<ol class="algorithm">
<li>A |variable:DOMString| can be declared like this.li>
ol>
section>
<section id="conformance">
<p>
This is required for specifications that contain normative material.
p>
section>
body>
html>
The following code is used to include a ReSpec document, usually in the :
<script src="https://www.w3.org/Tools/respec/respec-w3c" class="remove" defer>
script>
<script class="remove">
var respecConfig = {
// configuration options
}
script>
ReSpec is regularly updated and this will allow you to automatically benefit from bug and security fixes and enhancements.
ReSpec is configured using a JSON-like object, which is assigned to a respecConfig
JavaScript variable:
<script class="remove">
var respecConfig = {
// configuration options
}
script>
All the configurations options are listed in this document.
ReSpec documents are just HTML document and rely on HTML structural elements, in particular ,
,
, -
,
etc. In this section, we discuss how to specify various aspects of a typical document.
The
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.
<title>The Best Specificationtitle>
If you need to add additional markup to your title, you can still use a with
id="title"
.
<h1 id="title">The <code>Foocode> APIh1>
As with the title, you can also specify a subtitle as:
<h1 id="title">The <code>Foocode> APIh1>
<h2 id="subtitle">Subtitle hereh2>
Which is rendered as:
You can also specify a subtitle
configuration option in the ReSpec config, but using the markup above is preferred.
ReSpec-based specifications require you to wrap your content in elements. We provide specific information and examples on how to use
elements.
Sections, subsections, appendices, and whatever other structural items are marked up in ReSpec using elements.
<section>
<h2>A sectionh2>
<p>Some text.p>
<section class="informative">
<h3>I'm a sub-sectionh3>
<p>Sub-section text.p>
section>
section>
Which is rendered as:
As shown, sections are automatically numbered and uniquely id
's for you. Use specify your own id.
ReSpec sections understand some specific CSS classes: introductory
, informative
, and appendix
.
Note: You can use the special syntax [[[#some-id]]]
to link to a section.
In W3C specs, a table of contents (ToC) is generated automatically and placed after the "Status of This Document".
See also the maxTocLevel option to limit how deep the ToC is.
Set the configuration option noTOC
to true
to remove the table of content.
To include a figure, use the
and
elements. They automatically get an id
and figure number.
<figure id="figure">
<img src="figure.svg" alt="W3C Logo" />
<figcaption>The W3C logofigcaption>
figure>
Which renders as:
Automatic linking to figures works just as it does for sections, with [[[#some-figure]]]
.
To add a "List of Figures", include anywhere in the document. ReSpec will do its best to guess if it should be an appendix, introductory, or just a regular section.
<section id="tof" class="appendix">section>
Renders as:
Any or
gets the additional example header and style. Content inside
is syntax highlighted. You can specify the language in the class attribute, for example /
elements
.
<aside class="example" title="How to use it">
<p>
This is how to use it.
<p>
<pre class="js">
function myCoolFunction() {
// stuff goes here...
}
pre>
aside>
which is rendered as:
Including external content into ReSpec is done using the data-include
attribute, which points to a URL.
<section data-include="some.html">section>
You can specify data-include-format='text'
to include content as text, and therefore only process it as much as text is expected to be. The only recognized value are "text", "markdown", and "html" (default).
Note: data-include
relies on the browser's ability to retrieve the resource and is governed by CORS (and the browser's security model in general). Browsers will generally block cross origin request, which means file://
URLs will likely fail. For more information, please see "Cross-Origin Resource Sharing (CORS)". You can usually get around this by starting a local web server (e.g., by running python -m http.server 8000
from the command line).
Use data-oninclude
to perform transformation on content included with data-include
.
ReSpec specifications are RFC2119/RFC8174 keyword aware.
Adding a tells ReSpec that the specification is dealing with "normative" statements. ReSpec can then warn if RFC2119 keywords are accidentally used in informative/non-normative contexts.
<section>
<h2>Requirementsh2>
<p>A user agent MUST do something.p>
section>
<section id="conformance">section>
Renders as:
Mark abbreviations using abbr
. ReSpec will then wrap all matching instances abbreviations with .
<p>
The <abbr title="World Wide Web">WWWabbr>.
p>
<p>
ReSpec will automatically wrap this WWW in an abbr.
p>
To mark some text as code, use or backticks (`).
To define a term, simple wrap it in a element.
<dfn>some conceptdfn>
Then, to link to it, just do:
<a>some concepta>
or
[=some concept=]
For simple/single nouns, ReSpec handles pluralization automatically:
<dfn>bananadfn>
These [=bananas=] are better than those <a>bananasa>
Sometimes a defined terms needs additional related terms or synonyms. In those cases, you can use the data-lt
attribute on the dfn
element:
<dfn
data-lt="the best fruit|yellow delicious">
banana
dfn>
Note: "lt" stands for "linked term".
The following all link back to "banana":
<p>[=the best fruit=] or the [=yellow delicious=].p>
The powerful (xref
) feature let's you reference terms and concepts in other specifications. For example, to reference "default toJSON steps" from the WebIDL standard:
<script>
var respecConfig = {
xref: ["WebIDL"],
};
script>
<a>default toJSON stepsa>
To search for terms + specs your can link to, you can use the XREF UI at http://respec.org/xref/. Below is a screenshot of what the UI looks like:
There are two important shorthands for linking to definitions:
[=term=]
for linking regular concepts, {{IdlThing}}
for linking WebIDL.Shorthand syntax works for referencing external terms as well as locally defined terms. It's best practice is to use shorthands all the time.
<script>
var respecConfig = {
xref: ["webidl", "payment-request"],
};
script>
<section>
<p>[=default toJSON steps=] for the {{PaymentRequest}} interface are ...p>
<p>A <dfn>felinedfn> has 4 legs and makes sound.p>
<pre class="idl">
interface Cat {}
pre>
<p>A {{Cat}} is a [=feline=] if it meows.p>
section>
Read more about linking and other shorthands in the Shorthands Guide.
To reference another specification use the [[SPEC-ID]]
syntax, where SPEC-ID is the referenced specification's in the Specref ecosystem - which includes most W3C, WHATWG, ECMA, and IETF documents.
When you reference a specification, your document automatically gets a bibliography section.
The [^link^] element is defined in the [[HTML]] spec.
Which renders as:
If you would like to reference a specification by its full name, you can use the three square brackets to "expand it":
<p>
The [^link^] element is defined in the [[[HTML]]].
p>
Renders as:
ReSpec uses the context of the reference to work out if the reference is normative or informative: if the reference is in a section marked "informative", or an example, note, or figure, then ReSpec automatically makes the reference non-normative. Otherwise, the reference is treated as normative.
If you need a non-normative reference in a normative section, you can use a ?
like so:
This is normative and MUST be followed. But, sometimes we need a non-normative
example reference [[?FOO]].
To escape a reference, use a backslash "[[\
". For example, "[[\InternalSlot]]
".
If a reference is missing, please submit it to Specref. This helps the whole community.
If that is not possible, you can use of the localBiblio
configuration option to define your own references.
ReSpec supports adding additional links by specifying an otherLinks
property in the configuration. The values for this configuration option are rich and complex, so are detailed in the reference section for otherLinks
.
If you wish to add your own additional styles to your document, just use the regular and
elements.
Some of ReSpec's configuration options can be specified in the query string, and they override the options specified in the source. For example, you can override the subtitle
by, for example, doing the following: index.html?subtitle=This is a subtitle
.
This is useful for quickly overriding configuration options without needing to directly edit the document itself (e.g., for the purpose of exporting a document draft with a different specStatus
).
ReSpec provides useful options to handle the creation of the W3C boilerplate that goes into the "status of this document" and other key sections.
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.
The group
configuration option lets you state to which working/business/community group your specification belongs to. The list of group identifiers can be found at: https://respec.org/w3c/groups/.
Setting the group
option sets the IPR Policy for your document, which is reflected in the "Status of this Document" section.
If your document is not intended to be on the W3C Recommendation Track, set noRecTrack
to true.
The specStatus
option denotes the status of your document, per the W3C Recommendation track. Typically, a status has implications in terms of what other options required. For instance, a document that is intended to become a Recommendation will require previousPublishDate
and previousMaturity
.
The specStatus
section list all the possible status values.
By default, W3C specifications all get the regular W3C copyright notice. In some cases however, you will want to modify that.
For all document types, you can add your own copyright by using .
At times, the patent situation of a specification may warrant being documented beyond the usual boilerplate. In such cases, simply add your own to the Status of this Document section.
To specify an interface using WebIDL, you define a block.
<pre class="idl">
interface Request {
readonly attribute ByteString method;
readonly attribute USVString url;
};
pre>
The recommended way to code up your WebIDL is as follows:
<section data-dfn-for="ExampleInterface">
<h2><dfn>ExampleInterfacedfn> interfaceh2>
<pre class="idl">
interface ExampleInterface {
void exampleMethod();
readonly attribute USVString url;
};
pre>
<section>
<h2><dfn>exampleMethod()dfn> methodh2>
<p>The {{ExampleInterface/exampleMethod()}} method steps are:p>
<ol class="algorithm">
<li>Let |x| be ...li>
ol>
section>
<section>
<h2><dfn>urldfn> attributeh2>
<p>The {{ExampleInterface/url}} attribute...p>
section>
section>
<section>
<h2>Here is how you link!h2>
<p>
The {{ExampleInterface}}
or the {{ExampleInterface/exampleMethod()}} method
or the {{ExampleInterface/url}} attribute.
p>
section>
Given interface Request {};
, you can define the interface inside a heading like so:
<section>
<h2><dfn>Requestdfn> interfaceh2>
<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.
data-dfn-for
๐ EditWhen defining things, the data-dfn-for
creates child-parent relationships (e.g., a .method()
is "for", or part of, SomeInterface
).
For example, the following defines both the url
and the clone
method.
<section data-dfn-for="Request">
<h2>`Request` interfaceh2>
<pre>
interface Request {
readonly attribute ByteString method;
readonly attribute USVString url;
};
pre>
<p>The <dfn>clone()dfn> method. The <dfn>urldfn> attribute.p>
<p>
Links to {{Request/clone()}} method. Links to the {{Request/url}} attribute.
p>
section>
If, for instance, you have two interfaces with methods or attributes that are the same:
<pre class="idl">
interface Request {
readonly attribute USVString url;
};
interface Response {
readonly attribute USVString url;
};
pre>
You explicitly distinguish between them like so:
<section data-dfn-for="Request">
<p>
The <dfn>urldfn> attribute of {{Request}} is used by {{Response/url}}.
p>
section>
<section data-dfn-for="Response">
<p>
The <dfn>urldfn> attribute of {{Response}} depends on {{Request/url}}.
p>
section>
Open the ReSpec UI and select "Export...".
Select the format to export as.
One off (downloads about 100mb)...
npx respec --src source.html --out index.html
Or, to install ReSpec for repeated use:
npm install --global respec
And then:
respec --src source.html --out index.html
For more options, run respec --help
.
Description
Converts a ReSpec source file to HTML and writes to destination.
Usage
$ respec [source] [destination] [options]
Options
-s, --src URL to ReSpec source file.
-o, --out Path to output file.
-t, --timeout How long to wait before timing out (in seconds). (default 10)
--use-local Use locally installed ReSpec instead of the one in document. (default false)
-e, --haltonerror Abort if the spec has any errors. (default false)
-w, --haltonwarn Abort if ReSpec generates warnings. (default false)
--disable-sandbox Disable Chromium sandboxing if needed. (default false)
--devtools Enable debugging and show Chrome's DevTools. (default false)
--verbose Log processing status to stdout. (default false)
--localhost Spin up a local server to perform processing. (default false)
--port Port override for --localhost. (default 3000)
-v, --version Displays current version
-h, --help Displays this message
Similar to markdown, shorthands trigger special behavior in ReSpec. The most commonly used one you've likely seen is [[Reference]]
. Shorthands save you time and work: you write a lot less HTML, and ReSpec does all the linking and error checking for you.
Each of these special character combinations, as well as what behavior they trigger, are detailed below.
Note: Only WebIDL identifiers are case sensitive.
Type | Syntax | Examples |
---|---|---|
WebIDL | {{WebIDLThing}} |
{{PaymentRequest}} {{PaymentRequest/show()}} |
Concepts in specs | [=normal link=] |
[=queue a task=] |
Variable in an algorithm | |variable:Type| |
Let |p:Promise| be a new {{Promise}} |
HTML/SVG elements | [^element^] |
[^iframe^] |
Element attributes | [^element/attribute^] |
[^iframe/allow^] |
References | [[shortName]] |
[[RFC2119]] |
Expansions | [[[#some-id]]] |
[[[#example-2]]] expands and links to "Example 2" |
By design, we also share a lot of syntax with the BikeShed document processor. This makes it easier for everyone in the standards community to edit ReSpec and BikeShed specifications.
WebIDL is a meta language that used to define Javascript APIs for Web browsers. Please see our WebIDL Guide or the WebIDL spec for more info.
To link to something in WebIDL, you need to know its identifier
. An identifier
is the name of the interface, dictionary, or enum.
For example, {{PaymentRequest}}
links to the PaymentRequest
interface.
You can link attributes, methods, or members by using the interface name, /
, and the name of the thing you want to link to. For example, {{PaymentRequest/show()}}
links to the show()
operation of the PaymentRequest
interface.
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"}} |
Warning: Aliasing is not recommended.
You can alias WebIDL method names if you think the original name is adding noise.
Input | Renders as |
---|---|
{{ Window/postMessage(message, options) }} |
postMessage(message, options) |
{{ Window/postMessage(message, options)|postMessage(message) }} |
postMessage(message) |
{{ Window/postMessage(message, options)|postMessage() }} |
postMessage() |
{{ Window/postMessage(message, options)|postMessage }} |
postMessage() |
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 tags. For example,
success
and the steps to make a great meal
are defined concepts.
The syntax is [=concept you want to link to=]
. For example, [=queue a task=]
and [=fire an event=]
.
To link to a concept in another spec, you need to use the xref configuration option, and simply cite the spec you want to link to:
<p data-cite="HTML DOM">
You can [=queue a task=] to [=fire an event=] named `"respec-is-amazing"`.
p>
In the above, "queue a task" is defined in the HTML specification while "fire and event" is defined in the DOM specification.
See xref for more information.
ReSpec supports automatically linking to plural forms for simple nouns. Thus, [=fruits=]
links to the singular concept of fruit
, even across specs.
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 ๐โโ๏ธ).
Type | Syntax | Examples |
---|---|---|
Concept | [=concept=] |
[=queue a task=] |
Aliased concept | [=concept|some alias=] [=convoluted thing|simpler thing=] |
[=queue a task|task queuing=] |
Just as WebIDL interfaces can have methods and attributes, concepts have a very specific relationship to each other.
For example, the definition of a forEach()
method for a list
behaves differently from the definition of forEach()
method for a map
: the former operates on a single item, while the letter operates on a key/value pair. To make the relationship clear, we would write [=map/for each=]
, which is different to, say, [=list/for each=]
.
To associate a concept with another concept, use data-dfn-for
to indicate who or what owns the concept. This tells Respec who or what the concept is "for". See the example below:
A <dfn>cardfn> has a <dfn data-dfn-for="car">enginedfn>, which burns petroleum.
A <dfn>browserdfn> has a <dfn data-dfn-for="browser">enginedfn>, which burns
democracy.
Type | Syntax | Examples |
---|---|---|
Concept for thing | [=concept/sub concept=] |
[=list/for each=] [=map/for each=] [=Document/visible=] |
The syntax is |name|
, where name
is the name of the variable.
Let |value| be the {{DOMString}} "hello". ... If |value| is not "hello", then
doโฆ
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).
Type | Syntax | Examples |
---|---|---|
Variable | |variable| |
|value| |
Variable with a data type | |variable:dataType| |
|value:DOMString| |
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.
Type | Syntax | Examples |
---|---|---|
Element | [^element^] |
[^iframe^] |
Element with Content Attribute | [^element/contentAttribute^] |
[^iframe/allow^] |
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}}
.
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.
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!) |
You can use markdown to write ReSpec based documents. But you must follow markdown's rules carefully.
To enable markdown globally, set format
to "markdown" (see below). And, in the , make sure you keep all text flushed to the left. This is required because whitespace is significant in Markdown.
<html>
<title>Using Markdowntitle>
<script>
var respecConfig = {
format: "markdown"
}
script>
<body>
<section id="abstract">
Showing how to use Markdown.
section>
<section id="sotd">
Custom paragraph.
section>
## This is a heading
I'm a paragraph.
* list item
* another list item
body>
html>
The markdown is interpreted as Github Flavored Markdown (GFM) and you can mix HTML and markdown.
Now, we describe some of the ReSpec specific markdown behaviors and extensions.
When using markdown, you don't need to add elements manually. Each heading automatically creates a structure of nested section elements around it. For example:
## Heading
Here's some text.
### Sub heading
More text.
will be transformed into:
<section>
<h2>Headingh2>
<p>Here's some text.p>
<section>
<h3>Sub headingh3>
<p>More text.p>
section>
section>
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:
## I'm a heading {#custom-heading-id}
If there's a title
part in a markdown image, it's treated as a
. So:


is converted into:
<img src="src1.png" alt="alt text 1" />
<figure>
<img src="src2.png" alt="alt text 2" />
<figcaption>titlefigcaption>
figure>
You can use triple-backticks to create code-blocks (
). Respec supports syntax highlighting of various languages./
elements
```js
function hello() {
console.log("hey!");
}
```
And for WebIDL:
```webidl
[Exposed=Window]
interface Paint { };
```
The markdown parser automatically converts any URLs into anchors, including those found in code blocks.
You can turn off that functionality by adding the .nolinks
css class. Sadly, it means you have to use a element to create a code block.
<pre class="js nolinks">
async function() {
// https://example.com won't link
neitherWillThis("https://example.com");
}
pre>
Please remember that markdown requires double newlines between an HTML tag and markdown text.
Whitespace is also significant! So, keep things aligned to the left.
addSectionLinks
๐ EditControls if linked "ยง" section markers are added to a document. This is enabled by default for W3C documents.
var respecConfig = {
// turns off the ยง section markers
addSectionLinks: false;
}
caniuse
๐ EditAdds a Can I Use support table in the document header.
var respecConfig = {
caniuse: "payment-request",
};
var respecConfig = {
caniuse: {
feature: "payment-request",
browsers: ["chrome", "safari"],
},
};
Note: This feature is only available in "live" Editor's Drafts. Because this feature relies on JavaScript, it's not exported out when a document is saved as HTML. In exported document, the table is replaced by a link to caniuse.com.
feature
browsers
and_chr
- Chrome (Android)and_ff
- Firefox (Android)and_uc
- UC Browser (Android)android
- Androidbb
- Blackberrychrome
- Chromeedge
- Edgefirefox
- Firefoxie
- IEios_saf
- Safari (iOS)op_mini
- Opera Miniop_mob
- Opera Mobileopera
- Operasafari
- Safarisamsung
- Samsung Internetversions
4
maxAge
0
to get fresh data each on each request.86400000
// 24 hoursedDraftURI
๐ EditThe URL of the Editor's Draft, used in the header. This is required for when specStatus is "ED".
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.
var respecConfig = {
specStatus: "ED",
edDraftURI: "https://www.w3.org/TR/example",
};
editors
๐ EditAn array of person objects describing the editors of the document. Editors have the same responsibility as authors
, and are preferred in specifications.
var respecConfig = {
editors: [
{
name: "Marcos Caceres",
company: "Mozilla Corporation",
companyURL: "https://mozilla.org/",
w3cid: 39125,
},
{
name: "Kenneth Rohde Christiansen",
company: "Intel Corporation",
companyURL: "https://intel.com",
w3cid: 57705,
},
],
};
format
๐ EditTells ReSpec to treat the document as being in a format other than HTML. Supported formats:
var respecConfig = {
format: "markdown",
};
formerEditors
๐ EditAn array of person objects describing the past editors of the document. formerEditors
were added so as to avoid cluttering the present editors
list and are shown just below the list of present editors.
var respecConfig = {
formerEditors: [
{
name: "Marcos Caceres",
company: "Mozilla Corporation",
companyURL: "https://mozilla.org/",
w3cid: 39125,
},
{
name: "Kenneth Rohde Christiansen",
company: "Intel Corporation",
companyURL: "https://intel.com",
w3cid: 57705,
},
],
};
github
๐ EditThe github
option allows you associate your specification with a repository on GitHub.
It takes either a string (URL to your repo or a string of format: org/repo
) or an object with the following properties:
repoURL
- the URL for the repository (e.g., https://github.com/w3c/browser-payment-api)branch
- optional, the branch you are using for GitHub pages. It defaults to "gh-pages".This automatically generates:
It adds "Feedback:" to the header of the document, with the appropriate links to your GitHub repository.
This is normally what you want:
var respecConfig = {
github: "w3c/browser-payment-api",
};
var respecConfig = {
github: "https://github.com/w3c/browser-payment-api",
};
This example shows a repository whose specs are being served from a "public-docs" branch.
var respecConfig = {
github: {
repoURL: "https://github.com/w3c/browser-payment-api",
branch: "public-docs", // alternative branch
},
};
highlightVars
๐ EditWith long algorithms in a specification, it can be useful to allow readers to click on variables marked up with (e.g., Let
elem be ...
). By setting the respecConfig.highlightVars
configuration option, readers can now click on vars
in an algorithm to see where they are used.
var respecConfig = {
highlightVars: true,
};
It renders as:
isPreview
๐ EditThe isPreview
adds an annoying red box to your document, warning unsuspecting readers that they should not cite or reference this version of the specification.
This adds a big red ugly box to your document.
var respecConfig = {
isPreview: true,
};
license
๐ Editlicense
can be one of the following:
lint
๐ EditA 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:
var respecConfig = {
lint: false,
};
You can also enable or disable certain rules:
var respecConfig = {
"no-http-props": false, // disable a rule that enabled by default
"no-unused-vars": true, // enable a rule that disable by default
};
a11y
๐ EditLints for accessibility issues using axe-core: "Axe is an accessibility testing engine for websites and other HTML-based user interfaces".
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.
var respecConfig = {
lint: {
a11y: true,
}
};
Example with Axe configuration, as per Axe's configuration options.
var respecConfig = {
lint: {
a11y: {
runOnly: ["image-alt", "link-name"],
},
},
};
Another example:
var respecConfig = {
lint: {
a11y: {
// run all rules, except "image-alt" and slow rules (but run "color-contrast")
rules: {
"color-contrast": { enabled: true }, // disabled by default, enable it
"image-alt": { enabled: false },
},
},
},
};
If the document has accessibility issues, they will show up as ReSpec warnings:
In an actual document, you can expand the details to get more information about each issue along with a link to the specific HTML element causing the issue.
You can also use respecConfig.a11y
to define the linter config (instead of respecConfig.lint.a11y
). This lets us quickly run the linter by adding a URL param ?a11y=true
.
check-punctuation
๐ EditEnable this lint rule to check for punctuation. It checks for:
tag.For example:
<p>This has no punctuation at the endp>
You will receive a warning that your tag should end with punctuation mark.
var respecConfig = {
lint: {
"check-punctuation": true,
},
};
informative-dfn
๐ EditEnable this lint rule to get a warning if an informative definition is used in a normative section.
You can fix your document by making the definition normative or use a local normative proxy for the definition like term
.
To silence this warning entirely, set lint: { "informative-dfn": false }
in your respecConfig
.
var respecConfig = {
lint: {
"informative-dfn": true
},
};
local-refs-exist
๐ EditEnable this lint rule to get a warning if there are some href
's that link to nonexistent id
's in a spec.
For example:
<section id="foo">section>
<a href="#bar">baza>
You'll receive a warning pointing you to the links that are broken.
var respecConfig = {
lint: {
"local-refs-exist": true,
},
};
no-captionless-tables
๐ EditEnable this lint rule to get a warning if there is some This only applies applies to tables with a For example: You'll receive a warning pointing you to the caption-less table. Enable this lint rule to get a warning if there is some For example: You'll receive a warning pointing you to the heading-less sections. Enable this lint rule to get a warning if there exists some URL in For example: You'll receive a warning pointing you to the violating properties in Enable this lint rule to get a warning if an internal or un-exported definition is not used, i.e. there is nothing linking to that definition in given spec. You can fix this by removing the To silence this warning entirely, set Enable this lint rule to get a warning if a variable is defined but not used. The first use of variable ( For example: You'll receive a warning pointing you to the unused To ignore warning on per-variable basis, add a Note that the 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. Enable this lint rule to get a warning if any of the tests mentioned in For example: You'll receive a warning listing all the missing tests. 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: use of localBiblio is strongly discouraged. Please contribute references back to the SpecRef database instead. Overrides the standard W3C logo with one or more other logos. The Would output: 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. The If a boolean is provided, it uses spec's If the The key can be found at https://w3c.github.io/mdn-spec-links/SPECMAP.json. For example, the key is It renders as panels near relevant definitions in the right-side of the document: A Adds a "monetization" This options takes either a boolean, a string (a payment pointer), or an object with a By default, the meta tag is added only to "live" documents, and is removed from generated static documents. If you do not explicitly disable this feature or set a different payment pointer, it uses ReSpec's payment pointer by default. To disable web monetization entirely: To keep the payment pointer in a generated snapshot: When this configuration variable is set to There is a corresponding class of Adds additional links to the header of the document. This is useful if you want to link to other resources, like a news feed, a GitHub repository, or a relevant website. The Above is rendered as: Adds automatic pluralization support for This is enabled by default for W3C specs. You can define a term as 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 If you want to selectively disable pluralization on certain Takes an array of JavaScript functions which ReSpec then runs in order. Each function is called with the ReSpec config object (i.e., the The following examples shows two functions run in order after processing. Note: there are no special requirements or "best practices" for how you process HTML either before or after ReSpec has finished doing its thing. Once ReSpec is finished processing the document, it stops running and you a free to do whatever you like to your document. Having said that, you should follow web development best practices for Web Development when manipulating any generated document (i.e., "it's just HTML, JS, and CSS"). 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), the reference to the DOM Document element and a utils object. A 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. 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). Specifications can be given a status (e.g. a Working Draft, an Unofficial document, etc). However, what that status means is up to the publisher, or standards body, that is publishing the specification. For W3C documents, the following status are supported. 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. Also see: The And then simply write the terms you want to link to: 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 the "export" CSS class. The following configurations are available: Note that when using the object configuration, if both Profiles are pre-defined lists of specifications. Using a profile means adding all of its specification short-names to the Following profiles are currently available: Using the specs 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: 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: The Following keywords automatically generate a corresponding URL. However, you are free to include your own URL. 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. ReSpec knows to include a copyright year that matches the Note that this can always be safely specified since if The following appears as "Copyright ยฉ 1977-2016". 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 Adds a JSON-LD The following entry in In addition, you will also need to provide a When configured, a script element similar to the following will be added: An URL to a document capturing errata for the specification. Generally, this only applies to documents with a "REC" and "PER" For W3C, it allows you to associate a specification with a particular working group. Supported group short-names can be found at: https://respec.org/w3c/groups/. Specifying the group will also figure out all the patent policy related things for your particular specification. You can also specify multiple groups: 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: Closed groups aren't listed at https://respec.org/w3c/groups/, but you can access their details by writing both group type and shortname in The URL of the implementation report (documenting how your test suite fares with implementations). It gets included in the specification's headers. For W3C Community Groups and Business Groups, it allows you to specify a URL for where the "Latest Version" of a specification can be found (e.g., on GitHub, using GitHub pages). For regular W3C Working Groups, Note: The "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: 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 Which results in: Which would render as, for example: A boolean indicating that a document is not intended to become a W3C Recommendation. Used for Notes while in unfinished maturity states. A date in the format 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. 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. A Please note that some values of this option make no sense depending on the current document A 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 Allows W3C staff to link to a comment number. Which shows up as: The short name of the mailing list on which the group conducts its public discussion. When present, a section with id The author can add any additional conformance clause(s) which will follow this boilerplate. This section is required for specifications that contain normative material. Add an element with The list is sorted by names (or GitHub username). Giving a 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. You can also add a custom header and content to your idl-index: Adding a You can also add a custom header and content to your When present, the You can add an explicit Automatically generate a Table of Figures by adding a To enable dark mode in your spec, add the following to the Note: This is supported for W3C specs only, and makes use of official dark.css in tr-design. Specification figures are indicated using the Figures can be automatically linked to using a link pointing to their ID with no content (e.g. You can also automatically generate a table of figures. The recommended way to set the title of a specification is via a ReSpec warns if the ReSpec provides code highlighting for blocks of code marked up with the Respec uses highlight.js for syntax highlighting and supports the following languages by default: An advanced syntax highlighter for WebIDL is also available out of the box. 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 Specification sections are indicated using the 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. ReSpec uses the 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 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 Marks a For a contra-example, replace the Note that the content of the The It is only supported on the following elements: Some examples of usage: Use Then other specs can use "fancy thing" using xref, like so: 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. Provided you've added the ReSpec will automatically download the issue details and include them for you. Additionally, you can gather all referenced issues in a list with The CSS class Setting "no-link-warnings" class on a Note: We discourage the use of this feature, because you could miss defining important things. However, if you know you don't want to link certain things (e.g., a Dictionary and an interface). In the following example, the semantics of the attributes is the same in both the dictionary and the interface. As such, it might not make sense to provide formal definitions for the dictionary items. Indicates that a code block should not be syntax highlighted. This block will not be syntax highlighted: But this one will be syntax-highlighted by default: When using markdown, nolinks disables automatic linking within code blocks. 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 When this class is specified on a section element, that section will be omitted from the Table of Contents. Also see: TODO. Warning: only use this as a last resort. This feature is not recommended. The Sections you can override include: The A A paragraph containing the description of a best practice, inside a practice A 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. 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 For W3C Proposed Recommendations, declaring The You can either set the abbreviation explicitly, or ReSpec can figure it out for you. You can also set the abbreviation by yourself. Note: This is not the recommended way of linking to terms in other specs. Please use Using Add "!" on the front of the spec ID makes it a "normative" citation. Excluding it, makes it informative. It is currently supported on The syntax for data-cite value is: The The following example automatically links up the You can add a In many cases, you do not need to provide this value. If a Currently, only two values: The The following would generate a H2 element (which ReSpec would automatically number). 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 - 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. Note: When using 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 If you want to include as markdown, use 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 The It works with IDL definitions also: The In this example, we link to Note: This is mostly internal. Prefer Shorthands Syntax, as they automatically add this attribute to relevant elements. The In general, you can provide alternative "linking text" (" However, in the rare situation where you need to export via 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: See also: Automatic pluralization with If you want to selectively disable pluralization on certain Allow you to ignore data-lt-noDefault definition of a defined term. This is sometimes useful if you need to disambiguate two terms. Limit depth of table to contents section to section, without adding a global depth limit using Can be used in conjunction with the configuration option A typical example for a file in the Github repository https:/github.com/w3c/dpub-pwd would include, for example: 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. By using You can also just write becomes: Sorting a definition list ("ascending" by default, so A-to-0Z locale dependent). The corresponding becomes: The The It's best used with Usable on Note: The ReSpec defaults the ReSpec defaults the The The filter function takes one argument, which is a commit object. The object is composed of two properties: When ReSpec is loaded, it immediately adds a This property returns a Promise, which resolves when ReSpec finishes all its processing. This promise is useful if you need to be notified when ReSpec has finished doing its work - and you want to do some additional work. The following example shows how to use An array of errors found during ReSpec's processing, with each item containing an error Similar to Returns a promise that resolves with the markup resulting from ReSpec's processing, as a string. This is no longer supported by ReSpec. Please write any patent-related notes directly into the "Status of This Document" section instead. Warning: 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 Warning: This is deprecated and has been removed. Use the 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. Warning: This is deprecated. Use the The full public name of the group, including "Working/Interest/Incubator/etc. Group" as applicable. Warning: This is deprecated. Use the The numeric W3C Working Group identifier. This is used when publishing NOTEs to create the Warning: This is deprecated. Use the The URL of the public list of patent disclosures for the group. 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. Warning: This is deprecated. Use the The URL to the public page of the working group that is working on the spec. A person object (used for Name of the person. Home page of the person. Name of the company the person is affiliated with. url of the company. For W3C documents, an identifier of the personsโ W3C account. This id can be
found in my profile URL
that will be redirected to the userโs page; the id appears in the address
bar (e.g., https://www.w3.org/users/12345). Identifier or full URL of the persons'
ORCID account. This can be a URL or the
ORCID. The date in which an person has retired from working on a specification. The
format is yyyy-mm-dd. Any text in this field will appear at the end of the personโs identification
in parenthesis. Refers to an array of extras (see below) objects, displayed at the end of
the person's identification. The โextrasโ are objects, with the following specified below. The content of the resulting A CSS class value (can be used for styling). Optionally, a hyperlink. This page lists some common ReSpec errors and their mitigation. To fix this issue, follow these steps: Is the term defined in some other document/specification? Is the term defined in same document? As a first step, clone the repository: Developing ReSpec requires Node.js v18.14+ and and install the needed dependencies: Now you can start the local development servers: Note: You can use Firefox and ChromeCanary in the above. That will start up "Karma" and a local http server for you. Open the url given (usually http://127.0.0.1:8000). And go to "examples". Usually "basic.html" is a good place to start hacking from. ReSpec is an application that runs mostly synchronous bits of JS after a Generally, a "profile" is only created for a real-world organization or company. So, for instance, the W3C's profile, located at What each plugin above does doesn't matter, though you can deduce what each does by the name. What matters is that ordering is important - and we mix together W3C plugins and "core" plugins. And that it's these plugins coming together that form a profile, in this case the "W3C profile". Each of the plugins are run only once - and the thing that runs them is the See The first and most important plugin ( Before any plugins are run, however, it adds the following property to the After that, the Base Runner starts looping over an array of given plugins: literally just a call to a Once all the plugins have "run", ReSpec resolves the This is potentially useful for scripts that depend on ReSpec's output. They can wait for the promise to settle before doing their own work. Alternatively, if you really need to run things immediately before or after ReSpec runs the plugins, you can define Plugins are simple ES6 modules that live in the "src/" folder. They have two parts: A synchronous initialization, and an optionally exported A plugin looks like this: The exported run method SHOULD have arguments (conf): If you are creating a plugin that needs to show warnings to a user, you can use the These messages will be picked up by ReSpec's UI (the "pill"), and displayed to the end-user. You should only "error" on things that the user needs to fix to successfully publish their document. Likewise, only warn on things the user SHOULD fix. IMPORTANT: Don't show JavaScript errors to the user - as they won't be able to fix these, and the minified JS output will make these messages really unhelpful! The You can launch a built in HTTP server during development by simply typing: ReSpec's unit tests are written using Jasmine and run on Karma. To start the testing server: You can run test in different browsers by setting For debugging purposes, you can click on the Debug button when the tests start in the browser - this will allow you to see the tests summary in browser itself as well as allow you to re-run any particular test. Please refer to Jasmine documentation regarding focused specs ( You can also select individual tests by filtering those which match a particular pattern: If you want to run all tests whose description includes "SEO". You can also This is useful for more advanced debugging sessions, and can be combined with You can also run tests without opening a full browser window. Test results will be visible in your terminal. Look at the help dialog when you run If you are a company, standards consortium, or government entity, you might want to consider maintaining your own ReSpec profile. That allows you have your own content templates, load whatever plugins you need, and generally keep control over how ReSpec runs. To create a custom profile: If the profile is popular, then please send a pull request to the main repository and we can host as part of the main project. In That will start a web server, so you can now load up If you are writing custom Jasmine tests, simply place them into If you prefer to use a different browser, that's ok too.
This document is generated directly from the content of the
ReSpec project wiki on
GitHub. Thus, it can be edited in two ways:
in the document that does not contain a
.
.numbered
class. Note that, the
must be the first child of .
<table class="numbered">
<tr><td>...td>tr>
table>
var respecConfig = {
lint: {
"no-captionless-tables": true,
},
};
5.12.6
no-headingless-sections
๐ Edit in the document that does not start with a heading element (
h1
-h6
).<section id="foo">
<p>content beginsp>
section>
var respecConfig = {
lint: {
"no-headingless-sections": true,
},
};
5.12.7
no-http-props
๐ EditrespecConfig
that starts with http://
.<script>
var respecConfig = {
implementationReportURI: "http://w3c.github.io/payment-request/reports/implementation.html",
^^^^^
};
script>
respecConfig
.var respecConfig = {
lint: {
"no-http-props": true,
},
};
5.12.8
no-unused-dfns
๐ Edit element or use another HTML element than
for that definition, or add
class="export"
to the definition.lint: { "no-unused-dfns": false }
in your respecConfig
.var respecConfig = {
lint: {
"no-unused-dfns": true,
},
};
5.12.9
no-unused-vars
๐ Edit) is considered its definition. Only unused variables in sections that contain a
are reported.<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>
s.
var respecConfig = {
lint: {
"no-unused-vars": true,
},
};
data-ignore-unused
attribute๐ Editdata-ignore-unused
attribute to as:
<var data-ignore-unused>someUnusedVarvar> is unused, but warning is ignored.
|someVar|
shorthand does not support this attribute.5.12.10
privsec-section
๐ Editvar respecConfig = {
lint: {
"privsec-section": false,
},
};
5.12.11
wpt-tests-exist
๐ Editdata-tests
does not exist in the WPT repository.<p id="a" data-tests="test.html,404.html">p>
var respecConfig = {
testSuiteURI: "https://github.com/web-platform-tests/wpt/tree/HEAD/webrtc/",
// alternatively:
// testSuiteURI: "https://wpt.fyi/webrtc/",
lint: {
"wpt-tests-exist": true,
},
};
5.13
localBiblio
๐ Editvar respecConfig = {
localBiblio: {
WEREWOLF: {
title: "Tremble Puny Villagers",
href: "https://w3.org/werewolf",
status: "RSCND",
publisher: "W3C",
},
},
};
5.14
logos
๐ Editlogos
property takes an array that contains a set of objects. Each of these objects contains:
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",
},
],
};
<a class="logo" href="https://example.com">
<span id="example-company-logo">
<img
src="https://example.com/logo.gif"
width="100"
height="42"
alt="The Example company"
>
span>
a>
5.15
maxTocLevel
๐ Editvar respecConfig = {
maxTocLevel: 2,
};
5.16
mdn
๐ Editmdn
option allows a spec to be annotated with links to MDN developer documentation.shortName
to match data over on MDN.var respecConfig = {
shortName: "payment-request",
mdn: true,
};
shortName
doesn't match the MDN key, you can provide a key as:var respecConfig = {
mdn: "payment-request",
};
"image-capture"
in the following entry:"https://w3c.github.io/mediacapture-image/": "image-capture.json",
5.17
modificationDate
๐ EditYYYY-MM-DD
date. The in-place edit date of an already published document. Used in conjunction with publishDate
, as per Pubrules.var respecConfig = {
publishDate: "2020-03-30",
modificationDate: "2020-04-13",
};
5.18
monetization
๐ Edit tag to enable Web Monetization.
paymentPointer
(string) and removeOnSave
(boolean) property. var respecConfig = {
monetization: "$wallet.example.com/my-wallet",
};
var respecConfig = {
monetization: false,
};
var respecConfig = {
monetization: {
paymentPointer: "$customPointer",
removeOnSave: false,
}
};
5.19
noTOC
๐ Edittrue
, no table of contents is generated in the document.var respecConfig = {
noTOC: true,
};
notoc
.5.20
otherLinks
๐ EditotherLinks
property takes an array that contains a set of objects. Each of these objects contains a key
and a data
property. The key
is the text that will contain the links to the relevant resources. The data
is another array of objects that contain the data describing the resource (with the properties value
which is a string, and href
which is the URL you want to link to). If a href
is not provided, value
is displayed as text.var respecConfig = {
otherLinks: [
{
key: "Implementation status",
data: [
{
value: "Gecko",
href: "https://bugzilla.mozilla.org/show_bug.cgi?id=xxxx",
},
{
value: "Blink",
href: "https://code.google.com/p/chromium/issues/detail?id=xxx",
},
],
},
],
};
5.21
pluralize
๐ Edit, so that you don't have to manually define
data-lt
attributes for plurals.var respecConfig = {
pluralize: true,
};
fetch
and reference it as either fetch
or fetches
.
Below are some more examples:<dfn>user agentdfn> can be referenced as:
โข <a>user agentsa>
โข <a>user agenta>
โข <a data-lt="user agent">browsera>.
<dfn data-lt="pub">bardfn> can be referenced as:
โข <a>puba>
โข <a>bara>
โข <a>barsa>
โข <a data-lt="pub">drinking establishmenta>
โข <a data-lt="bar">drinking establishmenta>
โข <a data-lt="bars">drinking establishmenta>
fetches
or fetch request
, we won't add a pluralization of fetch
., you can make use of
data-lt-no-plural
attribute like:<dfn data-lt-no-plural>htmldfn>
5.22
postProcess
๐ Editvar respecConfig
object, plus some additional internal data), the reference to the DOM Document element and a utils object.function doThing(config, doc, utils){...}
function doOtherThing(config, doc, utils){...}
var respecConfig = {
// After processing, run the following
postProcess: [doThing, doOtherThing]
}
5.23
preProcess
๐ Editfunction doThing(config, document, utils){...}
function doOtherThing(config, document, utils){...}
var respecConfig = {
// Before processing, run the following
preProcess: [doThing, doOtherThing]
}
5.24
publishDate
๐ EditYYYY-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.var respecConfig = {
publishDate: "2021-01-02",
};
5.25
shortName
๐ Editvar respecConfig = {
shortName: "awesome-api",
};
5.26
specStatus
๐ Editvar respecConfig = {
specStatus: "unofficial",
};
Value
Meaning
Must also include
base (default)
Just the basic template, not a specification. Use this for public documentation produced
by a group that has no current clear plan to be officially published.
None.
unofficial
An unofficial draft. Use this if you're producing a document
to use styles that match those of W3C specifications, for instance to propose
a new document while hosting it on your own server. Note that this automatically
licenses the content under CC-BY v3.0. If you want a different copyright,
you will need to set the various copyright configuration options.
W3C๐ Edit
Value
Meaning
Must also include
MO
Member-Only Document. Similar to base, but for documents that need to be clearly
flagged as being restricted in access to W3C Members. This is rarely, if
ever, useful.
None.
ED
Editor's Draft. Use this for documents that are maintained in the group's own repository.
latestVersion: null
(See #2968 for details).
FPWD
First Public Working Draft.
None.
WD
Working Draft.
LD
Living Document.
LS
Living Standard.
CR
Candidate Recommendation.
CRD
Candidate Recommendation Draft.
Same as CR above.
PR
Proposed Recommendation.
PER
Proposed Edited Recommendation.
REC
Recommendation.
RSCND
Rescinded Recommendation.
DISC
Discontinued Draft.
STMT
Statement.
DNOTE
Draft Group Note.
None.
NOTE
Group Note.
None.
BG-DRAFT, BG-FINAL
Business Group Draft or Final Report.
None.
CG-DRAFT, CG-FINAL
Community Group Draft or Final Report.
None.
Member-SUBM
Member Submission. Note that ReSpec uses the default W3C copyright for this, but
that you are entitled to retain your own copyright instead of transferring
it to W3C. Use the copyright options for this.
draft-finding
Draft TAG Finding. If you are one of the Nine and working on a Finding, this is for
you. Note that for findings, ReSpec currently does not support very robust
SotD generation (there doesn't seem to be solid rules for what constitutes
a valid Finding SotD) so you'll have to specify your own. If there are rules
that could be used, please report a bug. ReSpec further assumes some conventions
for finding URLs that are not consistent throughout all of the TAG's repository,
specifically that all findings live in "https://www.w3.org/2001/tag/doc/",
that the latest version is at "https://www.w3.org/2001/tag/doc/shortName",
and that the dated versions are at "shortName-YYYYMMDD".
None.
editor-draft-finding
Editor Draft TAG Finding. If you're working on a TAG document maintained on GitHub rather than
in the old datedspace system, use this.
None.
finding
TAG Finding. Same as above, but final.
None.
5.27
subjectPrefix
๐ Editvar respecConfig = {
subjectPrefix: "[Foopy-Spec-Feedback]",
};
5.28
subtitle
๐ Editvar respecConfig = {
subtitle: "The spec to end all specs.",
};
5.29
testSuiteURI
๐ Editvar respecConfig = {
testSuiteURI: "https://example.com/test/suite/",
};
wpt-tests-exist
lint rule.5.30
xref
๐ Editxref
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",
};
<p>
[=Queue a task=] to [=fire an event=] named "yay"
at the {{Window}} object.
<p>
xref configuration options๐ Edit
xref: true
simply enables the xref feature.data-cite
attribute of the document's . ReSpec then uses these specifications for disambiguation.
url
, specs
and profile
.
url
is used to link to a custom references API.specs
is used to specify an array of specification short-names. This array is added to the data-cite
attribute of the document's and used for disambiguation.
profile
is used to specify profile.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
data-cite
attribute of the document's .
var respecConfig = {
xref: true,
};
var respecConfig = {
xref: "web-platform",
};
var respecConfig = {
xref: ["spec1", "spec2"],
};
spec1
and spec2
along with specs in the web-platform
profile to look for references.var respecConfig = {
xref: {
specs: ["spec1", "spec2"],
profile: "web-platform",
},
};
6.1
additionalCopyrightHolders
๐ Editvar respecConfig = {
additionalCopyrightHolders: "Internet Engineering Task Force",
};
6.2
alternateFormats
๐ Edit
uri
label
var respecConfig = {
alternateFormats: [
{
label: "PDF",
uri: "https://example.w3.org/TR/example.pdf",
},
{
label: "XML",
uri: "https://example.w3.org/TR/example.xml",
},
],
};
6.3
canonicalURI
๐ EditcanonicalURI
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.
Keyword
Generated URL
"edDraft"
Use the
edDraftURI
as the canonical URL.
"TR"
Use the "TR" location for this document, using the
shortName
.var respecConfig = {
shortName: "fooAPI",
canonicalURI: "TR",
};
6.4
charterDisclosureURI
๐ Editvar respecConfig = {
charterDisclosureURI: "https://www.w3.org/2019/06/me-ig-charter.html#patentpolicy",
};
6.5
copyrightStart
๐ EditpublishDate
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.copyrightStart
is the same as the publishDate
's year it is ignored.var respecConfig = {
copyrightStart: 1977,
publishDate: "01-01-2016",
};
6.6
crEnd
๐ EditYYYY-MM-DD
format.var respecConfig = {
specStatus: "CR",
crEnd: "2014-01-04",
};
6.7
doJsonLd
๐ Editscript
element containing schema.org information, which can be useful for search engines.respecConfig
can be used to configure JSON-LD support, which currently defaults to false
.var respecConfig = {
doJsonLd: true,
};
canonicalUri
and a license
in your respecConfig
for the JSON-LD data to be generated.<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.8
errata
๐ EditspecStatus
.var respecConfig = {
status: "REC",
errata: "https://www.w3.org/XML/xml-V10-5e-errata",
};
6.9
group
๐ Editvar respecConfig = {
group: "payments",
};
var respecConfig = {
group: ["group1", "group2"],
};
var respecConfig = {
group: "wg/wot",
};
respecConfig.group
(like wg/csv
). https://www.w3.org/groups/ might be helpful in finding shortname and type in such cases.6.10
implementationReportURI
๐ Editvar respecConfig = {
implementationReportURI: "https://example.com/imp-report/",
};
6.11
latestVersion
๐ EditlatestVersion
is automatically set. However, in rare cases, you can override the "Latest Version" to point to a different path or URL. latestVersion
URL is resolved using https://www.w3.org/
as the base URL. var respecConfig = {
latestVersion: "https://respec.org/docs/";
}
6.12
level
๐ Editlevel
configuration options automatically appends the level to your specโs title and shortName. The level is an integer value greater than or equal to 0.var respecConfig = {
level: 2,
shortName: "payment-request",
};
Level 2
is appended to the title, so Payment Request Level 2
.payment-request-2
.6.13
noRecTrack
๐ Editvar respecConfig = {
noRecTrack: true,
};
6.14
prEnd
๐ EditYYYY-MM-DD
. Documents that are in Proposed Recommendation (specStatus
is "PR") are required to indicate an end date for the review period.var respecConfig = {
specStatus: "PR",
prEnd: "2016-01-03",
};
6.15
prevED
๐ Editvar respecConfig = {
prevED: "https://example.com/old/ed",
};
6.16
previousDiffURI
๐ Editvar 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
๐ EditspecStatus
identifier (e.g., "CR"). When a previousPublishDate
is specified, this is typically required as well in order to generate the "Previous Version" link since it includes an indication of the previous document's maturity level, which cannot be guessed. The values are the same as for specStatus
.specStatus
but that the rules for validating consistency are convoluted enough that ReSpec does not try to check them. If you pick the wrong value (typically by forgetting to change it), the Link Checker will most likely catch the error before publication (the same goes for previousPublishDate
).var respecConfig = {
previousPublishDate: "2014-05-01",
previousMaturity: "LC",
};
6.18
previousPublishDate
๐ EditYYYY-MM-DD
date. When there is a previous release of a given specification, this is used to generate the "Previous Version" link. It is required for Recommendation Track documents.var respecConfig = {
previousPublishDate: "2014-05-01",
previousMaturity: "LC",
};
6.19
prevRecShortname
๐ Editvar respecConfig = {
shortName: "fancy-feature-l2",
prevRecShortname: "fancy-feature",
};
6.20
prevRecURI
๐ EditprevRecURI
is not specified but prevRecShortname
is, the latter will be used to generate the former by prefixing "https://www.w3.org/TR/" to it. Note however that while in the overwhelming majority of cases this works, it is not recommended to use this approach since if the Recommendation is later Rescinded, the link will be stale. Instead, use the dated link to the Recommendation.var respecConfig = {
prevRecURI: "https://www.w3.org/TR/2014/example-20140327/",
};
6.21
submissionCommentNumber
๐ Editvar respecConfig = {
specStatus: "Member-SUBM",
submissionCommentNumber: "03",
};
<a href="https://www.w3.org/Submission/2018/03/Comment/">
W3C Team Comment
a>
6.22
wgPublicList
๐ Editvar respecConfig = {
wgPublicList: "public-device-apis",
};
7.1
conformance
๐ Editconformance
tells ReSpec to add the standard boilerplate to the document.<section id="conformance">
<p>The specification specific conformance textโฆp>
section>
7.2
gh-contributors
๐ Editid="gh-contributors"
to show a list of people who have contributed to the GitHub repository.<section>
<h2>Contributorsh2>
<ul id="gh-contributors">
ul>
section>
<p>
We'd also like to thank the following contributors: <span id=
"gh-contributors">span>.
p>
7.3
idl-index
๐ Edit 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.
<section id="idl-index" class="appendix">
section>
<section id="idl-index" class="appendix">
<h2>The Whole API!h2>
<p>This is what the whole thing looks like!p>
section>
7.4
index
๐ Edit in your document instructs ReSpec to gather all the terms defined in your specification, as well as all the terms referenced by your specification into a single section. The index lets you conveniently search for all defined/referenced terms, as well as find their usage in the document.
<section id="index" class="appendix">
section>
index
:<section id="index" class="appendix">
<h2>List All The Terms!h2>
<p>Wow, that's a lot of terms!p>
section>
7.5
issue-summary
๐ Editissue-summary
id tells ReSpec to gather all issues
found throughout your spec and display them.<div class="issue" data-number="123" title="This is issue!">
<p>It clear that this is an issue.p>
div>
<section class="appendix" id="issue-summary">
section>
7.6
references
๐ Edit in cases where you need to add custom content to the references section of a document.
<section id="references">
<p>Citations are great!p>
section>
7.7
tof
๐ Edit.
<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">
section>
8.1 Dark mode๐ Edit
of your document:
<meta name="color-scheme" content="light dark">
8.2
๐ Edit
element, with a nested
. They can occur anywhere.<section id="buckets">
<figure id="flowchart">
<img src="flowchart.svg" alt="" />
<figcaption>The water flows from bucket A to bucket B.figcaption>
figure>
<p>The flowchart shown in <a href="#flowchart">a> is quite impressive.p>
section>
).
8.3
๐ Edit
element. However, in cases where you might need markup in a spec's title (e.g., for i18n reasons), you can use a single element.
and the text content do not match.
<body>
<h1 id="title">The <code>Whatevercode> Interfaceh1>
<section id="abstract">
<p>...p>
section>
body>
8.4
/
๐ Edit
or
elements. ReSpec will try to guess the code language, or it can be added as a class (to disable syntax highlighting use the "nohighlight" class):
<pre>
<script>
function magic() {
const noop = "this";
doThat(noop);
}
script>
pre>
preProcess
option:async function loadSolidity() {
//this is the function you call in 'preProcess', to load the highlighter
const worker = await new Promise(resolve => {
require(["core/worker"], ({ worker }) => resolve(worker));
});
const action = "highlight-load-lang";
const langURL =
"https://rawgit.com/pospi/highlightjs-solidity/master/solidity.js";
const propName = "hljsDefineSolidity"; // This funtion is defined in the highlighter being loaded
const lang = "solidity"; // this is the class you use to identify the language
worker.postMessage({ action, langURL, propName, lang });
return new Promise(resolve => {
worker.addEventListener("message", function listener({ data }) {
const { action: responseAction, lang: responseLang } = data;
if (responseAction === action && responseLang === lang) {
worker.removeEventListener("message", listener);
resolve();
}
});
});
}
var respecConfig = {
// i.e. add this line to your existing configuration
preProcess: [loadSolidity],
// ... other configuration information
};
8.5
๐ Edit
element. They can be nested arbitrarily in order to indicate sub-sections.
).
<section>
<h2>The <code>foocode> Elementh2>
<p>The <code>foocode> Element allows you too...p>
section>
8.6
๐ Edit
element to generate the title of your specification. The
element is left untouched, but its content is used to create a title for the specification.
html>
<html>
<title>The Super Duper Spectitle>
<body>
<section id="abstract">section>
body>
html>
9.1
appendix
๐ Edit<section class="appendix">
<h2>Acknowledgementsh2>
<p>This spec would not be possible without...p>
section>
9.2
ednote
๐ Edittitle
attribute will be interpreted as HTML markup. See title
attributes for details.<p class="ednote" title="This section will be reformatted">
We are aware that the formatting of this section isn't great. We will fix it
in the next revision!
p>
9.3
example
๐ Editpre
, 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 pre
s.example
class with illegal-example
.title
attribute will be interpreted as HTML markup. See title
attributes for details.<aside class="example" title="Fat arrows (
=>
)">
<p>Here we see how to use a fat arrow in ES.p>
<pre>
const sum = [...items]
.map(item => item * 2)
.reduce((sum, next) => sum + (next || 0) );
pre>
aside>
9.4
exclude
๐ Editexclude
CSS class allows HTML tags to opt-out of being processed by ReSpec.
TEXT
- excludes the element from automatic abbreviation generation, such that TEXT won't be wrapped in .
, excludes the WebIDL block from the IDL index. This is useful if you want to have an WebIDL example that is not actually part of your specification.
<p>
<abbr class="exclude" title="Ay-Bee-See">ABCabbr>,
but this won't be wrapped ABC.
p>
<aside class="example" title="A hypothetical API">
<pre class="idl exclude">
interface ItsTwentyTwenty {
undefined cantSeeNobody();
};
pre>
aside>
9.5
export
๐ Edit to export a definition to W3C's Webref database.
<p>The <dfn class="export">fancy thingdfn> can be used by other specs.p>
<script>
var respecConfig = {
xref: true,
};
script>
<p data-cite="spec-shortname">
We can now link to <a>fancy thinga> in another spec.
p>
9.6
informative
๐ Edit<section class="informative">
<h2>A bit of history!h2>
<p>A really cool thing is that ...p>
section>
9.7
issue
๐ Editgithub
configuration option, you can easily reference GitHub issues in your spec as:<div class="issue" data-number="363">div>
issue-summary
.9.8
lint-ignore
๐ Editlint-ignore
can be used to:
no-unused-dfns
linter is enabled. This class attribute has to be added to the element.
informative-dfn
linter is enabled. This class attribute has to be added to the link.9.9
no-link-warnings
๐ Edit element stops ReSpec from warning you if you have missing links.
<pre class="idl no-link-warnings">
dictionary PointerEventInit: MouseEventInit {
long pointerId = 0;
double width = 1;
};
interface PointerEvent: MouseEvent {
constructor(DOMString type, optional PointerEventInit eventInitDict);
readonly attribute long pointerId;
readonly attribute double width;
};
pre>
9.10
nohighlight
๐ Edit<pre class="nohighlight">
function foo(){
const a = "foo!";
}
pre>
<pre>
function foo(){
const a = "foo!";
}
pre>
9.11
nolinks
๐ Edit<pre class="nolinks">
Prevents the following from becoming a hyperlink: https://example.com
pre>
9.12
note
๐ Edittitle
attribute will be interpreted as HTML markup. See title
attributes for details.<p class="note" title="Always rely upon native semantics">
Remember - if you are using the <code>rolecode> attribute to say that a
paragraph is a button, you are probably doing it wrong!
p>
9.13
notoc
๐ Edit<section class="notoc" id="mySection">
<h1>Some section I do not want in the ToCh1>
...
section>
noTOC
configuration option.9.14
numbered
๐ Edit9.15
override
๐ Editoverride
css class allow spec editors to completely override a section that would normally be dynamically filled with ReSpec generated content.
<section id="sotd" class="override">
<h2>Status of this documenth2>
<p>Exploring new ideas...p>
section>
9.16
permission
๐ Editpermission
class is used to define a browser permission.<p>
The Geolocation API is a default powerful feature identified by the
name `<dfn class="permission">"geolocation"dfn>`.
p>
9.17
practice
๐ Edit<div class="practice">
<p class="practicedesc">
<span class="practicelab">Best practicespan>
Practice makes perfect, but perfect is the enemy of the good.
p>
div>
9.18
practicedesc
๐ Edit<div class="practice">
<p class="practicedesc">
<span class="practicelab">Best practicespan>
Practice makes perfect, but perfect is the enemy of the good.
p>
div>
9.19
practicelab
๐ Edit containing the title of a best practice, inside a
.
<div class="practice">
<p class="practicedesc">
<span class="practicelab">Best practicespan>
Practice makes perfect, but perfect is the enemy of the good.
p>
div>
9.20
remove
๐ Edit<div class="remove">
<p>This will be removed at build time.p>
div>
9.21
removeOnSave
๐ EditremoveOnSave
class to it.<div class="removeOnSave">
<p>This will be removed at export time.p>
div>
9.22.1
updateable-rec
๐ Editclass="updateable-rec"
on the Status of This Document indicates the specification intends to allow new features once it becomes a W3C Recommendation. This will include the appropriate boilerplate text for you.
<section id="sotd" class="updateable-rec">
<p>Other status related stuff here...p>
section>
10.1
data-abbr
๐ Editdata-abbr
can be used on dfn
elements that are used as abbreviations throughout your spec.10.2
data-cite
๐ Editxref
whenever possible.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. and
elements:
spec-id[optional "/" path-to-document]#fragment
<a data-cite="rfc2119#some-section">some texta>
<dfn data-cite="spec/some.html#fragment">some texta>
10.3
data-dfn-for
๐ Editdata-dfn-for
attribute links a WebIDL attribute or method to a definition.bar
attribute and the doTheFoo()
method to the Foo
interface.<section data-dfn-for="Foo" data-link-for="Foo">
<h2><code>Foocode> interfaceh2>
<pre class="idl">
interface Foo {
attribute Bar bar;
void doTheFoo();
};
pre>
<p>The <dfn>Foodfn> interface is nice. Lets you do stuff.p>
<p>The <dfn>bardfn> attribute, returns ๐บ.p>
<p>The <dfn>doTheFoo()dfn> method, returns nothing.p>
section>
10.4
data-dfn-type
๐ Editdata-dfn-type
attribute on 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. has a
data-dfn-for
context, data-dfn-type
is treated as "idl"
. Otherwise, it is to be "dfn"
."idl"
and "dfn"
are supported. In future, more values might be supported.<p>
The document has visibility state of
<dfn id="dfn-hidden" data-dfn-type="dfn">hiddendfn>.
p>
<p>
`visibilityState` attribute has value
<dfn id="idl-hidden" data-dfn-type="idl">hiddendfn>.
p>
<p>
{{ hidden }} links to dfn with id="idl-hidden". This is same
<a data-link-type="idl">hiddena>, but above syntax is preferred.
p>
<p>
[= hidden =] links to dfn with id="dfn-hidden". This is same
<a data-link-type="dfn">hiddena>, but above syntax is preferred.
p>
10.5
data-format
๐ Editdata-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.10.6
data-include
๐ Editdata-include
attributes on included content will work as you expect. Though, for performance reasons, nested includes are supported only up to a maximum depth of 3.<section data-include="section/theFooElement.html">section>
data-include
, make sure you open your document with a static HTTP server running locally (i.e. don't open file:///
URL, but http://
or https://
), otherwise you'll get a network error.10.7
data-include-format
๐ Edit"text"
."markdown"
as attribute value. The default value is "html"
.<section
data-include="some.txt"
data-include-format="text">
section>
10.8
data-include-replace
๐ Edit element, the
.
<div data-include="section.frag" data-include-replace="true">
div>
10.9
data-link-for
๐ Editdata-link-for
attribute allows you to link to a definition with same data-dfn-for
value.<p>
<dfn>bardfn> is a global definition.
<a>bara> links to bar.
Prefer using [= bar =] syntax for linking.
p>
<p>
<dfn data-dfn-for="Foo">bardfn> is defined in scope of "Foo".
<a data-link-for="Foo" data-link-type="dfn">bara> links to `bar` in scope of `Foo`.
Following syntax is preferred: [= Foo/bar =]
p>
<p>
<dfn data-dfn-type="idl" data-dfn-for="Foo">bardfn> is defined in scope of "Foo".
<a data-link-for="Foo" data-link-type="idl">bara> links to `bar` in scope of `Foo`.
Following syntax is preferred: {{ Foo/bar }}
p>
data-link-for
attribute also allows you to link to one or more aspects of an interface at once.Request
's definition of url, but not Response
's.<pre class="idl">
interface Request {
readonly attribute USVString url;
};
interface Response {
readonly attribute USVString url;
};
pre>
<p data-dfn-for="Request">
The <dfn data-lt="clone()">clonedfn> method.
The <dfn>urldfn> attribute.
p>
<p data-link-for="Request">
Links to <a>clone()a> method.
Links to the <a>urla> attribute.
p>
10.10
data-link-type
๐ Editdata-link-type
attribute allows following values:
"dfn"
, "idl"
: See data-dfn-type
"biblio"
: Automatically added on bibliographic references through [[spec]]
syntax.10.11
data-local-lt
๐ Editlt
"s) to a defined term by using the data-lt
.export
a definition, you might want some shorthands to not be exported. In such a case, you can use data-local-lt
.
<dfn
class="export"
data-local-lt="installation|installing"
data-lt="installed web application"
>installeddfn>
<a>installed web applicationa>
[=installed=]
<a>installinga>
[=installation=]
10.12
data-lt
๐ Editdata-lt
allows you to define alternative terms for a definition (or link to a definition using an alternative name). This is great for some other variant that does not exactly match the dfn
. Each term is separated by a |
.<dfn data-lt="best fruit|fruits of the gods">Appledfn>...
<a>best fruita>
<a>fruits of the godsa>
[=fruits of the gods=]
pluralize
and data-local-lt
.10.13
data-lt-no-plural
๐ Edit, you can make use of
data-lt-no-plural
attribute like:<dfn data-lt-no-plural>htmldfn>
10.14
data-lt-noDefault
๐ Edit<dfn>The Foodfn>
<dfn data-lt="other foo" data-lt-noDefault>The Foodfn>
10.15
data-max-toc
๐ EditmaxTocLevel
.<section data-max-toc="2">
<h2>Section 1h2>
<section>
<h2>Section 1.1h2>
<section>
<h2>Section 1.1.1 (skipped)h2>
section>
section>
section>
data-max-toc=0
is equivalent to adding a notoc
class to current section:<section data-max-toc="0">
<h2>I'm skipped from ToCh2>
section>
10.16
data-number
๐ Editgithub
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.<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.17
data-oninclude
๐ Edit
<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>
<section
data-oninclude="toRainbows replaceUnicorns"
data-include="content.fragment"
>section>
10.18
data-sort
๐ Editdata-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.data-sort
and exclude the attribute value, and it will default to "ascending" (i.e., from A-to-Z).Regular list๐ Edit
<ul data-sort="descending">
<li>Wli>
<li>Zli>
<li>Ali>
ul>
<ul>
<li>Zli>
<li>Wli>
<li>Ali>
ul>
Definition list๐ Edit
dd
s for any dt
are also moved, but not sorted.<dl data-sort>
<dt>Bananasdt>
<dd>Are the best!dd>
<dt>Zebradt>
<dd>Are quite stripy.dd>
<dt>Applesdt>
<dd>๐s are delicious.dd>
<dd>๐s are great in a pie!.dd>
dl>
<dl>
<dt>Applesdt>
<dd>๐s are delicious.dd>
<dd>๐s are great in a pie!.dd>
<dt>Bananasdt>
<dd>Are the best!dd>
<dt>Zebradt>
<dd>Are quite stripy.dd>
dl>
10.19
data-tests
๐ Editdata-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.data-test
works together with the testSuiteURI
config option, so it must be present or ReSpec will yell at you. and
elements.
<script>
var respecConfig = {
testSuiteURI: "https://wpt.fyi/payment-request/",
};
script>
<p data-tests="test-1.html, test-2.html">
The user agent MUST do this stuff...
p>
10.20
data-type
๐ Edit to declare a variable's type.
|variable:type|
is a shorthand for variable
.|variable:type|
syntax accepts fewer characters than the HTML syntax, so, for example, a variable typed as "valid" or "invalid"
will need to use the HTML syntax.10.21
dir
๐ Editdir
attribute of the HTML element to ltr
. If you are writing in a language that requires a different directionality, simply set this attribute to another value.<html dir="rtl">html>
10.22
lang
๐ Editlang
attribute on element to "en" (English). If you are writing in another language, simply set this attribute to another value.
html>
<html lang="fr">html>
11.1
๐ Edit
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
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
12.1
document.respec
๐ Editrespec
object to the document
object which contains following properties:document.respec.ready
๐ Editdocument.respec.ready
.<script>
// Wait until resources have loaded, including ReSpec
document.addEventListener("load", function () {
document.respec.ready.then(function () {
// Do things
});
});
script>
document.respec.errors
{#document.respec.errors}๐ Editmessage
and the plugin
name where that error occurred. See RespecError
for all available fields and their details.document.respec.warnings
{#document.respec.warnings}๐ Editdocument.respec.errors
, but contains warnings instead of errors.document.respec.toHTML()
{#document.respec.toHTML}๐ Edit13.1
addPatentNote
(Deprecated)๐ Edit13.2
processVersion
๐ EditprocessVersion
was removed from v19.5.0
onwards.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,
};
13.3
tocIntroductory
๐ Edit.notoc
CSS class instead.13.4
wg
๐ Editgroup
option instead.13.5
wgId
๐ Editgroup
option instead.data-deliverer
attribute in the Status of this Document section.var respecConfig = {
wgId: 107714,
};
13.6
wgPatentURI
๐ Editgroup
option instead.13.7
wgURI
๐ Editgroup
option instead.A. ReSpec Ecosystem๐ Edit
xref
.caniuse
feature.wpt-tests-exist
B.
Person
๐ Editeditors
, authors
)
contains the following fields (most of the fields are straightforward). Only the
name
property is required.{
name: "Ben De Meester",
company: "Ghent University - iMinds - Data Science Lab",
companyURL: "https://www.iminds.be/",
url: "https://users.ugent.be/~bjdmeest/",
orcid: "0000-0003-0248-0987",
w3cid: "00000"
};
name
๐ Editurl
๐ Editcompany
๐ EditcompanyURL
๐ Editw3cid
๐ Editorcid
๐ EditretiredDate
๐ Editnote
๐ Editextras
๐ EditExtras๐ Edit
{
name: "Ben De Meester",
extras: [
{
name: "Some custom thing",
href: "https://example.com/",
class: "css-class-value"
}
]
};
name
(required)๐ Editspan
; this can contain html elements.class
๐ Edithref
๐ EditC. Common Errors๐ Edit
Couldn't match TERM to anything in the document or in any other document cited in this specification๐ Edit
xref
's specs.
should have a "export" css class.
data-cite
attribute to reference those terms.
data-link-for
.
data-link-for
.git clone [emailย protected]:speced/respec.git
pnpm
v8+. You can "install" pnpm
with corepack
as:corepack enable
corepack prepare --activate # run this from repository root
pnpm install
pnpm start --browser Chrome
Document
loads. These JavaScript fragments are referred to as "plugins". When a bunch of plugins are combined together, they create a "profile".profiles/w3c.js
, loads the following plugins (not the full list, just for illustrative purposes):
core/base-runner
plugin.profile/w3c.js
for the actual details of how the profile is set up. But it's essentially:
core/base-runner
), is actually the "brains" of ReSpec: it is the thing that "runs" all other plugins in order.document
object:// The following only resolves once all plugins have run
// and ReSpec has finished doing whatever it needs to do.
document.respec.ready;
.runAll(arrayOfPlugins)
method. For each plugin, it waits until a plugin has finished doing its work before continuing to the next plugin. It does this by calling the run()
function exported from a plugin, and await
ing for that function to finish. Some plugins may export a Plugin
class with a run()
method instead.respec.ready
promise on the Document object.document.respec.ready.then(() => {
console.log("ReSpec has finished processing this document");
});
preProcess
or postProcess
properties on the configuration object. See preProcess
and postProcess
more details and for examples.run()
function that is called asynchronously.// import other things you need
import utils from "core/utils";
// This part runs synchronously and an indeterminate order.
// do any plugin specific setup here. Note, the document
// can be in an unstable state here - so don't manipulate
// the DOM here!
// Optionally, export "run" function
// See below for description of arguments.
export async function run(conf) {
if ("something" in conf || document.querySelector("#important-element")) {
await someAsyncTask();
}
}
async function someAsyncTask() {
// Your code here
}
conf
: is the ReSpec configuration object (window.respecConfig
) - which the user defined. Be careful not to modify this object.showWarning
utility.import { showWarning, showError } from "./core/utils.js";
export async function run(conf) {
if (!"something" in conf) {
showWarning("Some error message", "plugin-name");
// You can pass additional details like a `hint` how to fix, list of `elements` that caused the issue etc.
// See showWarning and showError in core/utils.js
}
}
start
script in package.json contains the commands useful during development. It runs a static HTTP server, watches files for change and re-build the profile, and run unit tests.pnpm start
.
If you wish not to run tests and other parts of start script, you can alternatively run pnpm run server
.pnpm start --browser Firefox
browsers
value above to any of: Firefox, FirefoxHeadless, Chrome, ChromeHeadless, Safari. Same can be set using the BROWSERS
environment variable:BROWSERS="ChromeHeadless Firefox" pnpm start
fdescribe()
, fit()
) to see how to run only specific tests when running pnpm run karma
. This will save you a lot of time and pain.pnpm start --grep="SEO"
run start
in "interactive" mode. This gives you more control over when tests are run and, by default, turns off automatic file watching.pnpm start --interactive
--grep
to test just what you want, when you want.pnpm start --browser FirefoxHeadless
# or use ChromeHeadless
pnpm start
for more options.
node ./tools/builder.js YOUR-PROFILE-NAME
. That will generate a bundle in the build directory.examples/
, make a copy of "basic.html" and point the tag at your new profile. Now run:
pnpm start --profile YOUR_PROFILE_NAME --browser Chrome
http://localhost:8000/examples
and have play with your custom profile.tests/spec/YOUR-PROFILE-NAME/
. And then run:pnpm start --interactive --profile=YOUR-PROFILE-NAME --browser Chrome
src.html
is available
in the
respec-web-services repository.