From 2f6a113fbea528845283161fac6ce697cb4b6996 Mon Sep 17 00:00:00 2001 From: Thomas Aarholt Date: Wed, 20 Nov 2024 23:35:06 +0100 Subject: [PATCH] Docs Key-Remapping: Move Commands to top as introduction (#11953) --- book/src/remapping.md | 42 ++++++++++++++++++++++-------------------- 1 file changed, 22 insertions(+), 20 deletions(-) diff --git a/book/src/remapping.md b/book/src/remapping.md index ea63f292c..41e20f84b 100644 --- a/book/src/remapping.md +++ b/book/src/remapping.md @@ -4,10 +4,31 @@ Helix currently supports one-way key remapping through a simple TOML configurati file. (More powerful solutions such as rebinding via commands will be available in the future). +There are three kinds of commands that can be used in keymaps: + +* Static commands: commands like `move_char_right` which are usually bound to + keys and used for movement and editing. A list of static commands is + available in the [Keymap](./keymap.html) documentation and in the source code + in [`helix-term/src/commands.rs`](https://github.com/helix-editor/helix/blob/master/helix-term/src/commands.rs) + at the invocation of `static_commands!` macro. +* Typable commands: commands that can be executed from command mode (`:`), for + example `:write!`. See the [Commands](./commands.html) documentation for a + list of available typeable commands or the `TypableCommandList` declaration in + the source code at [`helix-term/src/commands/typed.rs`](https://github.com/helix-editor/helix/blob/master/helix-term/src/commands/typed.rs). +* Macros: sequences of keys that are executed in order. These keybindings + start with `@` and then list any number of keys to be executed. For example + `@miw` can be used to select the surrounding word. For now, macro keybindings + are not allowed in keybinding sequences due to limitations in the way that + command sequences are executed. Modifier keys (e.g. Alt+o) can be used + like `""`, e.g. `"@miw"` + To remap keys, create a `config.toml` file in your `helix` configuration directory (default `~/.config/helix` on Linux systems) with a structure like this: +> 💡 To set a modifier + key as a keymap, type `A-X = ...` or `C-X = ...` for Alt + X or Ctrl + X. Combine with Shift using a dash, e.g. `C-S-esc`. +> Within macros, wrap them in `<>`, e.g. `` and `` to distinguish from the `A` or `C` keys. + ```toml # At most one section each of 'keys.normal', 'keys.insert' and 'keys.select' [keys.normal] @@ -18,6 +39,7 @@ w = "move_line_up" # Maps the 'w' key move_line_up "C-S-esc" = "extend_line" # Maps Ctrl-Shift-Escape to extend_line g = { a = "code_action" } # Maps `ga` to show possible code actions "ret" = ["open_below", "normal_mode"] # Maps the enter key to open_below then re-enter normal mode +"A-x" = "@x" # Maps Alt-x to a macro selecting the whole line and deleting it without yanking it [keys.insert] "A-x" = "normal_mode" # Maps Alt-X to enter normal mode @@ -74,23 +96,3 @@ Ctrl, Shift and Alt modifiers are encoded respectively with the prefixes | Escape | `"esc"` | Keys can be disabled by binding them to the `no_op` command. - -## Commands - -There are three kinds of commands that can be used in keymaps: - -* Static commands: commands like `move_char_right` which are usually bound to - keys and used for movement and editing. A list of static commands is - available in the [Keymap](./keymap.html) documentation and in the source code - in [`helix-term/src/commands.rs`](https://github.com/helix-editor/helix/blob/master/helix-term/src/commands.rs) - at the invocation of `static_commands!` macro. -* Typable commands: commands that can be executed from command mode (`:`), for - example `:write!`. See the [Commands](./commands.html) documentation for a - list of available typeable commands or the `TypableCommandList` declaration in - the source code at [`helix-term/src/commands/typed.rs`](https://github.com/helix-editor/helix/blob/master/helix-term/src/commands/typed.rs). -* Macros: sequences of keys that are executed in order. These keybindings - start with `@` and then list any number of keys to be executed. For example - `@miw` can be used to select the surrounding word. For now, macro keybindings - are not allowed in keybinding sequences due to limitations in the way that - command sequences are executed. Modifier keys (e.g. Alt+o) can be used - like `""`, e.g. `"@miw"`