# Bikeshed Documentation

## Living Standard, 19 December 2025

Several types of definitions have well-established presentations, as a simple "key/value" table providing all of the details in a standardized format.

Bikeshed handles these specially, with a dedicated set of `<pre class=xxxdef>` blocks. The information in the block is presented in a simple line-based `Key: value` format, similar to `<pre class=metadata>`, and this is transformed into a standardized `table`.

All of the def tables look like this:

    <pre class='propdef'>
    Name: flex-basis
    Value: content | <<'width'>>
    Initial: auto
    Inherited: no
    Applies to: <a>flex items</a>
    Computed value: as specified, with lengths made absolute
    Percentages: relative to the <a>flex container's</a> inner <a>main size</a>
    Animation type: length
    Canonical Order: per grammar
    </pre>

### 9.1. Arbitrary Def Tables

If you want to display your own key/value rows in a similar way to the built-in types defined below, you can use a plain `<pre class=simpledef>` block.

    <pre class=simpledef>
    first row: some info
    second row: different info
    second row: merged with the previous row
    </pre>

will render as:

first row: | some info
second row: | different info merged with the previous row

Parsing is extremely simplistic:

- Each line defines a separate row.

- The first literal `:` character splits the "key" from the "value".

- Unique keys are displayed in order, with the key in a `<th>` and the value in a `<td>`.

- Repeated keys have their values merged (with a newline separating them, if that matters).

- HTML or Bikeshed markup can be used in both keys and values, like `<b>Key</b>: value&copy;`. The keys and values are both written literally into the document as the table, and then later parsed by Bikeshed as normal text.

  Note that the key/value splitting is done on the raw text, so a literal colon will trigger the split no matter where it appears: `<span title="behold: un pipe">what is it?</span>: a pipe` will parse the key as `<span title="behold`, and the value as everything following that first colon. Use `&#x3a;` to HTML-escape the colon if needed.

- If the key starts with raw text, the first letter is capitalized in the output.

### 9.2. CSS Property Tables

CSS properties are defined with a `<pre class="propdef">` block.

`Name`, `Value`, `Initial`, and `Inherited` are all required.

- `Name` gives the property name. It will be automatically wrapped in a `dfn` by Bikeshed, so there’s no need to do anything manually. Multiple comma-separated property names can be given, if several properties share identical propdef blocks.

- `Value` gives the grammar for the property, written in CSS’s Value Definition Syntax. Anything that looks like a grammar non-terminal (like `<foo>`) will automatically be escaped and linked appropriately, so you don’t need to manually autolink it.

- `Initial` gives the initial value of the property.

- `Inherited` must be "yes" or "no".

All the other keys listed in the block above are optional. If left unspecified, they’ll be given a usually-reasonable default value:

- `Applies to` defaults to "all elements". It specifies what subset of elements the property has meaning for.

- `Percentages` defaults to "n/a". It specifies what value percentages are resolved against, if the property takes percentage values at all.

- `Computed Value` defaults to "as specified". It specifies what, if any, canonicalization occurs when transforming specified values to computed values. (Complex values should use "see prose" and define it in prose instead.)

- `Canonical Order` defaults to "per grammar". It specifies what order values are serialized in, if values are rearranged when parsing. (The default is almost always correct; usually only properties with unusual legacy constraints on their serialization will need to specify anything for this.)

- `Animation Type` defaults to "discrete". It specifies the Animation Type of the values.

- `Logical Property Group` is optional, and if specified defines the logical property group the property belongs to. (The value is usually, but doesn’t have to be, a shorthand property name covering all the longhands in the group.)

All values are placed directly into the output HTML as written, so HTML tags, Bikeshed autolinks, etc can all be used as normal.

If defining a shorthand property, put a `"shorthand"` class on the block. This will change the block to only require `Name` and `Value`; `Canonical Order` is still allowed, but continues to default to "per grammar" as usual. All other keys will default to "see individual properties", which is usually all you need.

If adding some values to a property, rather than defining the property itself, put a `"partial"` class on the block. It will now require a `New Values` key, rather than `Value`, but is otherwise normal.

Additional keys beyond what is described here can be provided; they’re placed after all the built-in keys.

The end result looks like:

Name: | flex-basis
Value: | content | <<'width'>>
Initial: | auto
Applies to: | flex items
Inherited: | no
Percentages: | relative to the flex container’s inner main size
Computed value: | as specified, with lengths made absolute
Canonical order: | per grammar
Animation type: | length

### 9.3. CSS Descriptor Tables

CSS descriptors (like properties, but for at-rules) have def blocks similar to, but simpler than, propdef blocks.

`Name`, `Value`, and `Initial` are required keys, just like propdef blocks. Additionally, `For` is required, giving the name of the at-rule the descriptor is for, like `For: @counter-style`. The rest of the propdef keys are not meaningful for descriptors.

Like propdef blocks, a `"partial"` class can be put on the block to indicate that you’re adding values to an existing definition; `Name`, `For`, and `New Values` must be provided.

While not technically descriptors, media features can be defined with this block as well, if an `"mq"` class is put on the block. It then only requires `Name`, `For`, and `Value`.

Additional keys beyond what is described here can be provided; they’re placed after all the built-in keys.

### 9.4. HTML Element Tables

HTML/SVG/etc elements can use a `<pre class="elementdef">` block. (The content and presentation of this block is similar to that in the HTML standard, but is closer to that in the SVG standard.)

- Name - required. Gives the element name. Can provide multiple element names, comma-separated. The names will automatically be wrapped in a `dfn` for you.

- Categories - required. What element categories the element is part of. Can provide multiple values, comma-separated. The names will automatically be wrapped in links for you, of `dfn` type.

- Contexts - required. The contexts in which the element can be used. This is freeform HTML.

- Content model - required. The types of contents the element can contain. This is freeform HTML.

- Attributes and/or Attribute Groups - at least one is required. A comma-separated list of attribute names and/or attribute groups that this element can have. These will be automatically be wrapped in links for you—​`element-attr` type for attributes, and `dfn` type for attribute groups (like "core attributes" in SVG).

- DOM interfaces - required. A comma-separated list of WebIDL interface names corresponding to the elements being defined. The names will automatically be wrapped in links for you, of `interface` type.

Additional keys beyond what is described here can be provided; they’re placed after all the built-in keys.

### 9.5. IDL Method Argument Tables

IDL methods can have their arguments defined & documented in a `<pre class="argumentdef">` block:

    <pre class=idl>
      interface Foo {
        undefined bar(long arg1, DOMString? arg2);
      };
    </pre>

    <pre class=argumentdef for="Foo/bar()">
    arg1: here's the first arg
    arg2: the second arg is different!
    </pre>

The `argumentdef` block must specify what method the arguments are for in a `for` attribute on the `<pre>`. The contents of the element must then, on each line, list the argument name, a colon, then a description of that argument.

It will produce a table listing each argument, its description, and automatically contain its type, nullability, and optionality (determined from the IDL block), like:

    interface Foo {
      undefined bar(long arg1, DOMString? arg2);
    };

Arguments for the Foo.bar() method.
Parameter | Type | Nullable | Optional | Description
--- | --- | --- | --- | ---
`arg1` | `long` | ✘ | ✘ | here’s the first arg
`arg2` | `DOMString?` | ✔ | ✘ | the second arg is different!

Note: This automatically wraps the argument names in a `dfn`; this is meant to be the canonical location of the argument’s definition.

You can wrap the argument names in `|var|` syntax to also get a `<var>` around them, if you are placing the argument def within an algorithm block and want to highlight additional uses of it, like:

    <div algorithm="Foo/bar()">
      <pre class=argumentdef for="Foo/bar()">
      |arg1|: Here's the first arg
      </pre>

      When a {{Foo}}'s <dfn method for=Foo>bar(|arg1|)</dfn> method is called:

      1. Do something with |arg1|.
      2. ...
    </div>

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