aboutsummaryrefslogtreecommitdiff
path: root/book/src/themes.md
blob: 0a4d58ad536f4235e656b2dc3a9c13e289788c21 (plain) (blame)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
# Themes

First you'll need to place selected themes in your `themes` directory (i.e `~/.config/helix/themes`), the directory might have to be created beforehand.

To use a custom theme add `theme = <name>` to your [`config.toml`](./configuration.md) or override it during runtime using `:theme <name>`.

The default theme.toml can be found [here](https://github.com/helix-editor/helix/blob/master/theme.toml), and user submitted themes [here](https://github.com/helix-editor/helix/blob/master/runtime/themes). 

## Creating a theme

First create a file with the name of your theme as file name (i.e `mytheme.toml`) and place it in your `themes` directory (i.e `~/.config/helix/themes`).

Each line in the theme file is specified as below:

```toml
key = { fg = "#ffffff", bg = "#000000", modifiers = ["bold", "italic"] }
```

where `key` represents what you want to style, `fg` specifies the foreground color, `bg` the background color, and `modifiers` is a list of style modifiers. `bg` and `modifiers` can be omitted to defer to the defaults.

To specify only the foreground color:

```toml
key = "#ffffff"
```

if the key contains a dot `'.'`, it must be quoted to prevent it being parsed as a [dotted key](https://toml.io/en/v1.0.0#keys).

```toml
"key.key" = "#ffffff"
```

Possible modifiers:

| Modifier       |
| ---            |
| `bold`         |
| `dim`          |
| `italic`       |
| `underlined`   |
| `slow\_blink`  |
| `rapid\_blink` |
| `reversed`     |
| `hidden`       |
| `crossed\_out` |

Possible keys:

| Key                      | Notes                               |
| ---                      | ---                                 |
| `attribute`              |                                     |
| `keyword`                |                                     |
| `keyword.directive`      | Preprocessor directives (\#if in C) |
| `keyword.control`        | Control flow                        |
| `namespace`              |                                     |
| `punctuation`            |                                     |
| `punctuation.delimiter`  |                                     |
| `operator`               |                                     |
| `special`                |                                     |
| `property`               |                                     |
| `variable`               |                                     |
| `variable.parameter`     |                                     |
| `type`                   |                                     |
| `type.builtin`           |                                     |
| `type.enum.variant`      | Enum variants                       |
| `constructor`            |                                     |
| `function`               |                                     |
| `function.macro`         |                                     |
| `function.builtin`       |                                     |
| `comment`                |                                     |
| `variable.builtin`       |                                     |
| `constant`               |                                     |
| `constant.builtin`       |                                     |
| `string`                 |                                     |
| `number`                 |                                     |
| `escape`                 | Escaped characters                  |
| `label`                  | For lifetimes                       |
| `module`                 |                                     |
| `ui.background`          |                                     |
| `ui.cursor`              |                                     |
| `ui.cursor.insert`       |                                     |
| `ui.cursor.select`       |                                     |
| `ui.cursor.match`        | Matching bracket etc.               |
| `ui.cursor.primary`      | Cursor with primary selection       |
| `ui.linenr`              |                                     |
| `ui.linenr.selected`     |                                     |
| `ui.statusline`          |                                     |
| `ui.statusline.inactive` |                                     |
| `ui.popup`               |                                     |
| `ui.window`              |                                     |
| `ui.help`                |                                     |
| `ui.text`                |                                     |
| `ui.text.focus`          |                                     |
| `ui.info`                |                                     |
| `ui.info.text`           |                                     |
| `ui.menu`                |                                     |
| `ui.menu.selected`       |                                     |
| `ui.selection`           | For selections in the editing area  |
| `ui.selection.primary`   |                                     |
| `warning`                | LSP warning                         |
| `error`                  | LSP error                           |
| `info`                   | LSP info                            |
| `hint`                   | LSP hint                            |

These keys match [tree-sitter scopes](https://tree-sitter.github.io/tree-sitter/syntax-highlighting#theme). We half-follow the common scopes from [macromates language grammars](https://macromates.com/manual/en/language_grammars) with some differences.

For a given highlight produced, styling will be determined based on the longest matching theme key. So it's enough to provide function to highlight `function.macro` and `function.builtin` as well, but you can use more specific scopes to highlight specific cases differently.

## Color palettes

You can define a palette of named colors, and refer to them from the
configuration values in your theme. To do this, add a table called
`palette` to your theme file:

```toml
ui.background = "white"
ui.text = "black"

[palette]
white = "#ffffff"
black = "#000000"
```

Remember that the `[palette]` table includes all keys after its header,
so you should define the palette after normal theme options.