mirror of
https://github.com/kovidgoyal/kitty
synced 2026-07-08 21:25:32 +02:00
Command palette: word-level search with multi-token cross-column matching
Implement a word-level scoring engine for the command palette that replaces the previous FZF-based approach. Query tokens are matched against pre-tokenized words in each column (key, action, category) with exact, prefix, and edit-distance scoring. Multiple search terms are supported with cross-column matching — items matching more tokens rank higher. Compound query tokens containing delimiters (e.g. mouse_selection) are matched as units. Add comprehensive tests using a Go builder API instead of raw JSON blobs, covering single-token, multi-token, partial-match, ranking, mouse binding, and unmapped action scenarios. Add documentation for the command palette kitten.
This commit is contained in:
114
docs/kittens/command-palette.rst
Normal file
114
docs/kittens/command-palette.rst
Normal file
@@ -0,0 +1,114 @@
|
||||
Command palette
|
||||
=================
|
||||
|
||||
.. only:: man
|
||||
|
||||
Overview
|
||||
--------------
|
||||
|
||||
|
||||
The command palette lets you browse, search and trigger all keyboard shortcuts
|
||||
and actions in |kitty| from a single searchable overlay. Press
|
||||
:sc:`command_palette` to open it (default: :kbd:`Ctrl+Shift+F3`).
|
||||
|
||||
.. figure:: ../screenshots/command-palette.png
|
||||
:alt: A screenshot of the command palette kitten
|
||||
:align: center
|
||||
:width: 100%
|
||||
|
||||
The command palette showing search results for "window close"
|
||||
|
||||
All mapped actions (those with a keyboard shortcut) and unmapped actions (those
|
||||
available but not bound to any key) are listed, organized by category. Mouse
|
||||
bindings are shown in a separate section. Simply type to search, select a
|
||||
result, and press :kbd:`Enter` to run it.
|
||||
|
||||
|
||||
Searching
|
||||
-----------
|
||||
|
||||
As you type into the search bar, the palette filters results in real time using
|
||||
word-level matching across three columns: key, action, and category.
|
||||
|
||||
Multiple search terms are supported. Typing ``scroll page`` matches items that
|
||||
contain both "scroll" and "page" in any column. Items matching more of your
|
||||
search terms rank higher than those matching fewer.
|
||||
|
||||
The search also handles compound tokens that contain delimiters such as
|
||||
underscores or slashes. For example, typing ``mouse_selection`` matches the
|
||||
full compound name as a unit. Typo tolerance is built in for words of four
|
||||
characters or longer.
|
||||
|
||||
Matched characters are highlighted in the results so you can see exactly where
|
||||
each term matched.
|
||||
|
||||
|
||||
Keyboard controls
|
||||
-------------------
|
||||
|
||||
The following keys are available while the command palette is open:
|
||||
|
||||
.. list-table::
|
||||
:widths: auto
|
||||
:header-rows: 1
|
||||
|
||||
* - Key
|
||||
- Action
|
||||
* - Any text
|
||||
- Filter results by typing a search query
|
||||
* - :kbd:`Enter`
|
||||
- Run the selected action
|
||||
* - :kbd:`Escape`
|
||||
- Clear the search query, or close the palette if the query is already empty
|
||||
* - :kbd:`Up` / :kbd:`Ctrl+K` / :kbd:`Ctrl+P`
|
||||
- Move selection up
|
||||
* - :kbd:`Down` / :kbd:`Ctrl+J` / :kbd:`Ctrl+N`
|
||||
- Move selection down
|
||||
* - :kbd:`Page Up`
|
||||
- Move selection up by a page
|
||||
* - :kbd:`Page Down`
|
||||
- Move selection down by a page
|
||||
* - :kbd:`Home`
|
||||
- Jump to the first result
|
||||
* - :kbd:`End`
|
||||
- Jump to the last result
|
||||
* - :kbd:`Backspace`
|
||||
- Delete the last character from the query
|
||||
* - :kbd:`F12`
|
||||
- Toggle display of unmapped actions
|
||||
* - Mouse click
|
||||
- Select and run the clicked action
|
||||
|
||||
|
||||
Unmapped actions
|
||||
------------------
|
||||
|
||||
By default, the palette shows both mapped actions (those bound to a shortcut)
|
||||
and unmapped actions (those with no shortcut assigned). Unmapped actions appear
|
||||
with an ``(unmapped)`` label in the key column. Press :kbd:`F12` to toggle
|
||||
their visibility. This preference is remembered across sessions.
|
||||
|
||||
Unmapped actions are useful for discovering functionality that you may not have
|
||||
configured a shortcut for. You can run them directly from the palette, or note
|
||||
the action name and add a mapping in :file:`kitty.conf`.
|
||||
|
||||
|
||||
Custom keyboard modes
|
||||
-----------------------
|
||||
|
||||
If you have defined custom :ref:`keyboard modes <modal_mappings>` in your
|
||||
configuration, their bindings appear under separate mode headers in the palette.
|
||||
The ``push_keyboard_mode`` bindings are grouped with the target mode they
|
||||
activate, making it easy to see how to enter each mode alongside its shortcuts.
|
||||
|
||||
|
||||
Configuration
|
||||
--------------
|
||||
|
||||
The default mapping to open the command palette is::
|
||||
|
||||
map kitty_mod+f3 command_palette
|
||||
|
||||
You can change this in :file:`kitty.conf` like any other mapping. For example::
|
||||
|
||||
map ctrl+p command_palette
|
||||
@@ -13,6 +13,7 @@ Extend with kittens
|
||||
kittens/themes
|
||||
kittens/choose-fonts
|
||||
kittens/hints
|
||||
kittens/command-palette
|
||||
kittens/quick-access-terminal
|
||||
kittens/choose-files
|
||||
kittens/panel
|
||||
@@ -54,6 +55,11 @@ Some prominent kittens:
|
||||
filenames, words, lines, etc. from the terminal screen.
|
||||
|
||||
|
||||
:doc:`Command palette <kittens/command-palette>`
|
||||
Browse, search and trigger all keyboard shortcuts and actions from a
|
||||
single searchable overlay.
|
||||
|
||||
|
||||
:doc:`Quick access terminal <kittens/quick-access-terminal>`
|
||||
Get access to a quick access floating, semi-transparent kitty window
|
||||
with a single keypress.
|
||||
|
||||
BIN
docs/screenshots/command-palette.png
Normal file
BIN
docs/screenshots/command-palette.png
Normal file
Binary file not shown.
|
After Width: | Height: | Size: 285 KiB |
Reference in New Issue
Block a user