# Bikeshed Documentation

## Living Standard, 19 December 2025

Crucial to the processor’s ability to automatically generate most of a spec’s boilerplate is a small metadata section, typically located at the top of a file.

A metadata block is just a `<pre class='metadata'>` element, with contents like:

    Status: UD
    TR: http://www.w3.org/TR/css-variables/
    ED: http://dev.w3.org/csswg/css-variables/
    Shortname: css-variables
    Level: 1
    Editor: Tab Atkins Jr., Google, http://xanthir.com/contact
    Editor: Daniel Glazman, Disruptive Innovations, daniel.glazman@disruptive-innovations.com
    Abstract: This module introduces cascading variables as a new primitive value type that is accepted by all CSS properties,
      and custom properties for defining them.

The syntax of a metadata block is very simple - it’s a line-based format, with each line consisting of a key and a value, separated by a colon. Or if you’re adding multiple lines with the same key, you can just start the subsequent lines with whitespace to have it reuse the last-seen key.

Several keys are required information, and will cause the processor to flag an error if you omit them:

- Title is the spec’s full title, used to generate both the `title` and `h1` of the document. This can alternately be specified by adding an `h1` element as the first line of the spec.

  Note: The optional H1 metadata lets you specify the text you want for the document’s `h1`, if for some reason you want the `title` and `h1` to have different text. For example, some browsers interpret markup as literal text in `title`, so you may want to provide "plain text" in the Title metadata and marked-up text in H1.

- Org, Group, and Status collectively define the spec’s doctype. All are technically optional, but are used to select the correct boilerplate files and control how some macros are generated.

  All the recognized Org/Group/Status values are stored in the `doctypes.kdl` data file, and can be amended via PR there. This data file is automatically picked up by `bikeshed update`.

  Note: Org/Group/Status values are case-insensitive.

  - Org is the overall "organization" that the spec is being published under. An org can have its own set of "default" boilerplate files that all groups underneath it use by default (if they don’t supply specialized ones for themselves).

    You often don’t need to specify Org at all; it can usually be inferred from your Group, or explicitly specified in Group or Status by using a `/` to separate it from the other value. For example, a document published in the W3C org can merely say `Status: w3c/WD` to both specify that it’s in the W3C org and that it’s using the (W3C-specific) Working Draft status; or it can use `Group: csswg; Status: WD` to infer that it’s in the W3C org (as the CSSWG Group is unique in the data file, and part of the W3C org.)

    The currently recognized Org values are:

    - AOM

    - FIDO

    - ISO

    - KHRONOS

    - TC39

    - W3C

    - WHATWG

    If your organization is using Bikeshed and is not listed here, feel free to PR the doctypes file to add it, along with some boilerplate files in that same repository.

  - Group specifies the "group" publishing the spec, identifying a subset of the Org. This allows a group to use a different set of boilerplate files than the generic Org.

    Groups might also have "types", and Orgs can restrict certain Status values to only certain "types" of Groups. This is specified in the doctypes file. (For example, in the W3C Org, the CSSWG Group can’t use the FINDING Status, as that’s restricted to the TAG Group.

    Groups, along with Statuses, can also dictate additional required Metadata values for their specs. This is specified in the doctypes file.

    Rather than listing all the recognized Group values here, please refer to the doctypes file for information. As this file is maintained manually, if your group is not currently present in the file, feel free to fix this via a PR.

  - Status is the spec’s type/maturity status. This can control what specific boilerplate files are used, how some macros are generated, and even how links are resolved (preferring "snapshot" or "current" drafts to link to).

    Statuses, along with Groups, can also dictate additional required Metadata values for their specs. This is specified in the doctypes file.

    There are a few general abbreviations that can be used by any Group (or by specs without a Group or Org at all):

    - DREAM: "A Collection of Interesting Ideas"

    - LS: "Living Standard"

    - LS-COMMIT: "Commit Snapshot"

    - LS-BRANCH: "Branch Snapshot"

    - LS-PR: "PR Preview"

    - LD: "Living Document"

    There are a large number of Status values specific to certain Orgs, and within an Org, Statuses can be restricted to certain Groups based on their "type". Please refer to the doctypes file for details.

    Note: The Group/Status compatibility check can be bypassed by not specifying a Group at all, just an Org and a Status (perhaps together, like `Status: w3c/WD`). However, this limits you to the Org-generic boilerplate files; it is preferable to submit a one-line PR to the doctypes file to get your Group recognized.

- ED (or its synonym URL) must contain a link that points to the most current draft (typically the "editor’s draft", or otherwise the version that’s most live and updated).

- Shortname must contain the spec’s shortname, like "css-lists" or "css-backgrounds".

- Level (or Revision, an alias) must contain the spec’s level as an integer or `none` if the spec does not use levels.

- Editor must contain an editor’s information. This has a special format of comma-separated clauses the first is required and must contain the editor’s name; all the rest are optional.

  - If editing a W3C document, your W3C ID (the number at the end of the url when you navigate to https://www.w3.org/users/myprofile) can be added as a `w3cid ####` clause.

  - Your affiliation (company you work for, etc), optionally followed by a link to their homepage, like `Example Company http://example.com`. If your affiliation contains a comma, HTML-escape it (`&#44;`).

  - Your email address.

  - Your homepage.

  All of the optional clauses can occur in any order, except that affiliation must occur before email or homepage.

  Multiple Editor lines can be used to supply multiple editors.

- Abstract must contain an abstract for the spec, a 1-2 sentence description of what the spec is about. Multiple Abstract lines can be used, representing multiple lines of content, as if you’d written those multiple lines directly into the document.

There are several additional optional keys:

- Die On and Die When give the same control that the `--die-on` and `--die-when` command-line options do. They take the same values—​a single keyword—​as the corresponding command-line arguments.

- H1 contains the text/markup that goes into the document’s `h1` element. If omitted, this defaults to the value of the Title metadata, which is usually what you want.

- TR must contain a link that points to the latest version on /TR.

- Canonical URL defines the canonical URL (as used by search engines) for the document; it can be set to "TR" (the default value if TR is defined), "ED", or a specific URL.

- Favicon defines the favicon URL for the document; it only supports one single URL.

- Logo defines the logo url for the document; it only supports one single url. This URL can be used via the `[LOGO]` text macro (§ 5.3 Text Macros), and is by default used by the `logo` boilerplate section (§ 13.3 Boilerplate Sections).

- Former Editor must contain a former editor’s information, in the same format as Editor.

- Warning must contain either "Obsolete", "Not Ready", "New Version XXX", "Replaced by XXX", "Commit deadb33f http://example.com/url/to/deadb33f replaced by XXX", "Branch XXX http://example.com/url/to/XXX replaced by YYY", or "Custom", which triggers the appropriate warning message in the boilerplate.

  If set to "Custom", the metadata keys Custom Warning Title and Custom Warning Text control what the warning contains.

- Previous Version can contain either a URL to a previously-published version (such as versions published on w3.org/TR), or the value `from biblio` or `from biblio my-spec-1`.

  Links get displayed literally in the spec’s metadata section. "from biblio" entries instead auto-generate a link to the latest dated version of the given versioned shortname that appears in the biblio database. (If omitted, the spec’s own versioned shortname is implicitly used.)

- At Risk must contain an at-risk feature. You can specify this key more than once for multiple entries.

- Dark Mode must contain a boolish for whether or not Bikeshed includes darkmode-relevant colors/etc for all of its built-in styles.

  It defaults to "on", but if you provide custom styles that are not darkmode-aware, you should set this "off" so Bikeshed features don’t render for darkmode and become unreadable against your lightmode styles.

- Status Text allows adding an additional customized sentence that can be used in the document status section.

- Ignored Terms accepts a comma-separated list of terms and makes Bikeshed not emit warnings or errors when attempting to autolink those terms. Use this to quiet spurious preprocessor warnings caused by you inventing terms (for example, the Variables spec invents custom properties like 'var-foo'), or as a temporary patch when the spec you want to link to doesn’t set up its definitions correctly.

- Date must contain a date in YYYY-MM-DD format, which is used instead of today’s date for all the date-related stuff in the spec. Alternately it can contain the string `now`, which explicitly indicates a date of precisely when the output is generated.

- Deadline is also a YYYY-MM-DD date, which is used for things like the LCWD and CR Snapshot Status section, to indicate deadlines.

- Expires is also a YYYY-MM-DD date, or can be the string `now` to indicate today’s date, or can be an "ISO Duration" like `P1Y` to indicate "+1 year" from the Date metadata (or the spec’s generation date if that’s not specified), and indicates when the document should be considered "expired"—​before the expiration date an (initially closed) warning about the upcoming expiration is automatically included in the document; afterwards the warning defaults to being open and annoying.

  It can also take a boolish false value or `never` to indicate it never expires; this is just the default value, so these values are only useful for turning off a default expiration established by your default metadata.

- Test Suite must contain a link to the test suite (like `https://test.csswg.org/suites/css-flexbox-1_dev/nightly-unstable/`).

  Note: This merely displays a "Test Suite" item in the spec’s header-list, as linked text. To display WPT results, see § 12 Testing Integration With WPT.

- Implementation Report must contain a link to an implementation report, either a hand-written document or just a link to the spec’s folder on wpt.fyi. This is required for W3C Candidate Recommendation Snapshot.

- Mailing List must contain an email address to be used for mailing lists.

- Mailing List Archives must contain a link to the list archives.

- Issue Tracking indicates what and where you track issues, and will result in an "Issue Tracking" entry in your spec header. It must contain a comma-separated list of locations, each of which consists of the name of the location followed by the url.

  Bikeshed will automatically add additional entries to this in some situations: if you use any inline issues, you’ll automatically get an "In Spec" annotation; if you develop from within a git repo with a GH remote, or have the Repository metadata set, you’ll automatically get a "GitHub" annotation.

  You can turn off the spec-header entry entirely with `Boilerplate: feedback-header off`, or just turn off the GitHub entry specifically with `Boilerplate: repository-issue-tracking off`.

- Issue Tracker Template specifies a url template used to point remote issues at your issue tracker of choice. It takes a url, with `{0}` in the place where you want the remote identifier to go.

- Translation indicates a translation of the document. At minimum it consists of a language code (BCP47 format) and a url. Optionally, it can contain comma-separated `name [name-in-spec-language]` and `native-name [name-in-translation-language]`, but if Bikeshed knows about that language, these will be filled in for you. (If Bikeshed doesn’t know about a given language, let me know what its name is in English and itself!)

- Indent tells Bikeshed how many spaces you prefer to use to indent your source code, so it can properly parse your Markdown and data-blocks. It takes a single integer, and defaults to `4` if unspecified. (Of course, using tabs avoids this entirely, as one tab is always one indent.)

- No Editor lets you omit the `Editor` metadata without an error. It takes a boolish value. This shouldn’t generally be used; even if your organization doesn’t privilege editors in any way, putting the organization itself in the `Editor` field meets the intent while still producing useful information for readers of the spec.

- No Abstract lets you omit the `Abstract` metadata without an error. It takes a boolish value. This should only be used for very small and trivial documents, where the abstract would just be repeating the title of the more-or-less.

- Editor Term is a pair of comma-separated terms giving the singular and plural terms to refer to editors with, if you want something other than the default "Editor(s)".

- Default Ref Status takes the values "current" or "snapshot", and selects which URL you want to default to for bibliography and autolinks entries that have both "current" and "snapshot" URLs. (You can also specify this per-biblio entry or per-autolink.)

- Default Biblio Display takes the values "index" (default), "inline", or "direct" and selects whether biblio autolinks default to displaying as their shortname and linking to the bibliography index ("index"), displaying as their title and linking straight to the referenced document ("inline"), or displaying as their shortname and linking to the referenced document ("direct"). (You can also specify this per-biblio entry.)

- Markup Shorthands lets you specify which categories of markup shorthands you want to use; for example, you can turn off CSS shorthands and reclaim use of single quotes in your spec. You can still link to things with HTML links (`<a dfn>some term</a>`) or with the `l` element (`<l>[=some term=]</l>`) even if the shorthand is turned off. Its value is a comma-separated list of markup categories and boolish values, like `css no, biblio yes`. The currently-recognized categories are:

  - `algorithm`, covering the special `var` shorthand (the `|foo|` shorthand)

  - `biblio`, covering the dfn autolinks for biblio links and section links (the `[[foo]]` shorthands)

  - `cddl`, covering the dfn autolinks for CDDL types (the `{^foo^}` shorthand)

  - `css`, covering the dfn autolinks for CSS types

  - `dfn`, covering the dfn autolinks for "dfn" and "abstract-op" type definitions

  - `http`, convering the dfn autolinks for "http-header" type definitions

  - `idl`, covering the dfn autolinks for WebIDL types (the `{{foo}}` shorthand)

  - `markdown`, covering the various inline Markdown syntaxes (block-level Markdown is always supported)

  - `markup`, covering the dfn autolinks for HTML/etc elements and attributes (the `<{foo}>` shorthand)

  - `macros-in-autolinks`, which allows macros in autolinks. That is, it allows `[=[FOO]=]`, which can expand the `[FOO]` macro to produce something like `[=the long foo term you don’t want to re-type=]`. (Without this, all text in the link-data portion of an autolink is interpreted literally, with no parsing or substitution.)

    Note: Macros are always allowed in the link-text portion of an autolink, like `[=foo|some text about [FOO]=]`, as normal parsing occurs there.

  - `repository-links`, which allows inline links to repository issues. See § 5.13 Remote Issues.

  `markdown` and `macros-in-autolinks` default to "off"; the rest default to "on".

- Text Macro lets you specify custom text macros, like `[TITLE]` or `[DATE]`, letting you fill in different text when building a spec in multiple ways. (This is mostly useful as a command-line option.) Each Text Macro line consists of a macro name, which must be uppercase and alphanumeric, followed by the text it will get replaced with.

- Work Status indicates the status of the document, in a way unrelated to the publication status of Status. It must be one of (completed, stable, testing, refining, revising, exploring, rewriting, abandoned), with those terms defined in Fantasai’s blog. This just sets the `[WORKSTATUS]` text macro to the corresponding word, used in some of the boilerplates to pipe the metadata to scraping tools.

- Repository indicates the repository the spec is being tracked in. You can specify a url followed by a "short name" for it, and it populates the `[REPOSITORY]` and `[REPOSITORYURL]` text macros accordingly. If you are using GitHub, you can just specify `username/repo`, and Bikeshed will infer the rest for you. If you’re developing from within a GitHub repo, you don’t need to specify this at all, as Bikeshed will figure it out automatically! (That said, if you’re working in a fork, you should still specify the main repo’s information here, or else the spec will point to your fork instead.)

  If using GitHub, this metadata causes Bikeshed to automatically add a "GitHub" annotation to the Issue Tracking entry in your spec header. You can turn this off with `Boilerplate: repository-issue-tracking off`.

- Inline Github Issues tells Bikeshed whether to fetch the text of GitHub issues and inline them into the document, or not. It takes a boolish value, or the values "full" or "title". If it’s true or "full", any remote issues of the form `user/repo#issuenumber` will have their contents replaced by the contents of the corresponding issue from GitHub; if it’s "title", they’ll have their contents replaced by just the title of the remote issue (so a large, well-written initial issue post doesn’t derail a spec). If your Repository is set up to a GitHub repo, remote issues with just an issue number will also be expanded to the corresponding issue from your repository.

- Opaque Elements and Block Elements are a comma-separated list of custom element names, to help control Bikeshed’s parsing and serialization. By default, custom elements are treated as inline; marking an element as "opaque" makes it like `pre`, so shorthands and Markdown aren’t processed in it, and it’s serialized precisely as entered; marking an element as "block" makes it interrupt paragraphs when it starts a line, and causes the pretty-printer to serialize it in a block-like way.

- Note Class, Issue Class, Assertion Class, and Advisement Class specify the class name given to paragraphs using the note/issue/advisement markup shorthand. They default to "note", "issue", and "advisement".

- Informative Classes is a comma-separated list of classes that should be considered "informative" or "non-normative"—​elements with these classes must not contain definitions or requirements, and Bikeshed will verify this for you (either automatically, or via the `Complain About: accidental-2119` metadata). "note", "example", "informative", and "non-normative" all trigger this behavior by default.

- Translate IDs maps Bikeshed-generated IDs to manually-specified IDs, for cases where you need to manually specify an ID but it’s generated by Bikeshed in a hard-to-override way (like IDL blocks). It takes a comma separated list of Bikeshed IDs and new IDs.

- Default Highlight specifies the default highlighting language. Every `pre`, `xmp`, and `code` will automatically be highlighted according to the specified language, unless they or an ancestor specifies a different `highlight=foo` or `nohighlight` attribute overriding it.

- Line Numbers is a boolish specifying whether, by default, code blocks (`pre` and `xmp`) should get line numbers. Defaults to off.

- Toggle Diffs is a boolish that specifies whether Bikeshed should include a 'Hide deleted text' button to toggle hiding `del` elements in your spec header. Defaults to off.

- Boilerplate toggles the generation of individual boilerplate sections. Its value is a comma-separated list of section name and boolish value, e.g. `Boilerplate: issues-index no` to disable the list of issues.

- Local Boilerplate tells Bikeshed which boilerplate include files to look for relative to the specification (as opposed to inside the Bikeshed source). Its value is a comma-separated list of include file basename and boolish value, e.g. `Local Boilerplate: footer yes` to look for `footer.include` and `footer-[STATUS].include` next to the specification. This also works for default includes that aren’t quite boilerplate like defaults.include, computed-metadata.include, and bs-extensions.include.

- External Infotrees lists which of anchors.bsdata and link-defaults.infotree should be found in files adjacent to the specification instead of in `<pre>` blocks inside it.

- Complain About indicates what nits you’d like Bikeshed to complain about, that are normally too noisy to be turned on by default. Its value is a boolish list like Markup Shorthands. Accepted values are:

  `accidental-2119`

    Complains about usage of RFC 2119 terms (may, must, should, etc) in non-normative sections. If you need to use one of those terms (such as in an example about using them), you can put a `class=allow-2119` on the text’s immediate parent element.

  `broken-links`

    Checks all the external links in the document, and verifies that they result in a 200 response code. See Link Checker Timeout to control this.

  `missing-example-ids`

    Complains about examples without a manually-specified ID. (Examples auto-generate an ID based on their contents otherwise, which might not be stable over time.)

  `mixed-indents`

    Checks that all of your line-starting whitespace is either tabs or spaces, not both. (Complains both about a line using spaces when your document otherwise uses spaces, and a line using a mix of tabs and spaces at once.)

    This intentionally skips lines in "raw" elements like `pre`, because mixing tabs and spaces is completely reasonable there: using tabs to match the indent of the opening tag, then spaces to align the preformatted text.

    This value is turned on by default. You can turn it off with `Complain About: mixed-indents no`

- Link Checker Timeout takes a pair of ints, specifying the timeouts for the `Complain About: broken-links yes` link checker, in seconds. The first value is the per-link timeout, the second is the global timeout for all links. Defaults to 5 and 10.

- Infer CSS Dfns is a boolish that specifies whether Bikeshed should try to "infer" what type a `dfn` is by looking at the text, using CSS-biased heuristics. (In other words, this’ll only auto-detect certain CSS types.) Defaults to off.

- Assume Explicit For is a boolish that specifies whether an omitted `for` attribute on an autolink should imply `for="/"` (that is, selecting a definition without a `for` value), or just not express a `for` requirement at all (that is, selecting a definition without caring about what its `for` value is). Truthy values set the former, falsey set the latter. Defaults to off.

  Note: Turning this on is a better match for some people’s mental models, but it requires you to specify more `for` values on your autolinks even when it’s not necessary to disambiguate things, so it’s off by default.

- Max ToC Depth specifies the maximum depth you want the ToC to generate to. It can be the value "none", meaning generate the ToC normally, or an integer between 1 and 5. It defaults to "none".

- Several keys related to the MDN project:

  - Include MDN Panels is a soft boolish that specifies whether to include MDN panels or not. If it’s turned on, MDN panels will be added automatically in output, positioned to line up with the elements which define the features the panels annotate. Each MDN panel includes a hyperlink to the MDN article for the feature it annotates, as well as browser-support details for the feature (similar to what’s shown in the panels added when Include Can I Use Panels is enabled).

    Because this examines MDN links for the IDs to use, no configuration is necessary beyond turning the feature on; the panels will automatically be added to the definitions or headings with the associated IDs.

    If your spec is not yet in MDN, but you’d like the panels to be added when it shows up, you can pass one of the "maybe" values of a soft boolish to allow it to silently upgrade when possible; otherwise, if directly turned on, it will emit a fatal error if it can’t find your spec.

  - Ignore MDN Failure takes a comma-separated list of IDs that MDN is attempting (and failing) to target, and prevents Bikeshed from emitting a warning if it can’t find that ID. This allows you to have avoid having a build warning while waiting for MDN to be updated.

- Several keys relate to the Can I Use project:

  - Include Can I Use Panels is a boolish that specifies whether to include Can I Use usage-data panels or not. If it’s turned on, elements can take a `caniuse="featureID"` attribute, where the `featureID` is the value specified in the url like `https://caniuse.com/#feat=FEATUREIDHERE`, and the panel will be positioned to line up with that element. (When possible, put this on the corresponding `dfn`, as the panel doesn’t have any special indication of what feature it’s for; if you don’t, you must ensure the element has an ID of its own.)

  - Can I Use URL automatically informs you when/if Can I Use starts tracking new features from your spec, so you don’t have to check that yourself. It takes a single URL prefix, and can be specified multiple times to provide multiple URLs. These URLs are checked against the Can I Use data, and if there are any Can I Use features whose URL includes one of the specified URLs as a prefix, and the feature isn’t already specified somewhere in your spec, it will log a warning for you.

  - Ignore Can I Use URL Failure takes one of the URLs specified in Can I Use URL, and suppresses the warning that Bikeshed emits if the URL doesn’t show up in the Can I Use database. (This error exists to help catch typos, rather than just letting it silently fail.) This allows you to put your URL in pre-emptively, and get an error only when Can I Use does include your specification (and you thus have features that aren’t being tracked in your spec).

- Custom Warning Title specifies the title of a "custom" warning, requested via `Warning: custom` metadata.

- Custom Warning Text specifies the body of a "custom" warning. Like Abstract, it accepts multiple lines, and is parsed as Markdown (as if you’d written them directly into the document).

- Prepare For TR is a boolish that specifies whether or not to apply a bunch of automatic "fixups" for common errors that would make a spec fail the W3C’s PubRules check. This is applied automatically when you run the Echidna command to publish your spec, but you can use it manually to check precisely what your spec will look like when published.

- Use Dfn Panels is a boolish that determines whether "definition panels" are generated for every definition; it defaults to true. These "panels" show up when you click on a `dfn`, and show every local reference to the definition.

  It automatically adds some JS and CSS to your page for the panels; you can suppress this with `Boilerplate: script-dfn-panel no, style-dfn-panel no` and supply your own if desired.

- Metadata Include and Metadata Order are defined in § 13.1 Rearranging and Excluding "Spec Metadata".

- Remove Multiple Links is a boolish (defaulting to false) that controls whether Bikeshed automatically suppresses multiple autolinks to the same term in a single paragraph. (That is, if multiple autolinks point to the same URL within a single parent element, all but the first will be reverted to plain `span`s.)

- Slim Build Artifact is a boolish (defaulting to false) that specifies whether or not Bikeshed should try and "slim" the output, to make it more appropriate as an obvious "build artifact", rather than an active usable spec. This turns off various usability features which otherwise bloat your HTML, and which aren’t necessary if the output isn’t intended to be actively used by humans. The exact set of features that are affected by this will evolve over time.

- Required IDs is a list of IDs that the document must contain. This can be used to ensure that certain links into the document don’t rot over time.

- Force Crossorigin is a boolish that auto-adds the `crossorigin=anonymous` attribute to every relevant element (`link`, `script`, `img`, `audio`, `video`). You can set a different `crossorigin` value manually on the element, or skip the element entirely by putting `nocrossorigin` on it or an ancestor.

- WPT Path Prefix is a partial URL path that specifies a default path prefix for all of the tests in your `wpt` elements. (This can be overridden on an individual `wpt` element.)

- WPT Display takes the values "none", "closed", "open", or "inline", and specifies whether and how `wpt` elements display anything in the output document.

- Tracking Vector Class is the HTML `class` attribute value used on the link inserted in elements annotated with the `tracking-vector` attribute.

- Tracking Vector Image is an image URL that can be used to represent tracking vectors with an external image. Otherwise an inline SVG is used. The image is a child of the aforementioned link. This image will be marked as darkmode-aware, so make sure it actually is.

- Tracking Vector Image Width is the width of the external image, if any.

- Tracking Vector Image Height is the height of the external image, if any.

- Tracking Vector Alt Text is the replacement text for the inline SVG or external image.

- Tracking Vector Title is the title for the inline SVG or external image.

- Image Auto Size is a boolish (defaulting to true) that specifies whether Bikeshed should automatically detect the size of images used in the document.

A boolish value is a string representing a boolean value (true or false). The string "yes", "on", "true", and "y" all represent true values, while the strings "no", "off", "false", and "n" all represent false values.

A soft boolish value is either a boolish value, or one of the strings "maybe", "if possible", or "if needed", indicating an intermediate intention between something being turned on and off.

You can also provide custom keys with whatever values you want, by prefixing the key with `!`, like `!Issue Tracking: in spec`. Any custom keys are collected together and formatted as entries in the "spec metadata" boilerplate `dl`. Specifying a custom key multiple times will put all the values as `dd`s under a single `dt` for the key. A custom key name equal to one of the auto-generated keys will add your custom value as an additional `dd` under that auto-generated key.

Some of the metadata keys are deprecated; you shouldn’t use them, but just in case you run into them in the wild, they’re documented here for understanding. Each one recommends what you should be using instead.

- Use <i> Autolinks turns on legacy support for using `i` elements as "dfn" autolinks. It takes a boolish value.

  Instead of using this, just use the `a` element to autolink, as usual.

- Link Defaults lets you specify a default spec for particular autolinks to link to. The value is a comma-separated list of entries, where each entry is a versioned spec shortname, followed by a parenthesized link type, followed by a "/"-separated list of link phrases. For example, `Link Defaults: html (dfn) allowed to show a popup/in parallel`.

  Instead of using this, use a `<pre class=link-defaults>` block, as the error message suggests when this is necessary.

- Ignored Vars accepts a comma-separated list of variable names, and makes Bikeshed not emit warnings or errors about them being used only once in the document/algorithm.

  Instead of using this, put an `ignore` attribute on the `var` in question.

### 4.1. Default Metadata

To specify default metadata for all specs generated for a given group and/or spec status, add an appropriate `defaults.include` file to the `bikeshed/boilerplate/` folder. This file must be a JSON file, with the keys and values all strings matching the above descriptions.

Here’s an example file:

    {
      "Mailing List": "www-style@w3.org",
      "Mailing List Archives": "http://lists.w3.org/Archives/Public/www-style/"
    }

### 4.2. Computing Metadata From Other Metadata

If your Group produces several specs, and they all share some formulaic metadata that could be auto-generated with a bit of string-replacement, you can achieve this automatically with a "computed-metadata.include" file in the `bikeshed/boilerplate/` folder. It has the exact same syntax as the `defaults.include` file, except that you can use text macros in the file, based on all the previous metadata (defaults, `<pre class=metadata>`, and command-line overrides).

Note: Don’t forget about custom text macros with the Text Macro metadata, if none of the pre-defined ones give you the substitution strings you need.

Note: By necessity from the definition, these metadata override all previous metadata. Make sure that everything you set in this file is really something that every single spec in your Group should have.

Note: Bikeshed assumes that any text macros you use will be used inside of JSON strings, and escapes them accordingly. (In other words, you don’t have to worry about JSON-escaping when writing your macros, but you do need to ensure that all macros occur inside of double-quotes in your computed-metadata.include file.)

### 4.3. Overriding Metadata From The Command Line

If you want to generate multiple versions of a spec from the same source (such as a primary spec, plus some snapshots), you can override the metadata from the command line to generate the alternate forms.

For any metadata key defined above, just pass it as a `--md-foo=bar` command-line argument. For example, to override the Status metadata, run `bikeshed spec --md-status=ED`.

(If the metadata name has spaces in it, use dashes to separate the words instead.)

#### 4.3.1. Known Issues

1. You can’t override the `Use <i> Autolinks` status, because you can’t input the `<>` characters. I don’t intend to fix this, as you shouldn’t be specifying this in the first place.

2. You can’t supply custom metadata keys (ones with a `!` prefix). If you want to do this, let me know, and I’ll work on it.

3. Passing values with spaces in them is tricky. This is an issue with the argparse library. The only way around it is to specify both of the positional arguments (the input and output filenames), then put the offending argument after them.

### 4.4. Ordering Between Metadata Sources

When you specify a particular metadata key multiple times in your document, the exact behavior depends on which metadata key it is, but all of the behaviors depend on the order things appear in. For example, if you specify Title twice, the second one is used.

This also happens when metadata keys are duplicated between multiple sources, like from your `defaults.include` file and your `<pre class=metadata>` block. It’s important, then, to know what order the different sources are resolved in, so you know which key "wins", or in what order a list of things is constructed in.

The ordering is, from first to last:

1. "baseline" metadata (the default values that Bikeshed uses)

2. `defaults.include` metadata

3. `computed-metadata.include` metadata

4. `<pre class=metadata>` blocks in your document

5. command-line metadata

In general, this follows the ordering of least-specific to most-specific.

### 4.5. HTML "Metadata" (`lang=""`, `<meta>`, etc)

Generally, any HTML metadata (attributes on `<html>`, `<meta>` or `<link>` elements) should be handled in your `header.include` boilerplate file. However, sometimes you do need to add additional metadata to a specific document.

For attributes that belong on `<html>`, such as `dir=""` or `lang=""`, simply add an `<html>` element with those attributes into your source file. A quirk of the HTML parser is that multiple `<html>` elements, wherever they appear, coalesce their attributes onto the one "true" `<html>` element that wraps the entire document, rather than actually showing up in the DOM. Bikeshed’s serializer will then output the one true `<html>` element with all the coalesced attributes.

Similarly, if you need to add `<meta>`, `<link>`, or `<style>` elements to your document, simply put them in your source. Bikeshed will automatically transfer them to the `<head>` of the output document. (`<script>` elements are left where they are, as their location can matter.)

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