Bikeshed Documentation

Living Standard,

7. Autolinking

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.

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.

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):

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

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

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

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

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

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:

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.

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.

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.

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.

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

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:

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.

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.

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.

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.

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.

← 6 Definitions Table of Contents 8 Bibliography →

CC0 To the extent possible under law, the editors have waived all copyright and related or neighboring rights to this work. In addition, as of 21 January 2026, the editors have made this specification available under the Open Web Foundation Agreement Version 1.0, which is available at https://www.openwebfoundation.org/the-agreements/the-owf-1-0-agreements-granted-claims/owfa-1-0. Parts of this work may be from another specification document. If so, those parts are instead covered by the license of that specification document.