static snapshots

Creating Static Snapshots

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

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

Using Browser

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

Using Spec Generator service

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

curl -F "[email protected]" https://labs.w3.org/spec-generator/ > index.html

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

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

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

curl -F "[email protected]" -F "shortName=dahut" -F specStatus="ED" \
     -F "publishDate=2020-02-21" https://labs.w3.org/spec-generator/ > index.html

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

Using CLI

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

To install the CLI, run:

npm install --global respec

Then use the CLI to generate a snapshot as:

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

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

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

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

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

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

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

For more options, run respec --help.