helix-mods/book/src/configuration.md

# Configuration

## Theme

Use a custom theme by placing a theme.toml in your config directory (i.e ~/.config/helix/theme.toml). 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/contrib/themes).

Styles in theme.toml are specified of in the form:

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

where `name` 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) |
| namespace | |
| punctuation | |
| punctuation.delimiter | |
| operator | |
| special | |
| property | |
| variable | |
| variable.parameter | |
| type | |
| type.builtin | |
| constructor | |
| function | |
| function.macro | |
| function.builtin | |
| comment | |
| variable.builtin | |
| constant | |
| constant.builtin | |
| string | |
| number | |
| escape | escaped characters |
| label | used for lifetimes |
| module | |
| ui.background | |
| ui.linenr | |
| ui.statusline | |
| ui.popup | |
| ui.window | |
| ui.help | |
| ui.text | |
| ui.text.focus | |
| ui.menu.selected | |
| 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.
Add book/ (mdbook based user guide) 2021-04-05 08:18:43 +02:00			`# Configuration`
theme: Enable style modifiers in theme.toml, add Ingrid's theme (#113) * theme: Enable style modifiers in theme.toml * docs: theme documentation * fixup: parse modifiers with filter_map * theme: tests for parse_style * theme: Log invalid cases in theme.toml parse * docs: theme documentation fixup * docs: Blaz's theming comments * docs: Theme doc fixes from pickfire Co-authored-by: Ivan Tham <pickfire@riseup.net> * theme: More context in logs, TODO for alerting users * contrib: Ingrid's theme * docs: Theme subsection fixes Co-authored-by: Ivan Tham <pickfire@riseup.net> 2021-06-06 14:45:59 +02:00
			`## Theme`

			`Use a custom theme by placing a theme.toml in your config directory (i.e ~/.config/helix/theme.toml). 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/contrib/themes).`

			`Styles in theme.toml are specified of in the form:`

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

			where `name` 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) \|`
			`\| namespace \| \|`
			`\| punctuation \| \|`
			`\| punctuation.delimiter \| \|`
			`\| operator \| \|`
			`\| special \| \|`
			`\| property \| \|`
			`\| variable \| \|`
			`\| variable.parameter \| \|`
			`\| type \| \|`
			`\| type.builtin \| \|`
			`\| constructor \| \|`
			`\| function \| \|`
			`\| function.macro \| \|`
			`\| function.builtin \| \|`
			`\| comment \| \|`
			`\| variable.builtin \| \|`
			`\| constant \| \|`
			`\| constant.builtin \| \|`
			`\| string \| \|`
			`\| number \| \|`
			`\| escape \| escaped characters \|`
			`\| label \| used for lifetimes \|`
			`\| module \| \|`
			`\| ui.background \| \|`
			`\| ui.linenr \| \|`
			`\| ui.statusline \| \|`
			`\| ui.popup \| \|`
			`\| ui.window \| \|`
			`\| ui.help \| \|`
			`\| ui.text \| \|`
			`\| ui.text.focus \| \|`
			`\| ui.menu.selected \| \|`
			`\| 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.