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>

1 files changed, 86 insertions, 0 deletions

diff --git a/book/src/configuration.md b/book/src/configuration.md
index a025a48b..4528080b 100644
--- a/book/src/configuration.md
+++ b/book/src/configuration.md
@@ -1 +1,87 @@
 # 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.