Skip to content
🚲 A preprocessor for anyone writing specifications that converts source files into actual specs.
HTML Other
  1. HTML 99.1%
  2. Other 0.9%
Branch: master
Clone or download


Type Name Latest commit message Commit time
Failed to load latest commit information.
bikeshed Clarify the status of the TAG, and provide TAG boilerplate. (#1663) May 26, 2020
docs Add script to the not-yet-expired case to flip it after the expiry da… Apr 25, 2020
emacs [emacs] enable subword-mode for easy editing of camelCase terms. (#1653) Apr 23, 2020
tests Rebase tests due to the propdef link change. May 19, 2020
.gitignore Add a new script. Mar 20, 2020
.travis.yml Update Docker and CI config to use 3.7 (#1611) Mar 18, 2020
Bikeshed.tmLanguage Don't mark all other text as markup.raw; in the new ST3 color schemes… Sep 19, 2017 Improve CONTRIBUTING Mar 20, 2020
LICENSE add a license file dictating cc0 Mar 19, 2020 Add a new script. Mar 20, 2020
Pipfile Move widlparser and json_home_client to be pip-installed, and set up … Mar 19, 2020
Pipfile.lock Move widlparser and json_home_client to be pip-installed, and set up … Mar 19, 2020
appveyor.yml Update to python 3.7 Mar 19, 2020 Fix flake8 W391 blank line at end of file (#780) Aug 9, 2016 Put the new semver in the commit about bumping the semver. Apr 10, 2020
requirements.txt Update attrs from 17.3.0.dev0 to 19.3.0. (#1672) May 21, 2020
semver.txt Bump semver to 1.2.2 May 19, 2020
setup.cfg Yet more flake8 fixes (#784) Aug 11, 2016 Defer the requires list to requirements.txt Mar 21, 2020

Bikeshed, a spec preprocessor

Bikeshed is a pre-processor for spec documents, turning a source document (containing only the actual spec content, plus several shorthands for linking to terms and other things) into a final spec document, with appropriate boilerplate, bibliography, indexes, etc all filled in. It's used on specs for CSS and many other W3C working groups, WHATWG, the C++ standards committee, and elsewhere!

Build Status Gitter Docs

The processor can be easily installed and run locally (requiring no network access unless you're updating), or accessed as a CGI without any installation at all:

A short overview of some of Bikeshed's features:

Documentation Sections

The full Bikeshed documentation is generated by Bikeshed and accessible here.

Note About Fatal Errors

Bikeshed generates "fatal errors" for lots of things that it wants you to fix, but generally recovers gracefully from them anyway. If you're getting a fatal error, but don't have time to fix it and just need a spec right now, you can force Bikeshed to generate anyway with the -f flag, like: bikeshed -f spec.

This is also sometimes useful when converting a spec to Bikeshed for the first time, so you can see all the errors at once and fix them in whatever order is easiest, rather than having to deal with them one-by-one with no idea when they'll end. (You may also want to silence the warnings in this case, to reduce visual noise until you've gotten it at least building successfully. Use bikeshed -qf spec.)

Bikeshed File Extension

The preferred file extensions for Bikeshed source files is bs, like Bikeshed will automatically recognize *.bs files in the folder it's run in, and assume that you want an output file of the same name with a .html extension. The repository also contains a syntax highlighting script for Bikeshed source files.

(Bikeshed also recognizes files with *.src.html for backwards compatibility with older CSS specs, though most such specs have switched their source file extensions to .bs now. Using .src.html in most text editors will display the file with HTML source formatting, which isn't generally what you want.)


This document and all associated files in the github project are licensed under CC0 . This means you can reuse, remix, or otherwise appropriate this project for your own use without restriction. (The actual legal meaning can be found at the above link.) Don't ask me for permission to use any part of this project, just use it. I would appreciate attribution, but that is not required by the license.

You can’t perform that action at this time.