# Bikeshed Documentation

## Living Standard, 19 December 2025

As with WebIDL, Bikeshed can automatically process CDDL blocks, marking up all relevant terms for you without any intervention, setting up definitions and autolinks as appropriate. [RFC8610]

To activate this behavior, simply place the CDDL in a `<pre class='cddl'>` element. Bikeshed will consume the text content of the element (ignoring any markup you may currently have) and replace it with marked-up text containing `dfn` and `a` elements.

As mentioned in § 5.9.2 xmp To Avoid Escaping Markup, you can use `<xmp class=cddl>` as well, so you don’t have to escape your `type<parameter>`/etc types. This prevents you from using other markup in your CDDL, but that’s relatively rare.

In the process of doing this, Bikeshed will also syntax-check your CDDL, and report fatal errors for any mistakes. If anything isn’t recognized when it should be, or the CDDL parser fails in a major, non-graceful way, please report it as an issue.

### 11.1. Putting Definitions Elsewhere

You may want to have the actual definition of a CDDL term (the thing that Bikeshed actually links to) somewhere in your prose near the full definition, rather than being in the CDDL block.

Bikeshed will automatically produce an `a` in your CDDL, rather than a `dfn`, if it can find a pre-existing definition of that CDDL term, including local definitions in the current spec. However, you have to mark up the definition correctly to get this to work, or else Bikeshed will fail to recognize there’s an external definition and will mark up the CDDL with a `dfn` as well.

In particular, CDDL key and value definitions need to have their `for` value set to the CDDL type they’re a part of.

### 11.2. Turning Off Processing

If for whatever reason you don’t want your CDDL block to be processed by Bikeshed, simply use another element, or another class. If you really want to use `<pre class=cddl>`, you can add a `data-no-cddl` attribute to the element. Bikeshed will leave these elements alone.

Alternately, if your block is CDDL, but it’s not meant to be taken literally (for example, if it shows an example type), put a `class=extract` on it.

### 11.3. CDDL Modules

Bikeshed generates a CDDL index appendix by default from CDDL type definitions it finds in the spec. If the CDDL index needs to split CDDL type definitions into more than one CDDL module, the spec needs to name these modules and associate CDDL blocks with them:

- Any CDDL module must be defined somewhere in the spec with a `<dfn>` element whose type is `cddl-module`.

- CDDL blocks must add a `data-cddl-module` attribute set to a comma-separated list of CDDL module names they belong to. If a CDDL block does not have that attribute, the code considers it is defined in all CDDL modules.

The CDDL index is split per module, using the `<dfn>` linking text as title for each module.

For example:

    This spec defines two CDDL modules:
    * <dfn cddl-module>local end</dfn>
    * <dfn cddl-module>remote end</dfn>

    Local end definitions:
    <pre class=cddl data-cddl-module="local end">
      LocalCommand = {
        param: common
      }
    </pre>

    Remote end definitions:
    <pre class=cddl data-cddl-module="remote end">
      RemoteCommand = {
        param: common
      }
    </pre>

    Both local and remote definitions:
    <pre class=cddl data-cddl-module="local end,remote end">
      common = any
    </pre>

will create a CDDL index appendix that contains two listings: one named "Local end" and another named "Remote end".

Note: Even when modules are used, CDDL definitions in a spec are part of a single namespace, meaning that a `foo` type cannot be defined differently within a single spec for two different CDDL modules.

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