# ReSpec: writing W3C specifications from a plain HTML file

> ReSpec is a pre-processor for technical documents that runs in the browser, so a specification is written as ordinary HTML with a script tag and comes out formatted, cross-referenced, bibliographed and validated. The repository is the tool's own development, not something a spec author needs to clone, and its output still has to satisfy the W3C publication rules.

**speced/respec** — A tool for creating technical documents and web standards

- Repository: https://github.com/speced/respec
- Website: https://respec.org/
- Stars: 806 · Forks: 440
- Language: JavaScript
- License: NOASSERTION
- Published: 2026-10-20 · Updated: 2026-10-20 · Language: en
- Canonical page: https://hysenlabs.com/projects/speced-respec

## A pre-processor that runs where the document is

ReSpec is a tool for writing W3C specifications and other technical documents. You write your content in HTML, add a script tag, and ReSpec handles the boilerplate, the formatting, the cross-references, the bibliography and the validation automatically.

That list is the whole value proposition, and it is worth separating the items. Boilerplate is the front matter a specification needs: title, editors, the group's logo, the status of the document, the date. Formatting is the structure, the section numbering, the tables and the requirement boxes. Cross-references are the internal and external links, so that a reference to a section of your own document or to another specification resolves to the right target. Bibliography is the reference list, assembled from the specifications you cited. Validation is the check that the document is internally consistent, which is the part that saves the most time because it is the part that is tedious.

The package metadata describes it as a technical specification pre-processor, and that word is accurate. It does not replace your editor and it does not own your document. The source stays as HTML, and the transformation happens when the document is rendered.

The project is written in JavaScript, its licence is recorded as W3C, and the last push was on 2026-10-19 with version 37.4.1 released on 2026-10-02, after 37.4.0 in September and 37.3.6 at the start of it.

## No installation, and a starter document to copy

The claim at the top of the README is that you do not need to install anything: write an HTML file, open it in a browser, done.

That works because ReSpec is loaded into the page as a script and does its work client-side, which means the toolchain is the browser you already have. There is no local toolchain, no package to install and no build step between you and a rendered specification. The cost of that convenience is that the transformation happens in the page, so the raw HTML is not the finished document until the script has run.

For a starting point, the README points at the starter spec in the repository, at examples/starter.html, and the instruction is to change the title, add your name as editor and start writing. The full documentation is at respec.org/docs, with an editor's guide that the README calls a complete walkthrough for new spec editors, a WebIDL guide for JavaScript API specifications, and a How Do I wiki page with quick answers to common tasks.

The README is also explicit that the repository is for the development of ReSpec itself, and that you do not need to clone or fork it in order to write a specification. That distinction matters when you are evaluating the project, because what you are looking at is the tool's source, not a template you are meant to fork.

## Cross-references and the bibliography through specref

The part of ReSpec that most changes the working day of a spec editor is the handling of references, and it works through specref.org.

The README explains that specref is the service for looking up and citing other specifications, and that ReSpec resolves [[SPEC-ID]] references automatically. In practice that means you write a reference in double brackets with the identifier of the specification, and the pre-processor turns it into a proper citation with the right title, the right status and a link, without you maintaining a reference list by hand.

There is a second route in. The README notes that you can search specref directly from the ReSpec pill menu in any spec, so the tool you use to look up a specification is already in the page you are writing it.

For comparison, the manual approach to a bibliography in a specification means tracking the title, the shortname, the editor, the date and the URL of every document you reference, and correcting them when any of those change. Doing that for a document with fifty references is a maintenance task of its own, and it is the kind of task that specifications traditionally get wrong. Automating it is why a pre-processor exists at all.

The cross-reference machinery covers internal references too, so the numbered sections of the document you are writing are linked consistently rather than by hand-written section numbers that go stale when a section is inserted.

## Running it from a command line in CI

The browser is how an author works, but a published specification also has to be built by a pipeline, and the package exposes command line entry points for that. The package.json in the repository shows them:

```json
  "engines": {
    "node": ">=24"
  },
  "packageManager": "pnpm@12.10.0",
  "bin": {
    "respec": "tools/respec2html.js",
    "respec2html": "tools/respec2html.js"
  },
```

Both binaries point at the same script, tools/respec2html.js, which is the one that turns a document into HTML. The main entry point of the package is different, ./tools/respecDocWriter.js, which is the programmatic interface for writing a document rather than converting one. The package is an ES module, and it requires Node 24 or newer, with pnpm as its package manager and a pnpm workspace file in the repository.

The practical workflow is that an author edits the source and sees the rendered result in a browser, while the continuous integration job runs the command line version over the same file and publishes the result. That separation is why the tool can be both zero-install for a writer and scriptable for a pipeline, and it is the reason the node engine requirement is as high as it is.

## Inside the repository: profiles, builds, examples and browser tests

The tree shows how a pre-processor is put together, and a few directories carry meaning.

The src directory holds the sources, builds holds the bundled output, tools holds the command line scripts, worker holds the web worker code, profiles holds the configuration profiles, js holds older JavaScript, assets holds static files and examples holds sample documents. The examples directory is instructive because it contains the starter template alongside a basic document and its built counterpart, basic.html next to basic.built.html, which is the before and after of a transformation in two files, plus a dark mode example and a document from a 2019 TPAC event.

The testing stack is visible in the development dependencies. The suite runs under jasmine with karma as the runner, and karma is configured with launchers for Chrome, Firefox and Safari, which means the document transformation is verified in three real browsers rather than in a simulated DOM. There is also chokidar for watching files during development, rollup for bundling, prettier and eslint for formatting and linting, idb for IndexedDB access, highlight.js for syntax highlighting, and cddlparser for structured header parsing.

Around the code sit the governance files, and they are worth noting in a project that is frequently used by people outside its maintainers. There is a CODE_OF_CONDUCT.md, a CONTRIBUTING.md, a SECURITY.md, a CHANGELOG.md, a CLAUDE.md for assistant tooling, and both an AI_POLICY.md and an ai-pr-proof-requirement.md, the latter being the mechanism by which contributions produced with AI are required to carry proof that they were checked.

## The publication rules and the licence are separate contracts

Two statements in the README qualify everything else, and both are about accountability rather than about the tool.

The first is that ReSpec is not endorsed by W3C, and that for W3C publication requirements you should consult the W3C Publication Rules. In other words, using ReSpec does not make a document publishable. The publication rules are a separate contract that the document has to satisfy, and a tool that produces well-formed output is only addressing part of what a working group chair and the technical architecture committee will look at.

The second is the licence. The package metadata records the licence as W3C, a custom licence that GitHub cannot classify, with the terms in a LICENSE file at the root of the repository. The project also depends on the publication rules for what a document may contain, and on the W3C process for how a document is reviewed, so for a document intended for publication the relevant agreement is the one between your group and the W3C rather than the software licence alone.

The README also points at resources for people new to specification writing, and the list is a good description of what a spec author has to learn: the API design principles from the W3C technical architecture group, a guide to writing promise-using specifications for async patterns, a security and privacy self-review questionnaire to audit a specification before publishing, a short internationalisation review checklist, and the process for adding a new permission type. None of that is ReSpec's job, and all of it is required to produce a document that gets published.

## Where ReSpec is the wrong tool

The first limitation is the target format. ReSpec produces W3C-style technical documents, with the metadata, the section structure, the requirement boxes and the editorial conventions that process expects. A documentation site, a book, a tutorial or a blog post will not benefit from it, because the value of the tool is in producing output that matches a specific editorial standard, and that standard is not yours if you are not writing a specification.

The second is the audience. The documentation set assumes familiarity with specification conventions: the WebIDL guide is for JavaScript API specifications, the new-to-spec-writing list is about API design, permission models and internationalisation. A team that wants a lightweight way to produce a readable technical document will find the tooling fine and the surrounding expectations heavy.

The third is that the transformation happens in the browser for the author. There is no build step in the author's loop, which is a genuine advantage, but it also means that the source you edit is not the source that is published unless a pipeline runs the command line version, and the two paths can drift if the pipeline is not wired up.

The fourth is the boundary around contributions. The repository asks contributors to follow a code of conduct, a developer guide, and, if a contribution is produced with AI, an AI policy and a proof requirement. That is a reasonable governance model for a tool whose output carries institutional weight, and it is also a signal that contributions are reviewed rather than merged on request.

Finally, the help channel is a W3C mailing address, spec-prod@w3.org, for general questions, with bugs filed in the issue tracker. That is appropriate for the tool's actual users and means support is not a private channel.

## Maintenance, community and how the project is funded

The release history shows a project on a fast, regular cadence: v37.4.1 on 2026-10-02, v37.4.0 on 2026-09-10 and v37.3.6 on 2026-09-02, with the last push on 2026-10-19. The major version has been at 37 for a while, which in a pre-processor means the document format it emits has been stable for a long time, and the work now is in the details.

The named contributors in the package metadata give a sense of the project's centre: Marcos Cáceres, Kagami Sascha Rosylight, Sid Vishnoi and Robin Berjon, the last of whom is a long-standing figure in the W3C community. That list is the formal credit, and the README is explicit that the project exists thanks to all the people who contribute, pointing at a CONTRIBUTING file.

Funding runs through OpenCollective, with both backers and sponsors. The sponsors section explains what a sponsor gets, a logo and a link to their site, and the backers section is the mechanism for contributing money without a logo. For a tool whose users are largely individuals contributing their own time to standards work, a sponsorship page with a dozen entries is a reasonable signal of a sustainable maintenance budget.

The three entry points for using it are all worth keeping straight: the documentation at respec.org/docs, the editor's guide and WebIDL guide within it, and the How Do I wiki page for quick answers, with the W3C technical architecture group's API design principles and security questionnaire as the companion reading for anyone writing the document itself.

## Conclusion

Adopt ReSpec if you are writing a technical specification, especially a W3C one, and you want the structural work, the reference resolution and the document metadata handled for you while you keep the source in plain HTML. Do not adopt it for general documentation, because it targets the W3C specification format rather than a documentation site, and do not treat its output as publishable on its own. Verify first that your document uses the conventions ReSpec expects, that the references you cite are in specref, and that the result passes the W3C Publication Rules, since the README states plainly that ReSpec is not endorsed by W3C and the publication requirements are a separate contract.

## FAQ

### Do I need to install ReSpec to write a specification?

No. The README says you need to install nothing: write an HTML file, add a script tag and open it in a browser. The starter template at examples/starter.html is the recommended starting point, and the repository itself is only for the development of ReSpec.

### How does ReSpec handle citations of other specifications?

Through specref.org. You write a [[SPEC-ID]] reference and ReSpec resolves it automatically into a proper citation, and you can also search specref directly from the ReSpec pill menu inside any specification.

### Can ReSpec be run in a CI pipeline?

Yes. The package exposes respec and respec2html binaries, both pointing at tools/respec2html.js, with Node 24 or newer required and pnpm as the package manager, so a build job can produce the published document from the same source the author edits in the browser.

### Is a document produced with ReSpec ready to publish at W3C?

Not on its own. The README states that ReSpec is not endorsed by W3C and that you should consult the W3C Publication Rules for publication requirements, which are a separate contract from the tool.

## Sources

- [Issues](https://github.com/speced/respec/issues)
- [Project website](https://respec.org/)
- [README](https://github.com/speced/respec/blob/main/README.md)
- [Releases](https://github.com/speced/respec/releases)
- [speced/respec on GitHub](https://github.com/speced/respec)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/speced-respec