git.iko.soy/helix
on master help sign in
Update docs
commitcd0ecded1fdec11a16148bf5c8a2d8d9702e759c authorwojciechkepka <wojtek.kepka@protonmail.com> dateSat 19 Jun 2021, 13:19 (5 years ago) parent10f9f72
3 files changed+97−89
compare with master
unifiedsplit
book/src/SUMMARY.md+1 book/src/configuration.md+2−89 book/src/themes.md+94
book/src/SUMMARY.md+1
@@ -3,6 +3,7 @@
33- [Installation](./install.md)
44- [Usage](./usage.md)
55- [Configuration](./configuration.md)
6+ - [Themes](./themes.md)
67 - [Keymap](./keymap.md)
78 - [Key Remapping](./remapping.md)
89 - [Hooks](./hooks.md)
book/src/configuration.md+2−89
@@ -1,97 +1,10 @@
11# Configuration
22
3+To override global configuration parameters create a `config.toml` file located in your config directory (i.e `~/.config/helix/config.toml`).
4+
35## LSP
46
57To disable language server progress report from being displayed in the status bar add this option to your `config.toml`:
68```toml
79lsp-progress = false
810```
9−
10−## Theme
11−
12−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).
13−
14−Styles in theme.toml are specified of in the form:
15−
16−```toml
17−key = { fg = "#ffffff", bg = "#000000", modifiers = ["bold", "italic"] }
18−```
19−
20−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.
21−
22−To specify only the foreground color:
23−
24−```toml
25−key = "#ffffff"
26−```
27−
28−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).
29−
30−```toml
31−"key.key" = "#ffffff"
32−```
33−
34−Possible modifiers:
35−
36−| Modifier |
37−| --- |
38−| `bold` |
39−| `dim` |
40−| `italic` |
41−| `underlined` |
42−| `slow_blink` |
43−| `rapid_blink` |
44−| `reversed` |
45−| `hidden` |
46−| `crossed_out` |
47−
48−Possible keys:
49−
50−| Key | Notes |
51−| --- | --- |
52−| `attribute` | |
53−| `keyword` | |
54−| `keyword.directive` | Preprocessor directives (\#if in C) |
55−| `namespace` | |
56−| `punctuation` | |
57−| `punctuation.delimiter` | |
58−| `operator` | |
59−| `special` | |
60−| `property` | |
61−| `variable` | |
62−| `variable.parameter` | |
63−| `type` | |
64−| `type.builtin` | |
65−| `constructor` | |
66−| `function` | |
67−| `function.macro` | |
68−| `function.builtin` | |
69−| `comment` | |
70−| `variable.builtin` | |
71−| `constant` | |
72−| `constant.builtin` | |
73−| `string` | |
74−| `number` | |
75−| `escape` | Escaped characters |
76−| `label` | For lifetimes |
77−| `module` | |
78−| `ui.background` | |
79−| `ui.linenr` | |
80−| `ui.linenr.selected` | For lines with cursors |
81−| `ui.statusline` | |
82−| `ui.popup` | |
83−| `ui.window` | |
84−| `ui.help` | |
85−| `ui.text` | |
86−| `ui.text.focus` | |
87−| `ui.menu.selected` | |
88−| `ui.selection` | For selections in the editing area |
89−| `warning` | LSP warning |
90−| `error` | LSP error |
91−| `info` | LSP info |
92−| `hint` | LSP hint |
93−
94−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.
95−
96−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.
97−
book/src/themes.mdnew file+94
@@ -0,0 +1,94 @@
1+# Themes
2+
3+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.
4+
5+To use a custom theme add `theme = <name>` to your [`config.toml`](./configuration.md) or override it during runtime using `:theme <name>`.
6+
7+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).
8+
9+## Creating a theme
10+
11+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`).
12+
13+Each line in the theme file is specified as below:
14+
15+```toml
16+key = { fg = "#ffffff", bg = "#000000", modifiers = ["bold", "italic"] }
17+```
18+
19+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.
20+
21+To specify only the foreground color:
22+
23+```toml
24+key = "#ffffff"
25+```
26+
27+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).
28+
29+```toml
30+"key.key" = "#ffffff"
31+```
32+
33+Possible modifiers:
34+
35+| Modifier |
36+| --- |
37+| `bold` |
38+| `dim` |
39+| `italic` |
40+| `underlined` |
41+| `slow\_blink` |
42+| `rapid\_blink` |
43+| `reversed` |
44+| `hidden` |
45+| `crossed\_out` |
46+
47+Possible keys:
48+
49+| Key | Notes |
50+| --- | --- |
51+| `attribute` | |
52+| `keyword` | |
53+| `keyword.directive` | Preprocessor directives (\#if in C) |
54+| `namespace` | |
55+| `punctuation` | |
56+| `punctuation.delimiter` | |
57+| `operator` | |
58+| `special` | |
59+| `property` | |
60+| `variable` | |
61+| `variable.parameter` | |
62+| `type` | |
63+| `type.builtin` | |
64+| `constructor` | |
65+| `function` | |
66+| `function.macro` | |
67+| `function.builtin` | |
68+| `comment` | |
69+| `variable.builtin` | |
70+| `constant` | |
71+| `constant.builtin` | |
72+| `string` | |
73+| `number` | |
74+| `escape` | Escaped characters |
75+| `label` | For lifetimes |
76+| `module` | |
77+| `ui.background` | |
78+| `ui.linenr` | |
79+| `ui.statusline` | |
80+| `ui.popup` | |
81+| `ui.window` | |
82+| `ui.help` | |
83+| `ui.text` | |
84+| `ui.text.focus` | |
85+| `ui.menu.selected` | |
86+| `ui.selection` | For selections in the editing area |
87+| `warning` | LSP warning |
88+| `error` | LSP error |
89+| `info` | LSP info |
90+| `hint` | LSP hint |
91+
92+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.
93+
94+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.