BBEdit Cheat Sheet File Format

[Note: The information in this document applies to BBEdit 15.0 and later.]

Introduction

BBEdit 15 cheat sheets reside in the Cheat Sheets application support folder, which is accessible by choosing the corresponding menu item from the "Folders" menu item on the BBEdit application menu.

Files added or removed from this folder will appear on the "Cheat Sheets" submenu of BBEdit's Window menu.

Changes made within cheat sheet files will take effect the next time the corresponding cheat sheet palette opens. Thus, if a cheat sheet file is changed on disk while the cheat sheet palette is open, close and reopen the palette in order to see the changes.

File Format

Cheat Sheet files are written as JSON, and may contain comments as documented here. The file must be valid and well formed, and the file's name must end with .json.

The following descriptions of keys and values make reference to an example cheat sheet, which itself is derived from BBEdit's built-in Markdown cheat sheet. You can download the example here.

Basic Structure

A cheat sheet consists of the following five keys:

1. com.barebones.documentType: required, and must always be "CheatSheet".

2. com.barebones.DocumentFormatVersion: required, and must always be "1".

3. CheatSheetName: required; must be a non-empty string.

4. LanguageCode: optional; if present must be a four-character code corresponding to an installed language.

5. Hints: required; this is the array of entries for the cheat sheet itself.

BBEdit uses CheatSheetName in the user interface, as the title of the cheat sheet palette and corresponding menu item.

The LanguageCode value, if present, determines syntax coloring for the cheat sheet entries as displayed in the palette. You can use “MRKD” if you would like them colored as Markdown; or omit this key to treat them as plain text. You can also use the four-character code of any installed language, but the entries won't be colored if you specific an invalid or missing language code.

The Hints array is ordered, and entries in the palette are listed in the order they appear in the array.

Hints Format

An entry in the Hints array consists of (at minimum) two key/value pairs:

1. description: The text description of the entry. This appears in the right-hand column of the cheat sheet palette. This value is required and must be non-empty.

2. text: The text that inserted when the entry is invoked (by double-clicking, or by dragging and dropping it to the desired location). This value is required and must be non-empty.

Because the text value can contain Clippings placeholders, it may not always be suitable for display. Therefore a third, optional (but recommended) value is available:

1. displayText: If present, the text to be displayed in the left column of the cheat sheet's palette.

If a LanguageCode value was supplied, the text in the left-hand column (whether from displayText or from text) is colored using the specified language.

Here is an example entry:

{
    "description" : "Strong emphasis",
    "text" : "**#SELECTIONORPLACEHOLDER text#**",
    "displayText" : "**text**"
}

Because the text uses the "#SELECTIONORPLACEHOLDER #" clipping placeholder in order to generate an editing placeholder, it's not really appropriate for display. Thus, the displayText value contains a string that is more readable in the cheat sheet's palette.

---

Back to Technical Notes