# Bikeshed Documentation

## Living Standard, 19 December 2025

Bikeshed’s source format is roughly HTML, but it allows you to omit or shorten several verbose/annoying parts of the language, reducing the amount of format noise in the spec source, making it easier to read and write.

### 5.1. Markdown

Bikeshed uses a Markdown variant called Bikeshed-flavored Markdown (BSMD). By default, it recognizes all of the "block-level" Markdown constructs defined by CommonMark, except for indented code blocks:

- paragraphs

- lists

- blockquotes

- headings (both underlined and #-surrounded)

- horizontal rules

- fenced code blocks (using `~` or ```)

- HTML blocks

Because it doesn’t have to handle indented code blocks, BSMD’s HTML handling is generally superior to other Markdown implementations. You can freely switch back and forth between Markdown and HTML as needed, and indent properly. (In fact, you should properly indent everything; if you don’t, you can sometimes get confusing errors!)

If the `Markup Shorthands: markdown yes` metadata is specified, it also recognizes several of the Markdown "inline elements":

- emphasis (`*emphasis*`) and strong (`**strong**`) elements

- inline `code` (``code``) elements, which can include literal backticks by delimiting the content with multiple-backtick sequences: ``` ` ``` produces ```. (Note that spaces at the beginning and end of the code element are stripped.)

- inline links, with optional title

It does not recognize "autolinks" (surrounded by <> characters), images, or "hard line breaks"; use HTML for these. It also does not recognize "link references" (defining the link location elsewhere, and referring to it by reference instead).

In addition to standard (CommonMark) Markdown, Bikeshed also recognizes definition lists, with the following format:

    Here's the dl syntax:

    : key
    :: val
    : key 1
    : key 2
    :: more vals

For all three list formats, on the rare occasions you need to add a class or attribute to the list, you can wrap it in the appropriate list container, like:

    <ol class=foo>
      1. first
      2. second
    </ol>

Bikeshed will use the container you provided, rather than generating a fresh one like it does by default.

Bikeshed also supports adding IDs to headings, via the Markdown Extra syntax:

    Header 1 {#header1}
    ========

    ### Header 2 ### {#header2}

More of Markdown will be supported in the future, as I get closer to adhering to the CommonMark specification.

### 5.2. Bikeshed-Specific Character References

In addition to the standard HTML character reference syntaxes (named refs like `&copy;` or numeric refs like `&#1234;` or `&#x1a2b;`), Bikeshed supports a few custom character references to address some common needs. All of these look like `&bs...;`:

"bs" + any single ASCII punctuation character

  This is an escape for that punctuation character. For example, `&bs[;` is an escape for the `[` character, allowing you to escape an autolink without having to remember the codepoint of the character: `&bs[;=foo=]`.

  (Yes, semicolon works too, and still needs to be ended by a semicolon: `&bs;;` to produce ;.)

`&bs<<;`
`&bs>>;`
`&bs->;`

  These are escapes for the [INFRA] syntax for lists and maps: «1, 2, 3» or «a→b, c→d ».

More of these will likely be added in the future.

### 5.3. Text Macros

Bikeshed supports the ability to use "text macros", spelled like `[FOO]` (a single uppercase word, surrounded by square brackets), which expand into other text.

Macros can be used in several places, which dictate how they’re parsed:

- in place of ordinary text/markup, like `<p>It’s [YEAR] right now`, where their contents are parsed as HTML

- in HTML attributes, like `<a href=[LATEST]>`, where their contents are parsed as HTML attribute value (and safely escaped, no need to worry about spaces or quotes)

- directly within an HTML tag, like `<div [ATTRS]>`, where their contents are parsed as an HTML attribute list

- in the `computed-metadata.include` file, where their contents are just used as text and substituted into the JSON with no escaping.

Macros are not substituted, by default, in the "link data" portion of autolinks, but this can be allowed by setting `Markup Shorthands: macros-in-autolinks yes`. With this, you can define a common long term in a macro, then use it in an autolink like `[=[LONGTERM]=]`. (Alternately, you can just put the autolink itself into a macro, like `Text Macro: FOO [=foo=]`, and then `[FOO]` will expand to the autolink without having to adjust Markup Shorthands.)

Macros are also not substituted, by default, in the contents of `style`, `script`, `xmp`, or datablocks, as CSS/JS/etc are too likely to contain things that accidentally look like the macro syntax, and mixing another escaping syntax into those languages is more trouble than it’s worth. You can turn on macro substitution on an element-by-element basis by adding the `bs-macros` attribute, like `<style bs-macros>html::before { content: "[TITLE]"; }</style>`. This will substitute them as unparsed plain text, so beware if there is any markup in the macro.

Macros can contain more macros, which are substituted recursively, even when the macros aren’t otherwise parsed (like in attribute values).

It’s normally a fatal error to use a macro that isn’t defined, but you can loosen that restriction by putting a ? at the end, like `[UNKNOWN?]`, which will cause the macro to substitute with the empty string if it’s not defined.

Macros can be escaped in several ways, if you need to write something that looks like `[FOO]` in your source:

- using standard HTML escapes to escape the `[`, like `&#91;FOO]`

- using a Bikeshed escape to escape the `[`, like `&bs[;FOO]`

- If `Markup Shorthands: markdown-escapes` is on (it is by default), using a leading `\` to escape it, like `\[FOO]`.

#### 5.3.1. Custom Macro Names

You can define your own macros via the Text Macros metadata, if you have some long term you’d like to avoid having to repeatedly type.

Macros are one of the possible tests you can use for § 13.2 Conditional Inclusion, so defining a custom text macro can be useful even if it doesn’t have a meaningful value.

#### 5.3.2. Predefined Macro Names

Additionally, Bikeshed supports a number of macros automatically, computed from your spec’s metadata. Mostly, these are just used by your boilerplate file and won’t be seen in the actual document source.

- `[TITLE]` is the spec’s title (taken from Title), formatted appropriately for the `title` element.

- `[SPECTITLE]` is the spec’s title (taken from H1, if set; otherwise from Title), formatted as normal HTML.

- `[SHORTNAME]` gives the document’s shortname, like "css-cascade" (taken from Shortname).

- `[LEVEL]` gives the document’s level (taken from Level).

- `[VSHORTNAME]` gives the "versioned" shortname, like "css-cascade-3" (taken from Shortname + Level).

- `[STATUS]` gives the short version of the spec’s status (taken from Status), like "ED".

- `[LONGSTATUS]` gives the long form of the spec’s status (taken from Status), like "Editor’s Draft".

- `[STATUSTEXT]` gives a custom message about the spec’s status (taken from Status Text).

- `[WORKSTATUS]` gives the spec’s current work status (taken from Work Status).

- `[LATEST]` gives the link to the latest /TR version of the spec (taken from TR).

- `[VERSION]` gives the link to the ED, if the spec is an ED, and otherwise constructs a dated /TR link from today’s date (taken from ED, or Shortname + Level + Date + Status).

- `[ABSTRACT]` gives the document’s abstract, (taken from Abstract).

- `[YEAR]` gives the current year.

- `[DATE]` gives a human-readable date like "30 January 2000" (taken from Date, or today’s date if that’s not set)

  - `[DATE-MY]` gives a partial date like "Jan 2000"

  - `[DATE-MMY]` gives a partial date like "January 2000"

  - `[DATE-DMMY]` is identical to [DATE].

  - `[CDATE]` gives a compact date in the format "YYYYMMDD", like "20000130"

  - `[ISODATE]` gives a compact date in iso format "YYYY-MM-DD", like "2000-01-30"

- `[DEADLINE]` gives a human-readable version of the deadline date (taken from Deadline)

  - `[ISODEADLINE]` gives the deadline data in iso format.

- `[EXPIRES]` gives the expiration date for the draft (taken from Expires)

  - `[EXPIRES-MY]`, `[EXPIRES-MMY]`, `[EXPIRES-DMMY]`, `[CEXPIRES]`, and `[ISOEXPIRES]` give the expiration data in the specified format, like the [DATE] variants.

- `[HISTORY]` gives a link to the W3C spec history page (taken from Shortname + Level, if your spec is in the W3C Org).

- `[REPLACEDBY]`, `[SNAPSHOTID]`, and `[SNAPSHOTURL]` give the corresponding components of the "Warning" metadata (taken from Warning)

  - `[CUSTOMWARNINGTEXT]` and `[CUSTOMWARNINGTITLE]` give the text and title of custom warnings (taken from Custom Warning Text and Custom Warning Title, + Warning to indicate a custom warning)

- `[LOGO]` gives the url of the spec’s logo (taken from Logo).

- `[REPOSITORY]` gives the name of the VCS repository the spec is located in, (taken from Repository, or auto-detected from the source file’s local repo if possible)

  - `[REPOSITORYURL]` gives the URL of the repository (auto-computed from Repository)

- `[MAILINGLIST]` and `[MAILINGLISTARCHIVES]` give the URLs of the mailing list and archives (taken from Mailing List and Mailing List Archives)

- `[W3C-STYLESHEET-URL]` and `[W3C-STATUS-URL]` give URLs to the correct W3C stylesheet and status description, if you’re in the W3C Org. (taken from Status)

As these are substituted at the text level, not the higher HTML level, you can use them anywhere, including in attribute values.

You can mark a macro as "optional" by appending a `?` to its name, like `[DATE?]`. This will cause Bikeshed to just remove it (replace it with the empty string) if it can’t find a definition, rather than throwing an error.

Like most other markup shorthands, text macros can be "escaped" by prepending a backslash, like `\[TITLE]`. When Bikeshed sees this, it will remove the slash and leave the text alone. This is sometimes necessary when code examples in your doc (such as a regex) accidentally look like text macros.

### 5.4. Notes, Issues, Examples, Advisements

The Markdown processor specially recognizes paragraphs starting with "Issue: ", "Advisement: ", "Assertion: ", "Note: ", or "Note, ", and will add a matching class to the paragraph automatically. These classes default to `.issue`, `.advisement`, `.assertion`, and `.note`, but can be customized with the metadatas Issue Class, Advisement Class, Assertion Class, and Note Class. (However, the default classes receive styling from the default stylesheet, so make sure you provide your own styling if you change them.)

The default styling of these blocks includes a generated-content "header" containing the word "NOTE:", etc. Elements with the `.example` class will also be given a generated-content "header" in the format `EXAMPLE n` with an auto-incrementing number, and have self-links created to allow linking directly to the example.

If you’d like to provide your own custom header, write out the container element yourself (rather than using the Markdown shorthand, just create any element with the appropriate class), and add a `heading="YOUR TEXT HERE"` attribute to the container. It will automatically have "NOTE: "/etc prepended to it. (This is used by § 5.13 Remote Issues to put the GitHub issue title on the issue containers.)

Alternately, if you want full control over the contents of the heading, write out the container element and create a `<div class=marker>` element containing the text you want as its first child. (This is what the `heading=""` attribute does; it just automatically prepends "Note:"/etc to the text to keep it visually in line with other notes/etc by default.)

### 5.5. Typography Fixes

Bikeshed will automatically handle a few typographic niceties for you, ones that it can reliably detect:

- Possessive apostrophes, and most contraction apostrophes, are automatically turned into curly right single quotes (`’`).

- Ending a line with `--` will turn it into an em dash (`—`) and pull the following line upwards so there’s no space between the surrounding words and the dash.

### 5.6. Datablocks

Bikeshed supports embedding a number of custom DSLs into your document, known as datablocks. These are done by including a `<pre>` (or `<xmp>` or `<script>`) with a particular class. These are used for several types of definition tables, railroad diagrams, file includes, and bikeshed data sources.

Datablocks are specially parsed: initially, the parser just jumps straight to the closing tag without interpreting anything inside of them, so there’s no risk of Bikeshed-isms or inline Markdown accidentally being parsed. (Within a `<pre>` datablock, standard HTML is still parsed, so use `<xmp>` or `<script>` if you want to include `<` and `&` without escaping.) Even text macros aren’t parsed by default; put a `bs-macros` boolean attribute on the start tag if you want them.

The DSL will handle the actual parsing of the datablock contents, and might invoke Bikeshed’s full parser on parts of that text where it makes sense. It will also determine what to replace the datablock with; data sources simply disappear, while railroad diagrams become `svg`s, and definition tables become `table`s.

### 5.7. Autolinks

There are several autolink shortcuts that make autolinks much shorter to write, such as `'foo'` to link to a CSS property or descriptor, or `{{foo}}` to link to an IDL construct. These are documented in § 7 Autolinking.

Other types of linking shorthand also exist, such as `[[#foo]]` to link to sections of a spec (documented in § 7.9 Section Links), or `[[FOO]]` to link to generate and link to bibliography entries (documented in § 8 Bibliography).

#### 5.7.1. Autolink Shortcuts That Work Anywhere: the `l` element

The autolink shorthands don’t work in elements like `pre`, because it’s too easy for code constructs to look like autolinks. You can still manually write out your autolink as an `a` element, but that can be much more verbose than the terse syntax that the shorthands provide. (For example, `{{Foo/bar()}}` vs `<a method for=Foo>bar()</a>`.)

You can avoid this by using the `l` element, and putting an autolink shorthand inside of it, like `<l>{{Foo/bar()}}</l>`. This will autolink exactly the same as normal, but works anywhere in your document. Extra bonus: it will recognize all the autolinking syntaxes, even if you have some turned off with the Markup Shorthands metadata.

The `l` element itself is removed from the document and replaced by the autolink, but if you specify any attributes on the `l`, they’ll be transferred to the generated `a`. This is especially useful for autolinking attributes that can’t be specified in the autolink shorthand, like the spec to search for when disambiguating a one-off term: `<l spec=foo>[=term that exists in multiple specs=]</l>`. Without this, you’d have to convert the autolink fully to HTML, like `<a dfn data-dfn-spec=foo>term that exists in multiple specs</a>`

### 5.8. `var` and Algorithms

The `var` element (or its shorthand equivalent, `|foo|`) is often used to mark up "arguments" to a prose algorithm. Bikeshed explicitly recognizes this, and has several features related to this.

Algorithms can be explicitly indicated in your markup by putting the `algorithm` attribute on a container element or a heading. All vars within an algorithm are "scoped" to that algorithm.

Note: Algorithms need to have a name. By default, it’ll infer one if there’s only a single `dfn` inside the algorithm container, but if there’s zero or multiple `dfn`s, or you just want to give a clearer name, you can supply it as the value of the `algorithm` attribute, like `algorithm="to foo a bar"`.

Generally, vars are used at least twice in an algorithm: once to define them, and at least once to actually use them for something. If you use a var only once, there’s a good chance it’s actually a typo. Bikeshed will emit a warning if it finds any vars used only once in an algorithm. If this singular usage is correct, you can instruct Bikeshed to ignore the error by adding an `ignore` attribute to the `var` itself. (There’s no way to do this with the `|foo|` syntax; you have to convert it back to an actual `var` element.)

### 5.9. Code Blocks (`pre`, etc)

Bikeshed has several nice features related to "code blocks"—​`pre`, `xmp`, and sometimes `code`.

#### 5.9.1. `pre` whitespace stripping

Using a `pre` element in HTML is unsatisfying, because it forces you to break your indentation strategy, pulling the content back to the margin edge (or else employing silly hacks with comments and explicit newlines). The preprocessor fixes this.

Whenever a `pre` element is encountered, the processor records how much whitespace precedes the first line, and then strips that much whitespace from it and all following lines.

Additionally, if the closing `</pre>` is on its own line, the processor automatically pulls it up onto the end of the previous line, so there’s no final blank line in the content.

In other words, you can now write:

    <div class='example'>
      <p>
        An example:

      <pre>
        &lt;ul>
          &lt;li>one
          &lt;li>two
        &lt;/ul>
      </pre>
    </div>

The preprocessor will automatically convert it into:

    <div class='example'>
      <p>
        An example:

      <pre>
    &lt;ul>
      &lt;li>one
      &lt;li>two
    &lt;/ul></pre>
    </div>

#### 5.9.2. `xmp` To Avoid Escaping Markup

The `xmp` element is an old HTML element that’s now deprecated (but still required to be supported). It was intended for markup examples (thus the name), and has magical parsing properties, where its contents (everything until the `</xmp>` closing tag) are treated as literal text, and not interpreted as HTML. In particular, this means that within an `xmp` you don’t need to escape your `<` or `&` characters.

Bikeshed supports using `xmp` anywhere a `pre` can be used; it converts it into a properly-escaped `pre` in the output to avoid validation errors. For example, the two markup examples in the previous section are using `xmp` in this document’s source.

Use of `xmp` is particularly useful for IDL blocks, as IDL uses `<foo>` syntax for higher-order types (like `sequence<DOMString>`). If you’re using a `pre` and don’t remember to escape this, you’ll end up with confusingly-broken IDL, as the `<DOMString>` part is interpreted as an opening HTML tag. If you use `xmp` instead, there’s no need to remember to escape anything; you can write or copy raw WebIDL into the block and it’ll be interpreted correctly.

#### 5.9.3. Syntax Highlighting

You can syntax-highlight code blocks. Just add either a `highlight="foo"` attribute or a `lang-foo` class to the element, or set a Default Highlight metadata, and the element will automatically be syntax-highlighted according to the "foo" language rules. (Setting `no-highlight` closer will turn if off for an element; it looks for the closest ancestor with one of the attributes.)

The syntax highlighter uses Pygments, which supports a large set of languages. See http://pygments.org/docs/lexers/ for the full list. (Use one of the "short names" of the language for the "foo" value.)

Bikeshed comes with a default color scheme based loosely on that of Prism.js. If you would like to use your own color scheme, turn off the automatic styles with a `Boilerplate: style-syntax-highlighting off` metadata, then supply your own.

Note: If you use `highlight=html`, `script` and `style` elements are automatically highlighted with JS and CSS rules. Normative WebIDL blocks (`class=idl`) and CDDL blocks (`class=cddl`) are automatically highlighted, but you can use `highlight=idl` and `highlight=cddl` to highlight non-normative ones.

Note: If your code block already has markup in it, this feature will safely "merge" the highlighting into your existing markup.

#### 5.9.4. Line Numbers

You can automatically generate line numbers for code blocks by adding a `line-numbers` attribute to the element or an ancestor, or setting the Line Numbers metadata to affect all elements. (Setting `no-line-numbers` closer will turn it off for an element; it looks for the closest ancestor with one of the attributes). The numbers are added to each line via CSS generated content, so they’ll always stay in sync and won’t get copied when you highlight a chunk of text.

    Haikus are easy:five-seven-five syllables,spread over three lines.

The lines default to starting at 1; to change that, set the `line-start` attribute on the element to your desired starting value.

If you would like to produce your own line-numbering CSS, turn off the automatic styles with a `Boilerplate: style-line-numbers off` metadata, then supply your own.

Note: Similar to syntax highlighting, this feature will safely "merge" the line-numbers markup into your existing markup. The only complication is if the original markup has elements that span more than one line; in this case, the "line" element will expand to cover all the lines spanned by your original markup. It will still put a line marker on the first and last line of this span, so the effect isn’t too noticeable if the original markup only spans two lines.

#### 5.9.5. Highlighting Particular Lines

If you want to bring attention to particular lines in your code snippet, but need to show more surrounding code for context, you can highlight the important ones with a `line-highlight` attribute.

    Another haiku.This is the important line.Ignore what's down here.

The syntax of `line-highlight` is a comma-separated sequence of either integers (like `5`), or integer ranges (like `2-4`). For example, `line-highlight="2-4, 6"` will highlight lines 2, 3, 4, and 6.

Like `line-numbers` (above), this defaults to considering the first line of the snippet as line 1, but the numbering can be changed with the `line-start` attribute.

If you would like to produce your own line-highlighting CSS, turn off the automatic styles with a `Boilerplate: style-line-highlighting off` metadata, then supply your own.

Note: This feature has the same restriction on line-spanning elements as the `line-numbers` feature does. In particular, if any line being wrapped in a multi-line "line" element is highlighted, the entire "line" element gets highlighted.

### 5.10. Automatic ID Generation

If any heading, issue, or `dfn` element doesn’t have an `id` attribute, one will be automatically generated by the processor, to ensure it’s usable as a link target.

Heading IDs are generated directly from the text contents of the element, cleaning up the characters to be a valid id. This often isn’t the best for complex heading texts, so it’s not recommended to rely on this. (Bikeshed will warn you that it’s generating IDs, and suggest you supply one manually.)

If a heading changed significantly, so that you want to change the ID, but you want links to the old heading ID to still work, put the old ID in an `oldids=""` attribute on the heading element. If there are multiple, comma-separate them.

Issues (elements with `class="issue"`) will generate IDs of the form "issue-###", where "###" is substring of a hash of the issue’s contents. This means that an issue’s ID will be stable against changes elsewhere in the document, including adding or removing issues above it in the source, but will change if you change the contents of the issue.

Definition IDs are also generated directly from the text contents of the element. Most definitions additionally get a prefix, such as "propdef-", to avoid clashes with other definitions.

If an automatically-generated ID would collide with any other ID, it’s automatically de-duped by appending a number to the end. This isn’t very pretty, so if you want to avoid it, supply an ID yourself.

### 5.11. Assertions

Bikeshed provides the ability to mark "assertions" that tests can refer to. The assertion can either be added with the fake element `<assert>` or by adding an `assert` attribute to a `div`. (e.g. `<div assert>`).

For the `<assert>` tag, it will be replaced by a `<span>` tag in the generated source. The `<div>` tag will pass through but the `assert` attribute is removed.

In both cases a unique ID is generated from the tags contents of the form "assert-###", where "###" is a substring of a hash of the assertions contents. This ensures that you have a unique ID that won’t change arbitrarily, but will change when the contents of the assertion change, making it easier to tell when a test might no longer be testing the assertion it points to (because it’s no longer pointing to a valid target at all!).

### 5.12. Automatic Self-Link Generation

Giving IDs to important things in your document, like headings and definitions, is great, but of little use if people don’t know they can link to them. Bikeshed will automatically generate a "self-link" in the margin next to certain linkable elements which just links to the element, so people can click on the link and then just copy the URL from their address bar to get a link straight to what they care about.

Self-links are currently auto-generated for headings, definitions, and issues, and notes, examples, `<li>`s, and `<dt>`s that have been given IDs.

### 5.13. Remote Issues

There are a few ways to easily link to issues in your source repository.

If Markup Shorthands is set to `repository-links yes` (which it is by default), you can also use inline repository links of the form `<#123>` or `<org/repo#123>`. This’ll generate an HTML link pointing to the issue, with appropriate text like issue #1532.

If you’re using `Issue:` paragraphs (as described in § 5.4 Notes, Issues, Examples, Advisements), you can instead write `Issue(###):`, where the `###` is some identifying value for the issue.

By default, it’s assumed this is a GitHub issue, of the form `123`, `#123`, or `org/repo#123`. Plain numbers will refer to the "local" repository (either specified by the Repository metadata, or auto-detected from the source folder), while the more explicit form refers to the specified repository.

This will generate a link to the specified issue at the end of the issue paragraph, like this. [Issue #1532]

If no repository is detected, or the identifier doesn’t look like the above patterns, Bikeshed will check for an Issue Tracker Template metadata to format the issue link instead. This only applies to `Issue():` paragraphs, not inline repository links.

Inline GitHub Issues also affects these `Issue():` paragraphs.

### 5.14. Including Other Files

Sometimes a spec is too large to easily work with in one file. Sometimes there’s lots of repetitive markup that only changes in a few standard ways. For whatever reason, Bikeshed has the ability to include additional files directly into your spec with a <pre class=include> block:

    <pre class=include>
    path: relative/to/spec/location
    </pre>

The included document is parsed just like if it were written in locally, except that metadata blocks aren’t processed. (For various reasons, they have to be parsed before any other processing occurs). This means that the include file can use markdown, data blocks of various kinds (<pre class=anchors>, <pre class=railroad>, etc), and both provide definitions for the outer document and refer to ones defined by the outer document.

Note: All include paths are processed relative to the outermost spec document’s location. If you’re including a document in another folder, and it includes a document itself, take care that your paths are correctly relative to the outermost spec, not to the included file.

If you’re including a block of repetitive markup multiple times, and want to vary how it’s displayed, you can pass additional "local" text macros in the block, which are valid only inside the included file:

    <pre class=include>
    path: template.md
    macros:
      foo: bar
      baz: qux qux qux
    </pre>

With the above code, you can use `[FOO]` and `[BAZ]` macros inside the include file, and they’ll be substituted with "bar" and "qux qux qux", respectively. (Remember that you can mark text macros as optional by appending a `?`, like `[FOO?]`, in which case they’ll be replaced with the empty string if Bikeshed can’t find a definition.)

#### 5.14.1. Including Code Files

While it’s easy to include short code snippets in your document inline with an ordinary `<pre>` block (particularly with a highlight attribute so it’s formatted nicely), you sometimes want to instead include snippets of a larger external file. (For example, so you can keep that file up-to-date easily, without having to go in and fiddle with all the chunks you’ve inlined into your document.)

Normal includes don’t work for this, as they include the whole file and assume that it’s more Bikeshed code; instead, use `<pre class=include-code>` to include part (or all) of a file and have it rendered as highlightable source code.

    <pre class=include-code>
    path: bigFile.cpp
    highlight: c++
    show: 100-120
    </pre>

This snippet will create a nicely highlighted code block containing lines 100-120 of the file `bigFile.cpp`.

You can additionally include any of the more advanced highlighting options (§ 5.9.4 Line Numbers, § 5.9.5 Highlighting Particular Lines), using the same names and value syntax as you would use when specifying them as attributes:

    <pre class=include-code>
    path: someFile.cpp
    highlight: c++
    line-numbers:
    line-highlight: 2-5, 10, 12
    </pre>

If any of your options cause line-numbers to show up (using `line-numbers` or `line-highlight`), and you’re showing a snippet of the larger file with `show`, the numbering will default to using the numbering of the original file (so if you said `show: 6-10`, the first visible line will be numbered "6"). You can override this with `line-start`, as usual.

Note that, unlike `<pre class=include>`, there is no `macros` option.

#### 5.14.2. Including Non-Bikeshed HTML/SVG/etc

`<pre class=include>` lets you insert chunks of Bikeshed source code into a larger outer document. But what if you want to include some markup that isn’t formatted as Bikeshed code? For example, SVG outputted by a design tool might not conform to Bikeshed’s syntax—​it might not indent properly, or it might use markup that will get messed up if parsed as Markdown, etc.

To avoid this, you can use `<pre class=include-raw>`. Just like `<pre class=include>`, it takes a single `path` line:

    <pre class=include-raw>
    path: myDiagram.svg
    </pre>

…and replaces itself with that markup directly, without doing any additional Bikeshed syntax processing.

Note: Unlike `<pre class=include>`, there are no local `macros`, as macro substitution is part of Bikeshed’s syntax processing, which is skipped here.

Note: Most parts of later Bikeshed processing do work, such as linking to definitions, etc., because inclusions are processed very early in Bikeshed’s transformation pipeline. However, if you’re writing something that’s intended to use Bikeshed’s features, you should really write Bikeshed source code and use `<pre class=include>`, in case some things move to being part of syntax processing. For example, inline autolinking shorthands currently aren’t, and so will work in include-raw substitutions, but that will change in the future.

### 5.15. Tracking Vectors

A tracking vector can be annotated with the `tracking-vector` attribute on the enclosing element. This will result in a link containing an image being prepended to the element.

    <p tracking-vector>This is an example of an element annotated with that attribute.

This is an example of an element annotated with that attribute.

The various "Tracking Vector *" metadata keys can be used to customize the appearance of this annotation, though it’s encouraged to leave those in their default state for a consistent appearance across standards.

### 5.16. Image Size Detection

If an `img` element has a neither a `width` nor a `height` attribute, Bikeshed will automatically detect these dimensions from the image file and insert both attributes into the resulting markup.

Given this markup:

    <img alt="…" src="img.jpg">

if the `img.jpg` file is 300 pixels wide and 100 pixels tall, bikeshed will generate the following output:

    <img alt="…" src="img.jpg" width="300" height="100">

Bikeshed will also detect and insert the dimensions of the image if the element has no `src` attribute but does have a `srcset` attribute. In that case, it accepts a narrow subset of the `srcset` syntax: a single image source URL followed by a single pixel density descriptor, limited to integers. Since the `src` attribute is mandatory in HTML, bikeshed will also add it to the output.

In order to specify high resolution images, use the following syntax:

    <img alt="…" srcset="highDPI.jpg 2x">

If the `highDPI.jpg` file is 600 pixels wide and 200 pixels tall, bikeshed will generate the following output:

    <img alt="…" src="highDPI.jpg" srcset="highDPI.jpg 2x" width="300" height="100">

Note: Bikeshed will only successfully detect the size of local images, and will not attempt to fetch resources over the network, as there is no way for Bikeshed to know whether the size it would get is stable. Using local images is generally preferred, but if you need to use a remote one, consider setting the `width` and `height` manually.

If either of the `width` and `height` attributes is already set (or both are), or if both the `src` and `srcset` attributes are set, Bikeshed will assume you know what you’re doing, skip detection, and leave the element unchanged.

To opt out of this automated size detection for a single image, set the boolean `no-autosize` attribute on it. To opt out for the entire document, specify the Image Auto Size metadata with the value false.

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