clone
ssh://git@git.notashelf.dev:33/notashelf/beer.git| 1 | beer-themes(7) |
| 2 | |
| 3 | # NAME |
| 4 | |
| 5 | beer-themes - colour theming for _beer_(1) |
| 6 | |
| 7 | # DESCRIPTION |
| 8 | |
| 9 | A *beer* theme is an ordinary _beer.toml_(5) fragment that sets the *[colors]* |
| 10 | table. Because *--config* is repeatable and later files win, a theme is best |
| 11 | kept in its own file and layered over the main config: |
| 12 | |
| 13 | ``` |
| 14 | beer --config ~/.config/beer/beer.toml --config ~/.config/beer/themes/dark.toml |
| 15 | ``` |
| 16 | |
| 17 | or listed in *BEER_CONFIG*. Everything a theme can set is described under |
| 18 | *[colors]* in _beer.toml_(5); this page explains how the pieces fit together |
| 19 | and how applications recolour the terminal at runtime. |
| 20 | |
| 21 | Colours are X11 specs: _#rrggbb_ or _rgb:rr/gg/bb_ (1-4 hex digits per channel). |
| 22 | |
| 23 | # THE PALETTE |
| 24 | |
| 25 | Terminals address colour in three layers, and a theme can set all of them: |
| 26 | |
| 27 | *Default foreground and background* |
| 28 | *foreground* and *background* are the colours used when a cell selects no |
| 29 | explicit colour (SGR 39 / 49). |
| 30 | |
| 31 | *The 16 named colours* |
| 32 | *regular* (indices 0-7) and *bright* (8-15) are the ANSI palette an |
| 33 | application selects with SGR 30-37, 40-47, 90-97, and 100-107. Unset entries |
| 34 | keep the built-in xterm values, so a theme may override only the entries it |
| 35 | cares about. |
| 36 | |
| 37 | *256-colour and truecolor* |
| 38 | Indices 16-255 are the standard xterm cube and greyscale ramp and are not |
| 39 | configurable; direct 24-bit colours (SGR 38;2 / 48;2) are used verbatim. |
| 40 | |
| 41 | *bold-as-bright* renders bold text in the bright variant of its colour, the |
| 42 | traditional terminal behaviour; set it _false_ to keep bold text in its base |
| 43 | colour. |
| 44 | |
| 45 | # CURSOR AND SELECTION |
| 46 | |
| 47 | *cursor* sets the cursor colour; left unset, the cursor inverts the cell beneath |
| 48 | it. *selection-foreground* and *selection-background* colour selected text, and |
| 49 | *match-background* and *match-current-background* colour scrollback search |
| 50 | matches and the focused match. |
| 51 | |
| 52 | # TRANSPARENCY |
| 53 | |
| 54 | *alpha* sets background opacity from _0.0_ (fully transparent) to _1.0_ (opaque) |
| 55 | via premultiplied ARGB; only the background is made translucent, and any blur is |
| 56 | left to the compositor. |
| 57 | |
| 58 | # RUNTIME COLOUR ESCAPES |
| 59 | |
| 60 | Applications and colour-scheme tools can change the palette live; *beer* honours |
| 61 | the standard OSC sequences and answers a *?* query with the current value: |
| 62 | |
| 63 | [[ *OSC* |
| 64 | :< *Effect* |
| 65 | | *4* ; _n_ ; _spec_ |
| 66 | : Set palette index _n_; *104* resets one or all indices |
| 67 | | *10* / *11* / *12* |
| 68 | : Set default foreground / background / cursor colour |
| 69 | | *110* / *111* / *112* |
| 70 | : Reset foreground / background / cursor to the configured value |
| 71 | | *17* / *19* |
| 72 | : Set selection background / foreground |
| 73 | |
| 74 | A reload on *SIGUSR1* re-reads the config and its theme files and re-applies the |
| 75 | palette, so editing a theme and signalling *beer* recolours a live window |
| 76 | without restarting it. |
| 77 | |
| 78 | # EXAMPLE |
| 79 | |
| 80 | A minimal dark theme in _~/.config/beer/themes/dark.toml_: |
| 81 | |
| 82 | ``` |
| 83 | [colors] |
| 84 | foreground = "#c5c8c6" |
| 85 | background = "#1d1f21" |
| 86 | cursor = "#c5c8c6" |
| 87 | regular = [ |
| 88 | "#282a2e", "#a54242", "#8c9440", "#de935f", |
| 89 | "#5f819d", "#85678f", "#5e8d87", "#707880", |
| 90 | ] |
| 91 | bright = [ |
| 92 | "#373b41", "#cc6666", "#b5bd68", "#f0c674", |
| 93 | "#81a2be", "#b294bb", "#8abeb7", "#c5c8c6", |
| 94 | ] |
| 95 | ``` |
| 96 | |
| 97 | # SEE ALSO |
| 98 | |
| 99 | _beer_(1), _beer.toml_(5) |