# Bikeshed Documentation

## Living Standard, 19 December 2025

Bikeshed’s custom text formats attempt to be fairly regular; most of them involve specifying key/value pairs, and are line-based. For example, Bikeshed’s metadata format is one key/value pair per line, with a colon between the key and the value.

The InfoTree format, used by several things in Bikeshed, is similar. It’s used when you need to specify data consisting of multiple key/value pairs, where it’s common that multiple entries share some of that data. The InfoTree format makes this easy to read, write, and maintain.

### Specifying Information on a Single Line

The simplest way to provide a piece of information is by putting all the key/value pairs on a single line. In the InfoTree format, this is done by putting a colon between the key and value, and separating the pairs with semicolons. For example, here is an example of two "anchor" entries:

    urlPrefix: https://encoding.spec.whatwg.org/; type: dfn; text: ascii whitespace
    urlPrefix: https://encoding.spec.whatwg.org/; type: dfn; text: utf-8

This specifies two entries, each with three keys: urlPrefix, type, and text.

### Nesting Information to Share Pieces

When multiple pieces of information share some key/value pairs, you can use nesting to indicate this, so you don’t have to repeat yourself. Here’s the same two entries as before, but using nesting to share their common information:

    urlPrefix: https://encoding.spec.whatwg.org/; type: dfn
      text: ascii whitespace
      text: utf-8

Just like the previous, this defines two entries, each with three key/value pairs. Now it’s clearer, though, that the two entries share their `urlPrefix` and `type` data, and you only have to maintain the common data in one place.

### Comments

A line that starts with a `#` character (with any amount of preceding whitespace) is a comment; it will be completely ignored for the purpose of parsing.

### Additional Details

The order that keys are specified in is irrelevant. Feel free to rearrange them for readability or more effective nesting.

You can specify the same key multiple times; the values will be collected into an array for later processing. (Each user of InfoTree will define whether multiple values for a key is valid or not, and what it means.) The order that the values appear in is preserved, as it might be important. (For example, in the anchor format, multiple urlPrefix values are concatenated together, to help specify urls in multipage specs.)

Additional semicolons are silently ignored; in other words, empty entries get dropped, so you can put a final semicolon at the end of the line or not, as you prefer.

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