# Bikeshed Documentation

## Living Standard, 19 December 2025

Sometimes it’s the source file you want to preprocess, if there is some feature you want literally in your source that is hard or annoying to type in yourself. Bikeshed has some options for doing this as well.

All of these commands are accessed from the `source` sub-command, like `bikeshed source`. You can run individual commands by specifying their relevant flag (see `bikeshed source -h` for a list), or run all of them by not passing any flags.

### 15.1. Big Text

When editing a large spec, it’s easy to get lost in its length, and have to spend some time scrolling back and forth to find particular sections.

The Sublime Text editor has a special feature, the minimap, which shows an extremely-zoomed out version of your document while you scroll, so you can recognize where you are in the file by the shape of your code. This can be made even easier by putting extra-large "ASCII art" text in your source to label major sections, so they show up visibly in the minimap as section markers.

Bikeshed can auto-generate this "ASCII art" text for you with its `--big-text` command. Just add an HTML comment to your document on its own line that looks like:

    <!-- Big Text: Your Text -->

If you run `bikeshed source --big-text`, Bikeshed will replace it with a comment that looks like:

    <!-- Big Text: Your Text

    █   ▐▌  ███▌  █▌  █▌ ████▌      █████▌ █████▌ █     █ █████▌
    ▐▌  █  █▌  █▌ █▌  █▌ █▌  █▌       █▌   █▌      █   █    █▌
     █ ▐▌  █▌  █▌ █▌  █▌ █▌  █▌       █▌   █▌       █ █     █▌
     ▐▌█   █▌  █▌ █▌  █▌ ████▌        █▌   ████      █      █▌
      █▌   █▌  █▌ █▌  █▌ █▌▐█         █▌   █▌       █ █     █▌
      █▌   █▌  █▌ █▌  █▌ █▌ ▐█        █▌   █▌      █   █    █▌
      █▌    ███▌   ███▌  █▌  █▌       █▌   █████▌ █     █   █▌
    -->

Which is clearly visible from Sublime’s minimap!

You can also edit the first line to change the text, re-run `bikeshed source --big-text`, and it’ll swap out the text art with your new text.

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