# Bikeshed Documentation

## Living Standard, 19 December 2025

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.

## Conformance

Conformance requirements are expressed with a combination of descriptive assertions and RFC 2119 terminology. The key words “MUST”, “MUST NOT”, “REQUIRED”, “SHALL”, “SHALL NOT”, “SHOULD”, “SHOULD NOT”, “RECOMMENDED”, “MAY”, and “OPTIONAL” in the normative parts of this document are to be interpreted as described in RFC 2119. However, for readability, these words do not appear in all uppercase letters in this specification.

All of the text of this specification is normative except sections explicitly marked as non-normative, examples, and notes. [RFC2119]

Examples in this specification are introduced with the words “for example” or are set apart from the normative text with `class="example"`, like this:

This is an example of an informative example.

Informative notes begin with the word “Note” and are set apart from the normative text with `class="note"`, like this:

Note, this is an informative note.