# Bikeshed Documentation

## Living Standard, 19 December 2025

### 1.1. Using Bikeshed Without A Local Install

#### 1.1.1. Via the Web

If you use Bikeshed infrequently, and are okay with requiring a network roundtrip every time you invoke Bikeshed, you probably want to use the Bikeshed API instead. In return, the API version is always up-to-date, so you don’t have to remember to update things yourself. See § 2 Invoking Bikeshed Without Installing for options.

Note: The remote API has several limitations; most notably, it can’t take multiple files. If you are using custom boilerplates, or include files, you’ll have to run Bikeshed yourself.

#### 1.1.2. Via `pipx`

If you use Bikeshed infrequently, but have the prereqs for a local install (a recent Python 3, and `pipx`; see below), you can run an always-up-to-date Bikeshed locally as:

    pipx run bikeshed update && pipx run bikeshed

    # on subsequent invocations, just call:
    pipx run bikeshed

This does not have the limitations of the web version; you can use all the features of Bikeshed, including custom boilerplates and include files, or alternate run modes like `bikeshed watch`.

Note: This actually creates a temporary local install, which automatically disappears after a few days. It does not add the `bikeshed` command to your PATH. However, it generally won’t require manual upgrading; so long as it’s been long enough for `pipx` to delete the cached version, it’ll always grab the newest version of Bikeshed.

### 1.2. Prereqs

Bikeshed is a Python program, and getting Python working well in modern systems has a few (pretty easy) steps. (These might already all work for you!)

#### 1.2.1. `python3`

Bikeshed requires Python 3.12 or later. (It’s currently tested up to 3.14.)

To tell what version you have, run:

    python3 --version

If it reports 3.12.0 or later, you’re fine.

If it’s earlier, you’ll need to update your local Python version. There are several ways to do so, but I recommend `pyenv` as a safe and easy method.

https://github.com/pyenv/pyenv#installation gives instructions for installing pyenv on various environments. It also links to the auto-installer, which can make things even easier. Windows users have slightly different instructions, but it links to a windows fork as well.

If you know your way around pyenv already, feel free to do what you’re used to here. Otherwise, it’s probably easiest to just set up 3.14.1 as your "default" Python:

    pyenv versions

will list what versions exist, and then

    pyenv global 3.14.1

will set 3.14.1 as your "global" version, used by default. (Substitute in whatever the name of the version you saw in `versions` was.)

#### 1.2.2. `pipx`

Installing packages globally is usually a bad (and sometimes insecure!) idea. They should instead be isolated into "virtual environments". This used to be a little tricky to set up, but now `pipx` makes it very simple.

To install pipx, your system software distribution might already have it; for example, distributions using `apt` can run

    sudo apt-get install pipx

If this is not the case for you, see pipx’s install instructions and do whatever it says.

### 1.3. Installing Bikeshed Itself

#### 1.3.1. Installing For Normal Use

Assuming the prereqs (above) are satisfied, installation is trivial:

    pipx install bikeshed

When this is completed, Bikeshed should be installed, and the `bikeshed` command should work in your shell.

Note: If this is your first time running `pipx`, you might get a message complaining about your PATH variable, and Bikeshed’s attempt to update its data files will fail. If so, follow `pipx`’s instructions, then run `bikeshed update` again.

After this, invoking Bikeshed is just:

    cd ~/my-spec-folder
    bikeshed

Remember to update Bikeshed regularly by running:

    pipx upgrade bikeshed

See § 1.4 Updating Bikeshed for more details.

You can also manually refresh Bikeshed’s datafiles by running:

    bikeshed update

But this will run automatically whenever you use Bikeshed if your data files are more than a few days old, so it usually shouldn’t be necessary.

##### 1.3.1.1. OpenSSL warning on Macs

If you’re on a Mac, you might see a warning about urllib3 not supporting LibreSSL, looking something like:

`/python-path-here/site-packages/urllib3/__init__.py:35: NotOpenSSLWarning: urllib3 v2 only supports OpenSSL 1.1.1+, currently the 'ssl' module is compiled with 'LibreSSL 2.8.3'. See: https://github.com/urllib3/urllib3/issues/3020`

This is a known issue with old system-installed Python version on Macs. To silence this, install Python 3.12 (or higher) with Brew instead. (Or install OpenSSL and regen your venv, or a number of other ways suggested in the urllib3 issue thread.) However, it’s likely fine to leave it alone, if you can ignore the warning yourself.

#### 1.3.2. Installing Bikeshed for Development

If you’re installing Bikeshed so you can work on it, or want to ensure you have the bleeding-edge tip-of-tree version, the instructions are just a tiny bit more complex.

First, clone the Bikeshed repository:

    git clone https://github.com/speced/bikeshed.git

Then navigate to that folder (by default, it’ll be a folder called "bikeshed" in the current folder you’re in) and run:

    pip3 install -e .

This will spam your console with a bunch of install progress. When it successfully completes, the `bikeshed` module should be globally available for import in Python, and a `bikeshed` command should now work in your shell.

##### 1.3.2.1. Installing With Pipenv

You probably don’t want to install all of Bikeshed’s dependencies globally, so I recommend using `pipenv` to install it into a virtual environment (similar to what `pipx` does for non-dev installs).

Follow the same instructions as above, but instead of running `pip3 install`, run:

    pipenv install --dev -e .
    pipenv run bikeshed update

This will not install a `bikeshed` command by default; instead, you run Bikeshed with `pipenv run bikeshed`. If you’d like `bikeshed` to work by itself, either start a pipenv shell with `pipenv shell`, or add an alias to your machine like:

    bikeshed=pipenv run bikeshed

### 1.4. Updating Bikeshed

To update bikeshed to its latest version at any time, just run:

    pipx upgrade bikeshed && bikeshed update

This’ll pull the latest version of Bikeshed, and ensure that you’re looking at the latest version of the data files, rather than whatever stale version is currently sitting in the repo.

Note: If you did an "editable" install up above, to update it you just run the install command again and invoke `bikeshed update` afterwards.

### 1.5. Building a Bikeshed docker image

Note: I don’t actually understand Docker or know how to use it, so this guide is based on one community member’s efforts. If something is wrong or outdated, uh, figure out how to fix it and tell me so I can fix the docs.

- If needed, download and install docker community engine

- Build the Bikeshed image from the project’s directory:

      docker build --tag=bikeshed:latest .

  The above command will cache Bikeshed’s datafiles in the Docker layer cache, in order to speed up rebuilds. If you want to be sure you get the latest datafiles, run `bikeshed update` in the container or add the `--no-cache` flag when building the image:

      docker build --tag=bikeshed:latest --no-cache .

- Optionally, deploy the Bikeshed image to a docker registry

  For example, on a unix system (for Windows, consider the Windows Subsystem for Linux):

      TAG=$(docker image inspect --format='{{.Id}}' bikeshed:latest)
      DATE=$(date '+%Y.%m.%d')

  Login to a docker registry.

      docker login

  Tag the image to be pushed as organization/artifact:version

      docker tag $TAG <organization>/bikeshed:$DATE

  Push the tagged image to the docker registry

      docker push <organization>/bikeshed:$DATE

#### 1.5.1. Invoking Bikeshed using a docker image

Note: As stated up in § 1.5 Building a Bikeshed docker image, I don’t know how Docker works and this guide is based on a community member’s experience, so use at your own risk.

Typically, this requires login to the docker registry and pulling a Bikeshed image.

For some `<organization>` and some `<date>`:

    docker login
    docker pull <organization>/bikeshed:<date>

Regardless of host environment’s operating system, running Bikeshed from a docker image requires two things:

- mapping a host directory to a path in the docker image (e.g. `/data`)

- specifying the location of Bikeshed’s input and output relative to the path in the docker image (i.e., `/data`)

Example for a Unix host:

    docker run --rm -v $(pwd):/data <organization>/bikeshed:<date> bikeshed spec /data/<some *.bs file> [/data/<some output file>]

Example for a Windows host:

    docker run --rm --volume C:\mystuff\project1\:/data <organization>/bikeshed:<date> spec /data/Index.bs /data/out/Index.html

Note that the § 3.1 Global Options apply to running Bikeshed from a docker image. Since the Bikeshed docker image is read-only, it does not make sense to execute the Bikeshed `update` command from a docker image.

## 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.