# Bikeshed Documentation

## Living Standard, 19 December 2025

Bibliographical references form a special class of autolinks. They’re typically added only via the shorthands `[[FOO]]` for informative references and `[[!FOO]]` for normative references.

(A "normative reference" is a reference that your document depends on; something in the other document is required in order to implement your document correctly. An "informative" reference is anything else. Informative references might be to normative documents, if your feature doesn’t actually depend on the referenced document.)

Unlike regular autolinks, which link to `dfn` elements, biblio autolinks cause the spec to generate entries in its "References" section, and then link to that instead.

The bibliography database is completely separate from the autolinking database, and comes from multiple sources. The default data comes from the SpecRef project and the CSSWG’s own biblio file (preferring SpecRef’s information when the same name appears in both).

### 8.1. Biblio Link Modifiers

Several aspects of how bibliography autolinks work can be controlled by adding keywords to the autolink, after the biblio name.

- Some biblio entries come with multiple sets of urls; at present, Bikeshed tracks a single "current" url and a single "snapshot" url. In the W3C, for example, this maps to Editors Drafts and things in /TR space, respectively.

  You can specify which url to use by specifying `current` or `snapshot` within the biblio shorthand, like `[[FOO current]]`, or specify the default url to choose for all your biblio refs with the Default Ref Status.

- By default, biblio autolinks are formatted in the "index" style, where they are links to the bibliography, and appear like you typed, just with a single set of square brackets: `[[FOO]]` will produce a link with the text "[FOO]".

  Alternately, they can be configured to use the "direct" style, which links directly to the document in question, rather than the bibliography entry containing the link. (The bibliography entry still gets added.)

  There is also an "inline" style, which links directly to the document in question, and formats itself as the title of the document, rather than as the short biblio tag you typed.

  These can be controlled on a link-by-link basis by setting `inline`, `direct`, or `index` in the shorthand, like `[[FOO inline]]`, or change the default for all biblio links in the document by setting the Default Biblio Display metadata.

- The bibliography database tracks whether certain documents have been obsoleted by newer documents, and if you attempt to link to the the now-obsolete document, Bikeshed defaults to linking to the newer document instead and asking you to update the reference.

  If you do intentionally need to link to a now-obsolete document (for example, if you’re talking about a feature in the old document that’s since been replaced), you can tell Bikeshed you do intend to link to that by setting `obsolete` in the shorthand, like `[[FOO obsolete]]`.

All of these keywords can be combined, in any order, such as `[[FOO inline obsolete]]` or `[[FOO index current]]`.

### 8.2. Autolinking and Automatic Bibliography Entries

Whenever you autolink to a term from another spec using a standard dfn autolink, Bikeshed automatically adds a bibliography entry for that document if one doesn’t already exist.

By default, it assumes these are normative references. However, if the link is in a "non-normative" element, Bikeshed doesn’t put it in the bibliography. This includes any notes (`class=note`), examples (`class=example`), or sections manually marked with `class=non-normative`. (You can override this and get a normative reference by adding a `class=normative` to the link or an ancestor.)

### 8.3. Manual Biblio Links

If, for whatever reason, you need to craft a bibliography link manually, just create an `a` element with `data-link-type=biblio` and the biblio tag either in the text content of the link or in a `data-lt` attribute, similar to a manually-crafted autolink.

If you need one of the biblio link modifiers, add `data-biblio-type=[normative | informative]`, `data-biblio-status=[current | snapshot]`, `data-biblio-display=[index | inline]`, and/or `data-biblio-obsolete=""` to the link as well.

### 8.4. Custom Biblio Entries

You can also add your own bibliography data, following the SpecRef JSON format:

    {
      "foo-bar": {
        "authors": [
          "Tab Atkins",
          "Bat Snikta"
        ],
        "href": "http://www.example.com/foo-bar/",
        "title": "Foo Bar Level 1",
        "status": "CR",
        "publisher": "W3C",
        "deliveredBy": [
          "http://www.w3.org/html/wg/"
        ]
      }
    }

This would allow you to write `[[FOO-BAR]]` into your document, and have it be recognized as a valid autolink, with a bibliography entry generated in the index just like any of the predefined biblio references.

Note: Only the "title" field is strictly necessary; the rest can be omitted if desired.

This JSON should be inline, in a `<pre class=biblio>` block. It can also be in a `biblio.json` file in the same folder as the Bikeshed file, but this is incompatible with the web service.

If you find yourself adding this to more than one document, it might be worth adding to SpecRef itself so others can benefit from it as well; file an issue on that project if you’re interested.

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