# Bikeshed Documentation

## Living Standard, 19 December 2025

The processor supports "autolinks" for easy linking to terms without having to fiddle around with urls. Instead, just match up the text of the link to the text of the definition!

There are three types of autolink syntaxes you might see/use:

1. Dfn autolinks, like `{{foo}}` or `[=foo=]`, which link to a definition. See § 7.1 Dfn Autolinks for details.

2. Spec/section autolinks, like `[[FOO]]` or `[[#foo]]`, which link to a document or heading. See § 7.2 Spec/Section Autolinks for details.

3. Manual `a` elements without an `href` attribute, which can create either of the preceding two types, and are occasionally useful when the preceding syntaxes can’t express what you need. See § 7.3 Manual Autolinks for details.

You may also see an `l` element, which is used to help augment dfn autolinks or biblio autolinks, and can avoid the need to use an `a` in many cases. See § 5.7.1 Autolink Shortcuts That Work Anywhere: the l element for details.

### 7.1. Dfn Autolinks

Dfn autolinks create links to definitions.

There are two parts to the syntax:

1. The wrapper, like `{{...}}` or `[=...=]`, which specifies what type of definition you’re linking to.

2. The inside syntax, which gives details on what you’re trying to link to.

#### 7.1.1. Wrapper Syntax

The characters used to wrap an autolink determine what type of definition (see § 6.4 Definition Types) you’re trying to link to. They’re arranged into categories that can be individually turned on or off, if you don’t think you’ll use a particular type of autolink, and want to avoid possibly triggering an autolink accidentally.

The Dfn varieties (controlled by `Markup Shorthands: dfn yes`):

- `[=foo=]` is an autolink to the "dfn"-type definition "foo".

- `[$foo$]` is an autolink to the "abstract-op"-type definition "foo".

The HTTP varieties (controlled by `Markup Shorthands: http yes`):

- `[:header:]` or `[::pseudo-header:]` is an autolink to the "http-header"-type definition for "header" or ":pseudo-header".

The IDL variety (controlled by `Markup Shorthands: idl yes`):

- `{{foo}}` or `{{foo()}}` is an autolink to one of the IDL types (interface, method, dictionary, etc) for the term "foo".

The CDDL varieties (controlled by `Markup Shorthands: cddl yes`):

- `{^type^}` is an autolink to the CDDL type named "type".

- `{^type/key^}` is an autolink to the CDDL key named "key" for the CDDL type named "type". The key may be a CDDL value in an enumeration, usually enclosed in double-quotes, as in `{^type/"value"^}`.

The markup (HTML/SVG/etc) varieties (controlled by `Markup Shorthands: markup yes`):

- `<{element}>` is an autolink to the element named "element".

- `<{element/attribute}>` is an autolink to the attribute or element-state named "attribute" for the element "element".

- `<{element/attribute/attribute value}>` is an autolink to the value "attribute value" of an attribute or element-state named "attribute" for the element "element".

The CSS varieties (controlled by `Markup Shorthands: css yes`):

- `'foo'` (apostrophes/straight quotes) is an autolink to a property or descriptor named "foo". If there is both a property and a descriptor of a given name, this defaults to linking to the property if used in its bare (`'foo'`) form.

- `''foo''` (double apostrophes) is an autolink to any of the CSS definition types (but see the special syntax notes in § 7.1.3 ''foo'' Special Syntax)

- `<<foo>>` is an autolink to a type/production named "<foo>"

  - Bikeshed supports the numeric-range restriction on type autolinks, such as `<<length [0,10px]>>`. Infinities in the range can be written as a literal `∞` character, an `&infin;` HTML character reference, or the literal string `Infinity`.

- `<<'foo'>>` is an autolink to the the property or descriptor named "foo" (used in grammars, where you need `<foo>` for non-terminals).

- `<<foo()>>` is an autolink to the function named "foo" (used in grammars)

- `<<@foo>>` is an autolink to the at-rule named "@foo" (used in grammars)

#### 7.1.2. Inside Syntax

The inside of an autolink contains literal text. It is not parsed as HTML, and there is no way to escape characters within it. (If this is necessary, use a manual autolink instead.) This means that, for example, if you are trying to link to the term `a < b`, you write that literally within the autolink, like `[=a < b=]`. (On the other hand, the definition is likely written normally, as `<dfn>a &lt; b</dfn>`.)

The inside syntax contains 1-4 segments, separated by certain characters:

- Put the text you’re trying to link to inside the autolink.

  `[=foo=]` will link to a `<dfn dfn>foo</dfn>`.

- If the definition is namespaced with a `for` attribute (see § 6.5 Namespacing a Definition), put the `for` value before the text, separated by a slash.

  `{{Foo/bar}}` will link to a `<dfn attribute for=Foo>bar</dfn>`.

  To link specifically to the version of a definition without a `for` value, use an empty slash, like `[=/url=]`, which will link to a `<dfn>url</dfn>`, but not a `<dfn for=page>url</dfn>`.

  If you omit the `/`, it means you don’t care what the `for` value of the definition is. The Assume Explicit For metadata can change this to make it mean the same as an empty slash.

- If your wrapper characters apply to more than one dfn type (like `{{...}}`, which can link to any of the IDL dfn types), you can append a `!!type` after the linking text if you need to differentiate them. (This is very rarely necessary.)

  `'foo!!descriptor'` will link to a `<dfn descriptor>foo</dfn>`, but not a `<dfn property>foo</dfn>`, while `'foo'` can potentially link to either.

- If you want the visible text to be different from the linking text, you can append `|visible text` after the linking text.

  `[=do foo|when foo is done=]` will link to a `<dfn dfn>do foo</dfn>`, but will display "when foo is done" as the visible text of the link.

  Unlike the rest of the autolink’s insides, the visible text is parsed as normal Bikeshed text, and can use any of the ordinary HTML/Markdown/Bikeshed constructs, like `[=do foo|when <b>foo</b> is done=]`, but is also subject to their parsing constraints (such as literal `<` characters indicating the start of an HTML tag). This segment is ended when the wrapper’s ending characters are encountered literally; you can use HTML escapes or Bikeshed escapes to use those characters in your visible text.

  Note: Many variations on the linking text are automatically handled by Bikeshed and don’t need manual adjustment via the visible text; see § 6.1 Conjugating/Pluralizing/etc the Linking Text for details.

All of these can be used together, like `{{Foo/bar!!attribute|the bar attribute}}`, which is equivalent to `<a attribute for=Foo lt=bar>the bar attribute</a>`. The separating characters between segments (`/`, `!`, and `|`) aren’t otherwise usable within the "literal text" portion of the syntax; use a manual autolink if your term contains one of these characters.

By default, text macros can be used in the "visible text" portion, but no other part, so `[=[FOO]=]` is an autolink to the term `[FOO]`. `Markup Shorthands: macros-in-autolinks yes` changes this, so `[=[FOO]=]` instead first has the `[FOO]` macro substituted, and then it’s parsed as normal. Macros can’t cross parsing boundaries, however—​a macro can supply the "literal text" portion (any or all of the three literal segments) or the "visible text" portion, but not both.

#### 7.1.3. `''foo''` Special Syntax

The CSS "maybe" autolink syntax, indicated by the double-single-quotes `''foo''` wrapper, uses a slightly different internal syntax for legacy reasons. It comes in three forms:

1. The standard autolink inside syntax almost works, just without the ability to specify different "visible text". That is, `''foo/bar!!value''` works as normal, but `''foo|the foo value''` does not. This syntax creates a "maybe" CSS autolink, which can link to most CSS types, but will fail silently if the linking fails and instead act like case 3, below.

2. A syntax that resembles a CSS property, like `''foo: bar baz''`. This creates a "propery" CSS autolink, linking to the `foo` property. Alternately, `''@foo/bar: value value''` creates a "descriptor" CSS autolink, linking to the "bar" descriptor of the "@foo" at-rule.

   In either case, the part after the `:` up to the next literal `''` is parsed as normal Bikeshed text, so it can contain HTML, markdown, or Bikeshed-specific syntax.

3. If the contents of the autolink don’t look like either of the above two cases, it’s just formatted as "CSS text": the contents are parsed as normal Bikeshed text, and the whole thing is wrapped in `<span class=css>`, which triggers a particular styling in W3C specs.

### 7.2. Spec/Section Autolinks

Biblio/spec/section autolinks create links to other documents as a whole, or sections of those documents, rather than to particular definitions. They come in three closely-related syntaxes:

1. Biblio/document autolinks, like `[[FOO]]` or `[[!FOO]]`, which specify the shortname of a document (from SpecRef). See § 8 Bibliography for more details.

2. Local section autolinks, like `[[#foo]]`, which link to another section in your current document by its ID.

3. Cross-spec section autolinks, like `[[FOO#bar]]`, which link to a section of another document, and mixes the previous two syntaxes.

See § 7.9 Section Links for details on the latter two.

Like dfn autolinks, if you want to display a specific visual text rather than what the autolink would normally display, you can append `|visible text` to the internals, like `[[CSS-FOO|the CSS Foo spec]]`.

These are all controlled by `Markup Shorthands: biblio yes`.

### 7.3. Manual Autolinks

If one of the shorthand syntaxes don’t work for whatever reason, even if you use the `l` element, you can use an ordinary `a` element to specify a manual autolink.

Any `a` without an `href` attribute is an autolink.

- By default, it’s a "dfn" autolink, same as the `[=...=]` syntax. To override this, add the link type as an attribute, similar to `dfn`, like `<a attribute>...</a>` to autolink to an attribute.

- By default, the visible text and linking text are the text content. To override this, specify linking text in an `lt` attribute, like `<a lt="do foo">when foo is done</a>`.

- If the definition is namespaced by a `for` attribute, add a `for` attribute, like `<a attribute for=Document>ready</a>`.

  To link specifically to the version of a definition without a `for` value, use an empty `for` attribute, like `<a for>a</a>`, which will link to a `<dfn>url</dfn>`, but not a `<dfn for=page>url</dfn>`.

  If you omit the `for`, it means you don’t care what the `for` value of the definition is. The Assume Explicit For metadata can change this to make it mean the same as an empty slash.

- To link to a specific spec’s version of a particular definition, add a `spec` attribute with the shortname of the spec you’re linking to.

All together, it might look like `<a attribute for=Document lt=ready>the Document.ready attribute</a>`.

### 7.4. Link Types

Links have the same types as definitions, with a few additional "union" types that are used by the shortcut forms. While you shouldn’t specify them explicitly, they’ll show up in error messages sometimes, so here’s a list of them:

- "propdesc" - used by the `'foo'` shorthand. A union of "property" and "descriptor".

- "functionish" - used by the `''foo()''` shorthand for things that look like functions. A union of "function", "method", "constructor", and "stringifier".

- "maybe" - used by the rest of the `''foo''` shorthand values. A union of "dfn" and all the CSS types except "property" and "descriptor". For legacy reasons, this link type has the additional magic that it doesn’t flag an error if it can’t find any matches, because it’s also used to annotate inline CSS code fragments.

- "idl" - used by the `{{foo}}` shorthand. A union of all the IDL types.

- "idl-name" - used by the IDL auto-parser. A union of all the IDL types that can declare IDL argument types, like "interface", "enum", or "dictionary".

- "cddl" - used by the `{^foo^}` shorthand. A union of all the CDDL types.

- "element-sub" - used by the `<{foo/bar}>` shorthand. A union of "element-attr" and "element-state".

When you actually run the processor, you may get errors about there being too many possible references to choose from. The processor will continue to run anyway, but its default choice might be the wrong definition. There are three things you might have to do to fix these:

1. Specify the type explicitly, if the link isn’t being processed as the correct type. Like definitions, this can be done by just adding the type as a boolean attribute on the link, or by adding a `link-for` attribute to a container. If the link is using shorthand syntax, you can use the `!!type` suffix to specify the type.

2. If the link type corresponds to one of the definition types that needs `for` to be specified, you may need to specify `for` on the link as well to narrow down which definition you’re referring to. For example, many CSS properties define an "auto" value; to link to the "auto" value of the 'width' property in particular, specify `<a value for=width>auto</a>`, or the shorthand syntax `''width/auto''`. To refer to a value of a descriptor, you can be completely explicit and specify the at-rule as well, like `<a value for='@counter-style/system'>numeric</a>`, but you’re allowed to omit the at-rule if there are no other properties or descriptors with the same name, like `''system/numeric''`. This might trigger errors in the future if a conflicting term gets added later, but it keeps your links shorter for now.

   Again, you can specify a `link-for` attribute on a container to default it for all the autolinks inside the container. Alternately, you can specify `link-for-hint` on a container, which’ll use the hint as the for value if possible (if doing so wouldn’t eliminate all the possible links). This is useful if some container has a bunch of links for a given property, say, but some of the links are to other things entirely; using `link-for` means you have to manually specify the other links aren’t for anything, but `link-for-hint` is more "do what I mean".

3. If multiple specs define the same term, you may need to declare which spec you’re referring to. (The processor is smart enough to automatically figure out which one you probably want in many cases.) Just add a `spec` attribute with the spec’s shortname to either the link or a container. This can also be specified document-wide, as described in § 7.7 Configuring Linking Defaults. (You can add this to a dfn autolink by wrapping it in an `l` element, or by fully converting to an `a` element, and adding a `spec` attribute.)

As a final note, the autolinking algorithm will link differently based on whether the spec being processed is a "current" (up-to-date) or "snapshot" (generated for a past date) draft. If "current" (ED, UD, etc.), it’ll prefer to link to other current drafts, and will only link to "snapshot" if no "current" version of that spec exists. (If a definition only exists in the "snapshot" draft but not the "current" draft, that almost certainly means it’s been deleted since the "snapshot" draft was last published, and thus shouldn’t be linked to.) On the other hand, "official" (WD, CR, etc.) specs will preferentially link to other official specs. A future version of the processor will likely enforce the W3C’s linking policy more strongly: preventing CRs from linking to EDs at all, preventing RECs from linking to anything below CR, etc.

If you need to override the processor’s choice for which status to link to for a particular link, provide a `status` attribute containing either "ED" or "TR" on the link or a container.

### 7.5. Linking to Unexported Definitions

Most definition types are automatically exported and made available for cross-linking, but "dfn" type definitions aren’t, because specs often define terms for their own internal use that aren’t meant to be used outside the spec (and in particular, aren’t named in a way so as to avoid collisions).

If a spec contains a "dfn" type definition that you want to link to, but it’s not marked for export (either intentionally, or because it was accidentally missed and fixing the spec would be time-consuming), using the `spec` attribute (defined above) will override the lack of an export declaration, and go ahead and link to it anyway.

### 7.6. Link Attributes On Ancestors

All of the autolinking attributes can be specified on an ancestor of the autolink instead, if you have a group of links that all share a particular attribute.

They can be spelled out fully (like `data-link-type`), or without the `data-` prefix, like `link-type`. As there’s no overlap with a similar `data-dfn-*` attribute, `link-spec` and `link-status` can omit `link-` as well, being spelled as merely `status` and `spec`.

A link will take the "closest" version of each attribute it can find, so specifying an attribute directly on the link will override anything coming from an ancestor.

### 7.7. Configuring Linking Defaults

When there are multiple definitions for a given term and Bikeshed can’t automatically tell which one you want, it’ll emit a warning asking you to specify more explicitly. You can do this per-link, but you typically want to make the same choice every time the term is autolinked; this can be done by adding a `<pre class='link-defaults'>` block, written in the InfoTree format. Each piece of info must have a `spec`, `type`, and `text` line, and optionally a `for` line if necessary to further disambiguate.

Sometimes this is too fine-grained, and you’d actually like to completely ignore a given spec when autolinking, always preferring to link to something else. To do this, add a `<pre class='ignored-specs'>` block, written in the InfoTree format. Each piece of info must have a `spec` line, and optionally a `replacedBy` line, both naming specs. If the info has just a `spec` line, that spec is ignored totally by default; linking to it requires you to manually specify a `spec=""` attribute on the autolink. If the info has a `replacedBy` line, then whenever an autolink has a choice between the two specs, it’ll delete the `spec` value from consideration, leaving only the `replacedBy` value (plus any other specs that might be providing a definition).

### 7.8. Potentially-ambiguous `for`-less Links

If you were directed here by a Bikeshed error message, put an explicit `for` value on your autolink. (Use `for="/"` to link to a definition without a `for` value of its own).

Bikeshed’s autolinking functions as a series of filters, some of which are optional. For example, if you don’t specify a `for` value, then Bikeshed simply doesn’t care about the `for` values of definitions as it searches. However, this doesn’t always match people’s mental models—​in particular, people sometimes implicitly assume that an autolink without a `for` will specifically match a definition without a `for`.

Usually this is fine; if there are multiple possible definitions, Bikeshed will just throw up a linking error informing you of how to be more specific. But if you have a definition of that term with a `for` value in your local spec (or your anchors block), Bikeshed can silently select that as the correct definition to link to, causing accidental spec corruption if you meant to link to a cross-spec definition without a `for`.

In other words, if some other spec defines `<dfn>term</dfn>`, and then your spec both defines `<dfn for=foo>term</dfn>` and links to `<a>term</a>` (expecting the link to go to the cross-spec definition), you’ll be disappointed, but won’t know it’s wrong unless you manually check your links.

Bikeshed looks out for this situation, and flags it as a potentially-ambiguous link, requiring you to specify the `for` value explicitly. If you want to link to the `for`-less cross-spec definition, simply add `for="/"` to your autolink, to indicate explicitly that you want the definition without a `for` value. Otherwise, add the appropriate `for` value as normal.

### 7.9. Section Links

Sometimes you want to link to a section of a document, rather than a specific definition. Bikeshed has section links to handle this case more easily:

    [[#heading-id]]

renders as:

    <a href="#heading-id">§6.1 The Example Section</a>

Note that this is quite different from normal autolinks; rather than matching on text and letting Bikeshed fill in the href, you match on href and let Bikeshed fill in the text. This is because section titles change much more often than definition texts, so using text-based matching is fragile; on the other hand, their IDs tend to be stable, as they’re often linked to. Also, the section titles are often long and annoying to type, and they move around, so numbering isn’t stable.

You can also use cross-spec section links, as long as the spec is either in Bikeshed’s linking database, or the biblio database. The syntax is a mixture of a biblio reference and a section link:

    [[css-flexbox-1#auto-margins]]
    [[CSS-access-19990804#Features]]

which renders as:

    <a href="https://drafts.csswg.org/css-flexbox-1/#auto-margins">CSS Flexbox 1 §8.1 Aligning with auto margins</a>
    <a href="http://www.w3.org/1999/08/NOTE-CSS-access-19990804#Features">Accessibility Features of CSS §Features</a>

If Bikeshed knows about the spec, it link-checks you, and fills in the section number and heading in the generated text. If the spec is only in the bibliography database, Bikeshed just assumes that the link target exists and uses it directly in the text, because it has no way to tell what the section is named.

If the spec is multipage, like SVG, and Bikeshed knows about it, most of the time you don’t need to do anything different - Bikeshed will find the correct page for the heading you’re linking to. On the rare occasions that the same heading id exists in multiple pages of the same spec, tho, specify the page like `[[svg/intro#toc]]` (which indicates the #toc heading on the intro.html page). If the desired heading is on the top-level page, use an empty page name, like `[[html/#living-standard]]`. In any case, Bikeshed will throw an error, and tell you what names it knows about so you can easily correct your link.

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