Update docs

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.