aboutsummaryrefslogtreecommitdiffstats
path: root/docs
diff options
context:
space:
mode:
authorMichelle Tilley <michelle@michelletilley.net>2026-02-11 12:25:52 -0800
committerGitHub <noreply@github.com>2026-02-11 12:25:52 -0800
commit05ffb902161e6d2111efe70a7bc488cfc550ff21 (patch)
tree0d0b1c7c4670236de8fea375cf619bee0d9618be /docs
parentfix(tui): enter in vim normal mode, shift-tab keybind (#3158) (diff)
downloadatuin-05ffb902161e6d2111efe70a7bc488cfc550ff21.zip
feat: expand keybinding system with vim motions, media keys, and inspector improvements (#3161)
Addresses the keybinding audit (#3157): - Add missing vim-normal bindings: 0, $, w, b, e, x, dd, D, C - Add new CursorWordEnd action for vim 'e' motion - Add VimChangeToEnd action for vim 'C' motion - Add Media key support (play, pause, stop, volume, etc.) - Refactor inspector keymap to be minimal but respect enter_accept and provide vim-style j/k navigation for vim users - Add $ to special character parsing - Replace eprintln! with tracing::warn! for config errors - Document shifted punctuation keys and media keys To be rebased once #3158 is merged
Diffstat (limited to '')
-rw-r--r--docs/docs/configuration/advanced-key-binding.md31
-rw-r--r--docs/docs/configuration/key-binding.md30
2 files changed, 52 insertions, 9 deletions
diff --git a/docs/docs/configuration/advanced-key-binding.md b/docs/docs/configuration/advanced-key-binding.md
index 9183ca8b..5027c5a2 100644
--- a/docs/docs/configuration/advanced-key-binding.md
+++ b/docs/docs/configuration/advanced-key-binding.md
@@ -69,7 +69,34 @@ An uppercase letter represents itself without needing a `shift` modifier. For ex
Some special characters are written out directly:
```
-"?", "/", "[", "]"
+"?", "/", "[", "]", "$"
+```
+
+### Shifted and punctuation keys
+
+When you press a key like `Shift+1`, your terminal sends the resulting character (`!`) rather than "shift-1". To bind shifted punctuation keys, use the character directly:
+
+```toml
+[keymap.emacs]
+"!" = "some-action" # Binds to Shift+1
+"@" = "some-action" # Binds to Shift+2
+"#" = "some-action" # Binds to Shift+3
+"$" = "cursor-end" # Binds to Shift+4 (vim $ motion)
+```
+
+Any single character can be used as a key binding.
+
+!!! note
+ The `shift` modifier is still valid for non-character keys like `"shift-tab"` or `"shift-up"`.
+
+### Media keys
+
+Media keys are supported on terminals that implement the kitty keyboard protocol with `DISAMBIGUATE_ESCAPE_CODES` enabled:
+
+```
+"play", "pause", "playpause", "stop"
+"fastforward", "rewind", "tracknext", "trackprevious"
+"record", "lowervolume", "raisevolume", "mutevolume", "mute"
```
### Multi-key sequences
@@ -127,6 +154,7 @@ Actions are specified as kebab-case strings.
| `cursor-right` | Move cursor one character right |
| `cursor-word-left` | Move cursor one word left |
| `cursor-word-right` | Move cursor one word right |
+| `cursor-word-end` | Move cursor to end of current/next word (vim `e` motion) |
| `cursor-start` | Move cursor to start of line |
| `cursor-end` | Move cursor to end of line |
@@ -191,6 +219,7 @@ The difference between `accept` and `return-selection`: `accept` runs the comman
| `vim-enter-insert-at-start` | Move to start of line and enter vim insert mode (like vim `I`) |
| `vim-enter-insert-at-end` | Move to end of line and enter vim insert mode (like vim `A`) |
| `vim-search-insert` | Clear the search input and enter vim insert mode (like vim `?` or `/`) |
+| `vim-change-to-end` | Delete to end of line and enter vim insert mode (like vim `C`) |
| `enter-prefix-mode` | Enter prefix mode (waits for one more key, e.g. `d` for delete) |
### Inspector
diff --git a/docs/docs/configuration/key-binding.md b/docs/docs/configuration/key-binding.md
index b3ae7aa2..f292999f 100644
--- a/docs/docs/configuration/key-binding.md
+++ b/docs/docs/configuration/key-binding.md
@@ -238,6 +238,15 @@ If [vim is enabled in the config](config.md#keymap_mode), the following keybindi
| j | Normal | Selects the previous item on the list |
| h | Normal | Move cursor left |
| l | Normal | Move cursor right |
+| 0 | Normal | Move cursor to start of line |
+| $ | Normal | Move cursor to end of line |
+| w | Normal | Move cursor to next word |
+| b | Normal | Move cursor to previous word |
+| e | Normal | Move cursor to end of current/next word |
+| x | Normal | Delete character under cursor |
+| dd | Normal | Clear the entire line |
+| D | Normal | Delete to end of line |
+| C | Normal | Delete to end of line and enter insert |
| i | Normal | Enters insert mode |
| I | Normal | Move to start of line and enter insert |
| a | Normal | Move right and enter insert mode |
@@ -253,17 +262,22 @@ If [vim is enabled in the config](config.md#keymap_mode), the following keybindi
| L | Normal | Jump to bottom of visible screen |
| ? or / | Normal | Clear input and enter insert mode |
| 1-9 | Normal | Select item by number |
+| enter | Normal | Execute selected item (respects enter_accept) |
| Esc | Insert | Enters normal mode |
### Inspector
Open the inspector with ctrl + o
-| Shortcut | Action |
-| -------- | --------------------------------------------- |
-| Esc | Close the inspector, returning to the shell |
-| ctrl + o | Close the inspector, returning to search view |
-| ctrl + d | Delete the inspected item from the history |
-| ↑ | Inspect the previous item in the history |
-| ↓ | Inspect the next item in the history |
-| tab | Select current item and edit |
+| Shortcut | Action |
+| --------- | --------------------------------------------- |
+| Esc | Close the inspector, returning to the shell |
+| ctrl + o | Close the inspector, returning to search view |
+| ctrl + d | Delete the inspected item from the history |
+| ↑ | Inspect the previous item in the history |
+| ↓ | Inspect the next item in the history |
+| page up | Inspect the previous item in the history |
+| page down | Inspect the next item in the history |
+| j / k | Navigate items (when vim mode is enabled) |
+| enter | Execute selected item (respects enter_accept) |
+| tab | Select current item and edit |