Bikeshed Documentation

2. Invoking Bikeshed Without Installing

While a locally-installed Bikeshed does provide additional functionality, if all you need to do is process a spec, there is an API server you can talk to, maintained by Peter Linss.

2.1. Using Curl

These instructions assume use of the curl command, but you can use any equivalent "talk HTTP at a server" command you might have access to.

curl https://api.csswg.org/bikeshed/ -F file=@index.bs -F force=1 > index.html

Simplest possible usage:

passing the source as -F file=@index.bs
forcing output even if there are errors with -F force=1
piping the output to the desired filename with > index.html.

Additional possible arguments:

-F output=err to just receive errors, if any
-F md-Foo=bar to pass a Foo: bar metadata to the spec (same as passing --md-Foo=bar locally)
-F die-on=[nothing, fatal, link-error, warning, everything], (same as the --die-on local flag)

If your source file is online, such as in a git repository, you can pass the url directly instead:

curl http://api.csswg.org/bikeshed/ -F url=http://dev.w3.org/csswg/css-syntax/Overview.bs -F force=1 > Overview.html

If you are using additional files beyond your plain source file—local boilerplate files, sub-document includes, custom definition files, etc—this is the only way to make those still work via the curl API; Bikeshed will look for the additional files relative to the source document’s url.

(Any additional files that get included implicitly, such as local boilerplates, must be listed in the Local Boilerplate or External Infotrees metadatas to get picked up. Files explicitly listed in the source file, such as in a <pre class=include>, will be picked up automatically.)

The separate bikeshed issues-list command (for generating issues lists for a W3C Disposition of Comments) can also be invoked via curl:

curl http://api.csswg.org/bikeshed/ -F file=@Issues.txt -F input=issues > Issues.html

2.2. Using the Web Form

Alternately, you can just visit https://api.csswg.org/bikeshed/ directly, and upload a file, point to a URL, or directly paste in your spec source.

It defaults to outputting both the HTML and the errors, but you can switch it to one or the other only if you want.

2.3. Using CI Tools

2.3.1. Travis CI

To use bikeshed on Travis CI’s github integration, you’ll need the following .travis.yml commands:

language: python
python:
  - "3.12"
install:
  - pip install bikeshed
  - bikeshed update
script:
  # Invoke bikeshed here, at your own leisure. E.g.:
  - bikeshed spec

Raymond Toy has written a very thoro guide on the full setup you need to auto-build and -publish the generated files to GitHub via Travis, so you only need to check in the source files themselves.

2.3.2. GitHub Actions

The W3C maintains a spec-prod GitHub Action that allows automatically processing commits or PRs as either Bikeshed or ReSpec.

To use, add a file to .github/workflows/ folder in your GitHub project, containing:

name: CI
on:
  workflow_dispatch: {}
  pull_request: {}
  push:
    branches: [main]
jobs:
  main:
    name: Build, Validate and Deploy
    runs-on: ubuntu-latest
    permissions:
      contents: write
    steps:
      - uses: actions/checkout@v4
      - uses: w3c/spec-prod@v2
        with:
          TOOLCHAIN: bikeshed

          # Modify as appropriate
          GH_PAGES_BRANCH: gh-pages

          # if your doc isn't in the root folder,
          # or Bikeshed otherwise can't find it:
          SOURCE: src/spec.bs

          # output filename defaults to your input
          # with .html extension instead,
          # but if you want to customize it:
          DESTINATION: src/index.html

The linked document has a number of usage examples to achieve various outcomes—simple validation, auto-publishing on w3.org/TR, building multiple specs from a single repository, and some others. It also explains the entire process from start to finish, if you need more help setting things up.

To the extent possible under law, the editors have waived all copyright and related or neighboring rights to this work. In addition, as of 21 January 2026, the editors have made this specification available under the Open Web Foundation Agreement Version 1.0, which is available at https://www.openwebfoundation.org/the-agreements/the-owf-1-0-agreements-granted-claims/owfa-1-0. Parts of this work may be from another specification document. If so, those parts are instead covered by the license of that specification document.