diff options
Diffstat (limited to 'book/src')
| -rw-r--r-- | book/src/configuration.md | 15 | ||||
| -rw-r--r-- | book/src/from-vim.md | 2 | ||||
| -rw-r--r-- | book/src/install.md | 4 | ||||
| -rw-r--r-- | book/src/keymap.md | 182 | ||||
| -rw-r--r-- | book/src/remapping.md | 2 | ||||
| -rw-r--r-- | book/src/themes.md | 189 |
6 files changed, 248 insertions, 146 deletions
diff --git a/book/src/configuration.md b/book/src/configuration.md index 00dfbbd8..60b12bfd 100644 --- a/book/src/configuration.md +++ b/book/src/configuration.md @@ -5,6 +5,21 @@ To override global configuration parameters, create a `config.toml` file located * Linux and Mac: `~/.config/helix/config.toml` * Windows: `%AppData%\helix\config.toml` +## Editor + +`[editor]` section of the config. + +| Key | Description | Default | +|--|--|---------| +| `scrolloff` | Number of lines of padding around the edge of the screen when scrolling. | `3` | +| `mouse` | Enable mouse mode. | `true` | +| `middle-click-paste` | Middle click paste support. | `true` | +| `scroll-lines` | Number of lines to scroll per scroll wheel step. | `3` | +| `shell` | Shell to use when running external commands. | Unix: `["sh", "-c"]`<br/>Windows: `["cmd", "/C"]` | +| `line-number` | Line number display (`absolute`, `relative`) | `absolute` | +| `smart-case` | Enable smart case regex searching (case insensitive unless pattern contains upper case characters) | `true` | +| `auto-pairs` | Enable automatic insertion of pairs to parenthese, brackets, etc. | `true` | + ## LSP To display all language server messages in the status line add the following to your `config.toml`: diff --git a/book/src/from-vim.md b/book/src/from-vim.md index 8e9bbac3..09f33386 100644 --- a/book/src/from-vim.md +++ b/book/src/from-vim.md @@ -7,4 +7,6 @@ going to act on (a word, a paragraph, a line, etc) is selected first and the action itself (delete, change, yank, etc) comes second. A cursor is simply a single width selection. +See also Kakoune's [Migrating from Vim](https://github.com/mawww/kakoune/wiki/Migrating-from-Vim). + > TODO: Mention texobjects, surround, registers diff --git a/book/src/install.md b/book/src/install.md index cd9c980e..b9febbcc 100644 --- a/book/src/install.md +++ b/book/src/install.md @@ -23,7 +23,9 @@ shell for working on Helix. ### Arch Linux -Binary packages are available on AUR: +Releases are available in the `community` repository. + +Packages are also available on AUR: - [helix-bin](https://aur.archlinux.org/packages/helix-bin/) contains the pre-built release - [helix-git](https://aur.archlinux.org/packages/helix-git/) builds the master branch diff --git a/book/src/keymap.md b/book/src/keymap.md index 861e46ac..78bac0cf 100644 --- a/book/src/keymap.md +++ b/book/src/keymap.md @@ -4,40 +4,40 @@ ### Movement -> NOTE: `f`, `F`, `t` and `T` are not confined to the current line. - -| Key | Description | Command | -| ----- | ----------- | ------- | -| `h`, `Left` | Move left | `move_char_left` | -| `j`, `Down` | Move down | `move_char_right` | -| `k`, `Up` | Move up | `move_line_up` | -| `l`, `Right` | Move right | `move_line_down` | -| `w` | Move next word start | `move_next_word_start` | -| `b` | Move previous word start | `move_prev_word_start` | -| `e` | Move next word end | `move_next_word_end` | -| `W` | Move next WORD start | `move_next_long_word_start` | -| `B` | Move previous WORD start | `move_prev_long_word_start` | -| `E` | Move next WORD end | `move_next_long_word_end` | -| `t` | Find 'till next char | `find_till_char` | -| `f` | Find next char | `find_next_char` | -| `T` | Find 'till previous char | `till_prev_char` | -| `F` | Find previous char | `find_prev_char` | -| `Home` | Move to the start of the line | `goto_line_start` | -| `End` | Move to the end of the line | `goto_line_end` | -| `PageUp` | Move page up | `page_up` | -| `PageDown` | Move page down | `page_down` | -| `Ctrl-u` | Move half page up | `half_page_up` | -| `Ctrl-d` | Move half page down | `half_page_down` | -| `Ctrl-i` | Jump forward on the jumplist TODO: conflicts tab | `jump_forward` | -| `Ctrl-o` | Jump backward on the jumplist | `jump_backward` | -| `v` | Enter [select (extend) mode](#select--extend-mode) | `select_mode` | -| `g` | Enter [goto mode](#goto-mode) | N/A | -| `m` | Enter [match mode](#match-mode) | N/A | -| `:` | Enter command mode | `command_mode` | -| `z` | Enter [view mode](#view-mode) | N/A | -| `Ctrl-w` | Enter [window mode](#window-mode) (maybe will be remove for spc w w later) | N/A | -| `Space` | Enter [space mode](#space-mode) | N/A | -| `K` | Show documentation for the item under the cursor | `hover` | +> NOTE: Unlike vim, `f`, `F`, `t` and `T` are not confined to the current line. + +| Key | Description | Command | +| ----- | ----------- | ------- | +| `h`, `Left` | Move left | `move_char_left` | +| `j`, `Down` | Move down | `move_char_right` | +| `k`, `Up` | Move up | `move_line_up` | +| `l`, `Right` | Move right | `move_line_down` | +| `w` | Move next word start | `move_next_word_start` | +| `b` | Move previous word start | `move_prev_word_start` | +| `e` | Move next word end | `move_next_word_end` | +| `W` | Move next WORD start | `move_next_long_word_start` | +| `B` | Move previous WORD start | `move_prev_long_word_start` | +| `E` | Move next WORD end | `move_next_long_word_end` | +| `t` | Find 'till next char | `find_till_char` | +| `f` | Find next char | `find_next_char` | +| `T` | Find 'till previous char | `till_prev_char` | +| `F` | Find previous char | `find_prev_char` | +| `Home` | Move to the start of the line | `goto_line_start` | +| `End` | Move to the end of the line | `goto_line_end` | +| `PageUp` | Move page up | `page_up` | +| `PageDown` | Move page down | `page_down` | +| `Ctrl-u` | Move half page up | `half_page_up` | +| `Ctrl-d` | Move half page down | `half_page_down` | +| `Ctrl-i` | Jump forward on the jumplist | `jump_forward` | +| `Ctrl-o` | Jump backward on the jumplist | `jump_backward` | +| `v` | Enter [select (extend) mode](#select--extend-mode) | `select_mode` | +| `g` | Enter [goto mode](#goto-mode) | N/A | +| `m` | Enter [match mode](#match-mode) | N/A | +| `:` | Enter command mode | `command_mode` | +| `z` | Enter [view mode](#view-mode) | N/A | +| `Z` | Enter sticky [view mode](#view-mode) | N/A | +| `Ctrl-w` | Enter [window mode](#window-mode) | N/A | +| `Space` | Enter [space mode](#space-mode) | N/A | ### Changes @@ -66,6 +66,16 @@ | `d` | Delete selection | `delete_selection` | | `c` | Change selection (delete and enter insert mode) | `change_selection` | +#### Shell + +| Key | Description | Command | +| ------ | ----------- | ------- | +| <code>|</code> | Pipe each selection through shell command, replacing with output | `shell_pipe` | +| <code>A-|</code> | Pipe each selection into shell command, ignoring output | `shell_pipe_to` | +| `!` | Run shell command, inserting output before each selection | `shell_insert_output` | +| `A-!` | Run shell command, appending output after each selection | `shell_append_output` | + + ### Selection manipulation | Key | Description | Command | @@ -75,6 +85,7 @@ | `Alt-s` | Split selection on newlines | `split_selection_on_newline` | | `;` | Collapse selection onto a single cursor | `collapse_selection` | | `Alt-;` | Flip selection cursor and anchor | `flip_selections` | +| `,` | Keep only the primary selection | `keep_primary_selection` | | `C` | Copy selection onto the next line | `copy_selection_on_next_line` | | `Alt-C` | Copy selection onto the previous line | `copy_selection_on_prev_line` | | `(` | Rotate main selection forward | `rotate_selections_backward` | @@ -86,22 +97,13 @@ | `X` | Extend selection to line bounds (line-wise selection) | `extend_to_line_bounds` | | | Expand selection to parent syntax node TODO: pick a key | `expand_selection` | | `J` | Join lines inside selection | `join_selections` | -| `K` | Keep selections matching the regex TODO: overlapped by hover help | `keep_selections` | -| `Space` | Keep only the primary selection TODO: overlapped by space mode | `keep_primary_selection` | +| `K` | Keep selections matching the regex | `keep_selections` | +| `$` | Pipe each selection into shell command, keep selections where command returned 0 | `shell_keep_pipe` | | `Ctrl-c` | Comment/uncomment the selections | `toggle_comments` | -### Insert Mode - -| Key | Description | Command | -| ----- | ----------- | ------- | -| `Escape` | Switch to normal mode | `normal_mode` | -| `Ctrl-x` | Autocomplete | `completion` | -| `Ctrl-w` | Delete previous word | `delete_word_backward` | - ### Search -> TODO: The search implementation isn't ideal yet -- we don't support searching -in reverse, or searching via smartcase. +> TODO: The search implementation isn't ideal yet -- we don't support searching in reverse. | Key | Description | Command | | ----- | ----------- | ------- | @@ -110,41 +112,17 @@ in reverse, or searching via smartcase. | `N` | Add next search match to selection | `extend_search_next` | | `*` | Use current selection as the search pattern | `search_selection` | -### Unimpaired - -Mappings in the style of [vim-unimpaired](https://github.com/tpope/vim-unimpaired) - -| Key | Description | Command | -| ----- | ----------- | ------- | -| `[d` | Go to previous diagnostic | `goto_prev_diag` | -| `]d` | Go to next diagnostic | `goto_next_diag` | -| `[D` | Go to first diagnostic in document | `goto_first_diag` | -| `]D` | Go to last diagnostic in document | `goto_last_diag` | -| `[space` | Add newline above | `add_newline_above` | -| `]space` | Add newline below | `add_newline_below` | - -### Shell +### Minor modes -| Key | Description | Command | -| ------ | ----------- | ------- | -| `\|` | Pipe each selection through shell command, replacing with output | `shell_pipe` | -| `A-\|` | Pipe each selection into shell command, ignoring output | `shell_pipe_to` | -| `!` | Run shell command, inserting output before each selection | `shell_insert_output` | -| `A-!` | Run shell command, appending output after each selection | `shell_append_output` | -| `$` | Pipe each selection into shell command, keep selections where command returned 0 | `shell_keep_pipe` | - -## Select / extend mode - -I'm still pondering whether to keep this mode or not. It changes movement -commands to extend the existing selection instead of replacing it. - -> NOTE: It's a bit confusing at the moment because extend hasn't been -> implemented for all movement commands yet. +These sub-modes are accessible from normal mode and typically switch back to normal mode after a command. -## View mode +#### View mode View mode is intended for scrolling and manipulating the view without changing -the selection. +the selection. The "sticky" variant of this mode is persistent; use the Escape +key to return to normal mode after usage (useful when you're simply looking +over text and not actively editing it). + | Key | Description | Command | | ----- | ----------- | ------- | @@ -154,8 +132,12 @@ the selection. | `m` | Align the line to the middle of the screen (horizontally) | `align_view_middle` | | `j` | Scroll the view downwards | `scroll_down` | | `k` | Scroll the view upwards | `scroll_up` | +| `f` | Move page down | `page_down` | +| `b` | Move page up | `page_up` | +| `d` | Move half page down | `half_page_down` | +| `u` | Move half page up | `half_page_up` | -## Goto mode +#### Goto mode Jumps to various locations. @@ -177,7 +159,7 @@ Jumps to various locations. | `i` | Go to implementation | `goto_implementation` | | `a` | Go to the last accessed/alternate file | `goto_last_accessed_file` | -## Match mode +#### Match mode Enter this mode using `m` from normal mode. See the relavant section in [Usage](./usage.md) for an explanation about [surround](./usage.md#surround) @@ -192,11 +174,9 @@ and [textobject](./usage.md#textobject) usage. | `a` `<object>` | Select around textobject | `select_textobject_around` | | `i` `<object>` | Select inside textobject | `select_textobject_inner` | -## Object mode - TODO: Mappings for selecting syntax nodes (a superset of `[`). -## Window mode +#### Window mode This layer is similar to vim keybindings as kakoune does not support window. @@ -207,24 +187,56 @@ This layer is similar to vim keybindings as kakoune does not support window. | `h`, `Ctrl-h` | Horizontal bottom split | `hsplit` | | `q`, `Ctrl-q` | Close current window | `wclose` | -## Space mode +#### Space mode -This layer is a kludge of mappings I had under leader key in neovim. +This layer is a kludge of mappings, mostly pickers. | Key | Description | Command | | ----- | ----------- | ------- | +| `k` | Show documentation for the item under the cursor | `hover` | | `f` | Open file picker | `file_picker` | | `b` | Open buffer picker | `buffer_picker` | | `s` | Open symbol picker (current document) | `symbol_picker` | | `a` | Apply code action | `code_action` | | `'` | Open last fuzzy picker | `last_picker` | | `w` | Enter [window mode](#window-mode) | N/A | -| `space` | Keep primary selection TODO: it's here because space mode replaced it | `keep_primary_selection` | | `p` | Paste system clipboard after selections | `paste_clipboard_after` | | `P` | Paste system clipboard before selections | `paste_clipboard_before` | | `y` | Join and yank selections to clipboard | `yank_joined_to_clipboard` | | `Y` | Yank main selection to clipboard | `yank_main_selection_to_clipboard` | | `R` | Replace selections by clipboard contents | `replace_selections_with_clipboard` | +| `/` | Global search in workspace folder | `global_search` | + +> NOTE: Global search display results in a fuzzy picker, use `space + '` to bring it back up after opening a file. + +#### Unimpaired + +Mappings in the style of [vim-unimpaired](https://github.com/tpope/vim-unimpaired). + +| Key | Description | Command | +| ----- | ----------- | ------- | +| `[d` | Go to previous diagnostic | `goto_prev_diag` | +| `]d` | Go to next diagnostic | `goto_next_diag` | +| `[D` | Go to first diagnostic in document | `goto_first_diag` | +| `]D` | Go to last diagnostic in document | `goto_last_diag` | +| `[space` | Add newline above | `add_newline_above` | +| `]space` | Add newline below | `add_newline_below` | + +## Insert Mode + +| Key | Description | Command | +| ----- | ----------- | ------- | +| `Escape` | Switch to normal mode | `normal_mode` | +| `Ctrl-x` | Autocomplete | `completion` | +| `Ctrl-w` | Delete previous word | `delete_word_backward` | + +## Select / extend mode + +I'm still pondering whether to keep this mode or not. It changes movement +commands (including goto) to extend the existing selection instead of replacing it. + +> NOTE: It's a bit confusing at the moment because extend hasn't been +> implemented for all movement commands yet. # Picker diff --git a/book/src/remapping.md b/book/src/remapping.md index 3f25e364..81f45da3 100644 --- a/book/src/remapping.md +++ b/book/src/remapping.md @@ -49,4 +49,6 @@ Control, Shift and Alt modifiers are encoded respectively with the prefixes | Null | `"null"` | | Escape | `"esc"` | +Keys can be disabled by binding them to the `no_op` command. + Commands can be found in the source code at [`helix-term/src/commands.rs`](https://github.com/helix-editor/helix/blob/master/helix-term/src/commands.rs) diff --git a/book/src/themes.md b/book/src/themes.md index 0a4d58ad..a99e3a59 100644 --- a/book/src/themes.md +++ b/book/src/themes.md @@ -30,7 +30,52 @@ if the key contains a dot `'.'`, it must be quoted to prevent it being parsed as "key.key" = "#ffffff" ``` -Possible modifiers: +### Color palettes + +It's recommended define a palette of named colors, and refer to them from the +configuration values in your theme. To do this, add a table called +`palette` to your theme file: + +```toml +ui.background = "white" +ui.text = "black" + +[palette] +white = "#ffffff" +black = "#000000" +``` + +Remember that the `[palette]` table includes all keys after its header, +so you should define the palette after normal theme options. + +The default palette uses the terminal's default 16 colors, and the colors names +are listed below. The `[palette]` section in the config file takes precedence +over it and is merged into the default palette. + +| Color Name | +| --- | +| `black` | +| `red` | +| `green` | +| `yellow` | +| `blue` | +| `magenta` | +| `cyan` | +| `gray` | +| `light-red` | +| `light-green` | +| `light-yellow` | +| `light-blue` | +| `light-magenta` | +| `light-cyan` | +| `light-gray` | +| `white` | + +### Modifiers + +The following values may be used as modifiers. + +Less common modifiers might not be supported by your terminal emulator. | Modifier | | --- | @@ -38,44 +83,88 @@ Possible modifiers: | `dim` | | `italic` | | `underlined` | -| `slow\_blink` | -| `rapid\_blink` | +| `slow_blink` | +| `rapid_blink` | | `reversed` | | `hidden` | -| `crossed\_out` | +| `crossed_out` | + +### Scopes + +The following is a list of scopes available to use for styling. + +#### Syntax highlighting + +These keys match [tree-sitter scopes](https://tree-sitter.github.io/tree-sitter/syntax-highlighting#theme). + +For a given highlight produced, styling will be determined based on the longest matching theme key. For example, the highlight `function.builtin.static` would match the key `function.builtin` rather than `function`. + +We use a similar set of scopes as +[SublimeText](https://www.sublimetext.com/docs/scope_naming.html). See also +[TextMate](https://macromates.com/manual/en/language_grammars) scopes. + +- `escape` (TODO: rename to (constant).character.escape) + +- `type` - Types + - `builtin` - Primitive types provided by the language (`int`, `usize`) + +- `constant` (TODO: constant.other.placeholder for %v) + - `builtin` Special constants provided by the language (`true`, `false`, `nil` etc) + - `boolean` + - `character` + +- `number` (TODO: rename to constant.number/.numeric.{integer, float, complex}) +- `string` (TODO: string.quoted.{single, double}, string.raw/.unquoted)? + - `regexp` - Regular expressions + - `special` + - `path` + - `url` + +- `comment` - Code comments + - `line` - Single line comments (`//`) + - `block` - Block comments (e.g. (`/* */`) + - `documentation` - Documentation comments (e.g. `///` in Rust) + +- `variable` - Variables + - `builtin` - Reserved language variables (`self`, `this`, `super`, etc) + - `parameter` - Function parameters + - `property` + - `function` (TODO: ?) + +- `label` + +- `punctuation` + - `delimiter` - Commas, colons + - `bracket` - Parentheses, angle brackets, etc. + +- `keyword` + - `control` + - `conditional` - `if`, `else` + - `repeat` - `for`, `while`, `loop` + - `import` - `import`, `export` + - (TODO: return?) + - `directive` - Preprocessor directives (`#if` in C) + - `function` - `fn`, `func` + +- `operator` - `||`, `+=`, `>`, `or` + +- `function` + - `builtin` + - `method` + - `macro` + - `special` (preprocesor in C) + +- `tag` - Tags (e.g. `<body>` in HTML) + +- `namespace` + +#### Interface + +These scopes are used for theming the editor interface. -Possible keys: | Key | Notes | | --- | --- | -| `attribute` | | -| `keyword` | | -| `keyword.directive` | Preprocessor directives (\#if in C) | -| `keyword.control` | Control flow | -| `namespace` | | -| `punctuation` | | -| `punctuation.delimiter` | | -| `operator` | | -| `special` | | -| `property` | | -| `variable` | | -| `variable.parameter` | | -| `type` | | -| `type.builtin` | | -| `type.enum.variant` | Enum variants | -| `constructor` | | -| `function` | | -| `function.macro` | | -| `function.builtin` | | -| `comment` | | -| `variable.builtin` | | -| `constant` | | -| `constant.builtin` | | -| `string` | | -| `number` | | -| `escape` | Escaped characters | -| `label` | For lifetimes | -| `module` | | | `ui.background` | | | `ui.cursor` | | | `ui.cursor.insert` | | @@ -84,8 +173,8 @@ Possible keys: | `ui.cursor.primary` | Cursor with primary selection | | `ui.linenr` | | | `ui.linenr.selected` | | -| `ui.statusline` | | -| `ui.statusline.inactive` | | +| `ui.statusline` | Statusline | +| `ui.statusline.inactive` | Statusline (unfocused document) | | `ui.popup` | | | `ui.window` | | | `ui.help` | | @@ -97,29 +186,9 @@ Possible keys: | `ui.menu.selected` | | | `ui.selection` | For selections in the editing area | | `ui.selection.primary` | | -| `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. +| `warning` | Diagnostics warning (gutter) | +| `error` | Diagnostics error (gutter) | +| `info` | Diagnostics info (gutter) | +| `hint` | Diagnostics hint (gutter) | +| `diagnostic` | For text in editing area | -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. - -## Color palettes - -You can define a palette of named colors, and refer to them from the -configuration values in your theme. To do this, add a table called -`palette` to your theme file: - -```toml -ui.background = "white" -ui.text = "black" - -[palette] -white = "#ffffff" -black = "#000000" -``` - -Remember that the `[palette]` table includes all keys after its header, -so you should define the palette after normal theme options. |