Bikeshed is a spec preprocessor, allowing you to write specs in a much more convenient source format than raw HTML, and have the full spec with all the boilerplate and other features (table of contents, etc) automatically generated for you.
Bikeshed is maintained on GitHub, and the documentation there describes the full suite of features, which are very useful.
Bikeshed can be easily installed and run locally (requiring no network access unless you're updating the processor or its databases), or accessed as a CGI without any installation at all: https://api.csswg.org/bikeshed/
See https://github.com/tabatkins/bikeshed#bikeshed-a-spec-preprocessor for more details.
You'll most likely be editing a file called:
that you'll need to turn into (and update in place when it's already there)
by running Bikeshed before committing your work.
(If you're not generating a spec for the CSSWG, the filename might be something else, like
index.bs turning into
Bikeshed's install instructions are designed for installing on a Debian Linux system, like Ubuntu. I know that people have installed Bikeshed on Mac systems, but they haven't recorded their steps; if you're feeling adventurous, please install it and send me the instructions!
Once it's installed, just go to the spec's source folder and type:
Further instructions and tips can be found in the Bikeshed README.
If you're on a system with curl on it, just save the following line to a file somewhere in your executable path:
curl https://api.csswg.org/bikeshed/ -F file=@Overview.bs -F force=1 > Overview.html
Mark the file as executable, then just run it from within the folder of the spec you're working on. It will automatically submit
Overview.bs to the post-processor and save the results to
Overview.bsfile on your local machine that you want to post-process (you should do this when you're ready to check it in). (Alternately, paste in your source text, or enter the URL of the source file, if it's already been committed.)
Overview.html(without the quotes), and save it right next your
Overview.bs- you'll likely be replacing an older version, that's ok, go ahead and confirm (command-R in the replace dialog).
If you get an error:
Error running preprocessor, returned code: 1. [1;31mFATAL ERROR:[0m The document requires at least one metadata block.
See https://github.com/tabatkins/bikeshed/blob/master/docs/metadata.md for how to create a metadata block for your spec.