diff options
| -rw-r--r-- | book/src/SUMMARY.md | 1 | ||||
| -rw-r--r-- | book/src/configuration.md | 91 | ||||
| -rw-r--r-- | book/src/themes.md | 94 |
3 files changed, 97 insertions, 89 deletions
diff --git a/book/src/SUMMARY.md b/book/src/SUMMARY.md index 3ea1fb9a..5dea3112 100644 --- a/book/src/SUMMARY.md +++ b/book/src/SUMMARY.md @@ -3,6 +3,7 @@ - [Installation](./install.md) - [Usage](./usage.md) - [Configuration](./configuration.md) + - [Themes](./themes.md) - [Keymap](./keymap.md) - [Key Remapping](./remapping.md) - [Hooks](./hooks.md) diff --git a/book/src/configuration.md b/book/src/configuration.md index 51a08e03..087d3fbb 100644 --- a/book/src/configuration.md +++ b/book/src/configuration.md @@ -1,97 +1,10 @@ # Configuration +To override global configuration parameters create a `config.toml` file located in your config directory (i.e `~/.config/helix/config.toml`). + ## LSP To disable language server progress report from being displayed in the status bar add this option to your `config.toml`: ```toml lsp-progress = false ``` - -## 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` | For lifetimes | -| `module` | | -| `ui.background` | | -| `ui.linenr` | | -| `ui.linenr.selected` | For lines with cursors | -| `ui.statusline` | | -| `ui.popup` | | -| `ui.window` | | -| `ui.help` | | -| `ui.text` | | -| `ui.text.focus` | | -| `ui.menu.selected` | | -| `ui.selection` | For selections in the editing area | -| `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. - diff --git a/book/src/themes.md b/book/src/themes.md new file mode 100644 index 00000000..5c1b5842 --- /dev/null +++ b/book/src/themes.md @@ -0,0 +1,94 @@ +# 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/contrib/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) | +| `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` | For lifetimes | +| `module` | | +| `ui.background` | | +| `ui.linenr` | | +| `ui.statusline` | | +| `ui.popup` | | +| `ui.window` | | +| `ui.help` | | +| `ui.text` | | +| `ui.text.focus` | | +| `ui.menu.selected` | | +| `ui.selection` | For selections in the editing area | +| `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. |