Bikeshed Documentation

Living Standard,

4. Metadata

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:

There are several additional optional keys:

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

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

← 3 Invoking Bikeshed Locally Table of Contents 5 Markup Shortcuts →

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.