Make your own theme¶
Audience: anyone who wants caret's review page in colors of their own.
A caret theme is one JSON file. Start from a theme caret ships or from a VS Code theme you already like, edit its colors, then put it in caret's themes folder or upload it from Settings → Appearance. The theme file format lists every field.
Start from a built-in theme¶
caret's built-in themes ship as theme files in
ui/src/lib/themes/.
Copy one, give the copy its own id, then change any field the theme file format
describes.
Start from a VS Code theme¶
Run caret convert-theme <file> to turn a VS Code color theme JSON into a caret theme
file. It prints the theme file to stdout. To write a file instead, pass -o or --out
with a file path, not a folder. The command writes into the
themes folder only when
--out points there:
The input may contain comments and trailing commas (JSONC). The command maps:
syntax: every role, required and optional, from the theme's token rules, as VS Code would color each scope. A token no rule colors takes the theme'seditor.foreground, or VS Code's default for itstypewhen it sets none, with asyntax:note. AtokenColorsrule with noscopeis ignored, as VS Code does.scheme: from the theme'stype.darkandhcDark(high contrast) becomedark;lightandhcLightbecomelight.palette: the required colors, a best-effort pick from the theme'scolors. A color with no clear source, missing or translucent, takes caret's own color for the scheme and is printed as apalette.<key>:note. The optional hues are left out, so caret derives them.idandlabel: from the theme'sname, or the file name when it has none. Anidthat matches a built-in theme gets-customappended, with a note.
Notes go to stderr as caret convert-theme: <note> and leave the exit code 0. The command
prints the reason, exits 1, and writes nothing when the theme:
- uses
include; - has a
tokenColorsthat names a.tmThemefile; - has no recognized
type; - can't be mapped for another reason, which it names.
Treat the output as a starting point: check the noted colors and tweak what you like.
Get editor support¶
Set $schema to
https://raw.githubusercontent.com/macintacos/caret/HEAD/docs/theme.schema.json, as the
example does. An editor that understands JSON
Schema, such as VS Code, then completes field names and flags invalid values as you type.
Add the theme to caret¶
Save the file in the themes folder, ~/.config/caret/themes (or
$XDG_CONFIG_HOME/caret/themes when that is set), then reload the review page. The theme
appears in the theme picker for its scheme in Settings → Appearance. Each file that
didn't load is listed there with its errors, under the theme pickers.
Upload a theme¶
Click Upload theme file… in Settings → Appearance. caret checks the file against
the same
rules as the themes folder
and saves it into the themes folder as <id>.json, named from its id, never from the
uploaded file's name. A file that fails shows its errors, and caret saves nothing. caret
rejects the id of a built-in theme.
Uploading an id that another file already declares replaces that theme: caret writes
<id>.json and removes the other files. If caret can't remove one of those other files,
it still saves the upload and names the file it left; caret loads neither until you delete
that file.
caret refuses the upload when <id>.json already holds a theme with a different id that
caret loads. If caret skips that file, because its id is built in or another file
declares it too, the upload replaces it.
Remove a theme¶
Delete its file from the themes folder. There is no delete control.