Working with ReSpec

ReSpec is a tool for writing technical specifications as ordinary HTML. You write a source HTML file, add a small configuration object, and ReSpec turns it into a formatted specification with title, table of contents, section numbering, references, definitions, cross-links, notes, and export tools.

This guide walks through the basics needed to create and preview a ReSpec document.

Create a minimal ReSpec file

Start with an HTML file such as index.html.

<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="utf-8">
  <title>My First Document</title>

  <script
    src="https://www.w3.org/Tools/respec/respec-w3c"
    class="remove"
    async></script>

  <script class="remove">
    var respecConfig = {
      specStatus: "ED",
      editors: [
        {
          name: "Your Name",
          url: "https://example.com/"
        }
      ],
      shortName: "my-first-spec",
      github: "w3c/my-first-spec",
      group: "i18n",
      canonicalURI: "TR",
      license: "w3c-software-doc"
    };
  </script>
</head>
<body>
  <section id="abstract">
    <p>This document defines a small example specification.</p>
  </section>

  <section id="sotd"></section>

  <section>
    <h2>Introduction</h2>
    <p>This is where the document begins.</p>
  </section>

  <section id="conformance"></section>
</body>
</html>

The two script elements are important. The first loads ReSpec, and the second tells ReSpec how to build the document.

Use var respecConfig, not const or let. ReSpec reads the configuration from window.respecConfig.

The class="remove" attribute tells ReSpec to remove those authoring scripts from exported static HTML.

Preview the document locally

Do not open the file directly with file://. Use a local HTTP server instead.

If you have Python, you can run the following command from the directory containing your file:

python3 -m http.server

Then open:

http://localhost:8000/

Serving the file over HTTP matters because ReSpec may fetch references, cross-reference data, issue information, includes, or other resources.

Understand the basic configuration

A small configuration usually starts like this:

var respecConfig = {
  specStatus: "ED",
  editors: [{ name: "Your Name" }],
  shortName: "my-spec",
  github: "w3c/repo",
  group: "i18n"
};

Common beginner options:

specStatus: the publication status. Use "ED" for an Editor's Draft while writing.
editors: the people editing the document. Most W3C documents require at least one editor.
shortName: the short identifier for the document.
github: the repository used for feedback.
group: the W3C group responsible for the document.

Write sections

ReSpec documents are HTML documents. Use section elements with headings.

<section>
  <h2>Concepts</h2>
  <p>A <dfn>widget</dfn> is an object managed by this specification.</p>

  <section class="informative">
    <h3>Background</h3>
    <p>This section gives non-normative background information.</p>
  </section>
</section>

ReSpec automatically numbers sections and builds a table of contents. If your document is normative, use class="informative" for explanatory material that is not normative.

If you link to a section with an empty link, ReSpec fills in the section number and title automatically:

<p>See <a href="#concepts"></a>.</p>

Define and link terms

Use dfn to define a term:

<p>A <dfn>request</dfn> represents a pending operation.</p>

Then link to it later:

<p>Each [=request=] has a state.</p>

You can also use a plain HTML link:

<p>Each <a>request</a> has a state.</p>

If a term has multiple names, use data-lt:

<p>A <dfn data-lt="user agent|browser">user agent</dfn> loads the page.</p>

Now [=user agent=] and [=browser=] link to the same definition.

Link to other specifications

ReSpec can link to terms defined in other specifications. Enable cross-reference support in the configuration:

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

Then use ReSpec shorthand:

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

Common shorthand forms:

Shorthand	Purpose
`[=term=]`	Link to a concept or definition.
`{{Interface}}`	Link to a WebIDL interface.
`{{Interface/member}}`	Link to a WebIDL attribute or method.
`[^element^]`	Link to an HTML or SVG element.
`[[HTML]]`	Add an informative reference.
`[[!RFC2119]]`	Add a normative reference.

If ReSpec cannot find a cross-reference, it shows a warning or error in the rendered document.

Add references

<p>The [^link^] element is defined in [[HTML]].</p>
<p>Conforming implementations MUST follow [[!RFC2119]].</p>

Use [[SPEC]] for an informative reference, and [[!SPEC]] for a normative reference.

ReSpec generates the references section automatically.

Add examples, notes, issues, and figures

Use notes for helpful explanations:

<aside class="note" title="Implementation note">
  <p>Implementations should handle network failure.</p>
</aside>

Use examples for sample code or concrete scenarios:

<aside class="example" title="Using the API">
  <pre class="js">
const result = await doSomething();
  </pre>
</aside>

Use issues for open editorial or technical questions:

<p class="issue">
  Decide whether this algorithm should reject or resolve.
</p>

Use figures with captions:

<figure id="fig-overview">
  <img src="overview.svg" alt="System overview diagram">
  <figcaption>System overview.</figcaption>
</figure>

<p>See <a href="#fig-overview"></a>.</p>

ReSpec can number figures and fill in empty links to figures.

Use Markdown if it helps

ReSpec can treat the whole document body as GitHub Flavored Markdown:

var respecConfig = {
  format: "markdown"
};

When using this mode, keep Markdown content aligned to the left margin because Markdown is whitespace-sensitive.

You can also include a Markdown file in one section:

<section data-include="my-section.md"
         data-include-format="markdown"></section>

HTML and Markdown can be mixed, but leave blank lines around Markdown content inside HTML elements.