421 lines
16 KiB
Plaintext
421 lines
16 KiB
Plaintext
*which-key.nvim.txt* For Neovim >= 0.8.0 Last change: 2024 June 07
|
||
|
||
==============================================================================
|
||
Table of Contents *which-key.nvim-table-of-contents*
|
||
|
||
1. Which Key |which-key.nvim-which-key|
|
||
- Features |which-key.nvim-which-key-features|
|
||
- Requirements |which-key.nvim-which-key-requirements|
|
||
- Installation |which-key.nvim-which-key-installation|
|
||
- Configuration |which-key.nvim-which-key-configuration|
|
||
- Setup |which-key.nvim-which-key-setup|
|
||
- Usage |which-key.nvim-which-key-usage|
|
||
- Plugins |which-key.nvim-which-key-plugins|
|
||
- Colors |which-key.nvim-which-key-colors|
|
||
2. Links |which-key.nvim-links|
|
||
|
||
==============================================================================
|
||
1. Which Key *which-key.nvim-which-key*
|
||
|
||
**WhichKey** is a lua plugin for Neovim 0.5 that displays a popup with possible
|
||
key bindings of the command you started typing. Heavily inspired by the
|
||
original emacs-which-key <https://github.com/justbur/emacs-which-key> and
|
||
vim-which-key <https://github.com/liuchengxu/vim-which-key>.
|
||
|
||
|
||
FEATURES *which-key.nvim-which-key-features*
|
||
|
||
- for Neovim 0.7 and higher, it uses the `desc` attributes of your mappings as the default label
|
||
- for Neovim 0.7 and higher, new mappings will be created with a `desc` attribute
|
||
- opens a popup with suggestions to complete a key binding
|
||
- works with any setting for |timeoutlen|, including instantly (`timeoutlen=0`)
|
||
- works correctly with built-in key bindings
|
||
- works correctly with buffer-local mappings
|
||
- extensible plugin architecture
|
||
- built-in plugins:
|
||
- **marks:** shows your marks when you hit one of the jump keys.
|
||
- **registers:** shows the contents of your registers
|
||
- **presets:** built-in key binding help for `motions`, `text-objects`, `operators`, `windows`, `nav`, `z` and `g`
|
||
- **spelling:** spelling suggestions inside the which-key popup
|
||
|
||
|
||
REQUIREMENTS *which-key.nvim-which-key-requirements*
|
||
|
||
- Neovim >= 0.5.0
|
||
|
||
|
||
INSTALLATION *which-key.nvim-which-key-installation*
|
||
|
||
Install the plugin with your preferred package manager:
|
||
|
||
|
||
LAZY.NVIM ~
|
||
|
||
>lua
|
||
{
|
||
"folke/which-key.nvim",
|
||
event = "VeryLazy",
|
||
init = function()
|
||
vim.o.timeout = true
|
||
vim.o.timeoutlen = 300
|
||
end,
|
||
opts = {
|
||
-- your configuration comes here
|
||
-- or leave it empty to use the default settings
|
||
-- refer to the configuration section below
|
||
}
|
||
}
|
||
<
|
||
|
||
|
||
PACKER ~
|
||
|
||
>lua
|
||
-- Lua
|
||
use {
|
||
"folke/which-key.nvim",
|
||
config = function()
|
||
vim.o.timeout = true
|
||
vim.o.timeoutlen = 300
|
||
require("which-key").setup {
|
||
-- your configuration comes here
|
||
-- or leave it empty to use the default settings
|
||
-- refer to the configuration section below
|
||
}
|
||
end
|
||
}
|
||
<
|
||
|
||
|
||
CONFIGURATION *which-key.nvim-which-key-configuration*
|
||
|
||
|
||
IMPORTANT: the |timeout| when **WhichKey** opens is controlled by the vim
|
||
setting |timeoutlen|. Please refer to the documentation to properly set it up.
|
||
Setting it to `0`, will effectively always show **WhichKey** immediately, but a
|
||
setting of `500` (500ms) is probably more appropriate.
|
||
|
||
don’t create any keymappings yourself to trigger WhichKey. Unlike with
|
||
_vim-which-key_, we do this fully automatically. Please remove any left-over
|
||
triggers you might have from using _vim-which-key_.
|
||
|
||
You can run `:checkhealth which-key` to see if there’s any conflicting
|
||
keymaps that will prevent triggering **WhichKey**
|
||
WhichKey comes with the following defaults:
|
||
|
||
>lua
|
||
{
|
||
plugins = {
|
||
marks = true, -- shows a list of your marks on ' and `
|
||
registers = true, -- shows your registers on " in NORMAL or <C-r> in INSERT mode
|
||
-- the presets plugin, adds help for a bunch of default keybindings in Neovim
|
||
-- No actual key bindings are created
|
||
spelling = {
|
||
enabled = true, -- enabling this will show WhichKey when pressing z= to select spelling suggestions
|
||
suggestions = 20, -- how many suggestions should be shown in the list?
|
||
},
|
||
presets = {
|
||
operators = true, -- adds help for operators like d, y, ...
|
||
motions = true, -- adds help for motions
|
||
text_objects = true, -- help for text objects triggered after entering an operator
|
||
windows = true, -- default bindings on <c-w>
|
||
nav = true, -- misc bindings to work with windows
|
||
z = true, -- bindings for folds, spelling and others prefixed with z
|
||
g = true, -- bindings for prefixed with g
|
||
},
|
||
},
|
||
-- add operators that will trigger motion and text object completion
|
||
-- to enable all native operators, set the preset / operators plugin above
|
||
operators = { gc = "Comments" },
|
||
key_labels = {
|
||
-- override the label used to display some keys. It doesn't effect WK in any other way.
|
||
-- For example:
|
||
-- ["<space>"] = "SPC",
|
||
-- ["<cr>"] = "RET",
|
||
-- ["<tab>"] = "TAB",
|
||
},
|
||
motions = {
|
||
count = true,
|
||
},
|
||
icons = {
|
||
breadcrumb = "»", -- symbol used in the command line area that shows your active key combo
|
||
separator = "➜", -- symbol used between a key and it's label
|
||
group = "+", -- symbol prepended to a group
|
||
},
|
||
popup_mappings = {
|
||
scroll_down = "<c-d>", -- binding to scroll down inside the popup
|
||
scroll_up = "<c-u>", -- binding to scroll up inside the popup
|
||
},
|
||
window = {
|
||
border = "none", -- none, single, double, shadow
|
||
position = "bottom", -- bottom, top
|
||
margin = { 1, 0, 1, 0 }, -- extra window margin [top, right, bottom, left]. When between 0 and 1, will be treated as a percentage of the screen size.
|
||
padding = { 1, 2, 1, 2 }, -- extra window padding [top, right, bottom, left]
|
||
winblend = 0, -- value between 0-100 0 for fully opaque and 100 for fully transparent
|
||
zindex = 1000, -- positive value to position WhichKey above other floating windows.
|
||
},
|
||
layout = {
|
||
height = { min = 4, max = 25 }, -- min and max height of the columns
|
||
width = { min = 20, max = 50 }, -- min and max width of the columns
|
||
spacing = 3, -- spacing between columns
|
||
align = "left", -- align columns left, center or right
|
||
},
|
||
ignore_missing = false, -- enable this to hide mappings for which you didn't specify a label
|
||
hidden = { "<silent>", "<cmd>", "<Cmd>", "<CR>", "^:", "^ ", "^call ", "^lua " }, -- hide mapping boilerplate
|
||
show_help = true, -- show a help message in the command line for using WhichKey
|
||
show_keys = true, -- show the currently pressed key and its label as a message in the command line
|
||
triggers = "auto", -- automatically setup triggers
|
||
-- triggers = {"<leader>"} -- or specify a list manually
|
||
-- list of triggers, where WhichKey should not wait for timeoutlen and show immediately
|
||
triggers_nowait = {
|
||
-- marks
|
||
"`",
|
||
"'",
|
||
"g`",
|
||
"g'",
|
||
-- registers
|
||
'"',
|
||
"<c-r>",
|
||
-- spelling
|
||
"z=",
|
||
},
|
||
triggers_blacklist = {
|
||
-- list of mode / prefixes that should never be hooked by WhichKey
|
||
-- this is mostly relevant for keymaps that start with a native binding
|
||
i = { "j", "k" },
|
||
v = { "j", "k" },
|
||
},
|
||
-- disable the WhichKey popup for certain buf types and file types.
|
||
-- Disabled by default for Telescope
|
||
disable = {
|
||
buftypes = {},
|
||
filetypes = {},
|
||
},
|
||
}
|
||
<
|
||
|
||
|
||
SETUP *which-key.nvim-which-key-setup*
|
||
|
||
With the default settings, **WhichKey** will work out of the box for most
|
||
builtin keybindings, but the real power comes from documenting and organizing
|
||
your own keybindings.
|
||
|
||
To document and/or setup your own mappings, you need to call the `register`
|
||
method
|
||
|
||
>lua
|
||
local wk = require("which-key")
|
||
wk.register(mappings, opts)
|
||
<
|
||
|
||
Default options for `opts`
|
||
|
||
>lua
|
||
{
|
||
mode = "n", -- NORMAL mode
|
||
-- prefix: use "<leader>f" for example for mapping everything related to finding files
|
||
-- the prefix is prepended to every mapping part of `mappings`
|
||
prefix = "",
|
||
buffer = nil, -- Global mappings. Specify a buffer number for buffer local mappings
|
||
silent = true, -- use `silent` when creating keymaps
|
||
noremap = true, -- use `noremap` when creating keymaps
|
||
nowait = false, -- use `nowait` when creating keymaps
|
||
expr = false, -- use `expr` when creating keymaps
|
||
}
|
||
<
|
||
|
||
|
||
When you specify a command in your mapping that starts with `<Plug>`, then we
|
||
automatically set `noremap=false`, since you always want recursive keybindings
|
||
in this case
|
||
|
||
MAPPINGS ~
|
||
|
||
|
||
for **Neovim 0.7** and higher, which key will use the `desc` attribute of
|
||
existing mappings as the default label
|
||
Group names use the special `name` key in the tables. There’s multiple ways
|
||
to define the mappings. `wk.register` can be called multiple times from
|
||
anywhere in your config files.
|
||
|
||
>lua
|
||
local wk = require("which-key")
|
||
-- As an example, we will create the following mappings:
|
||
-- * <leader>ff find files
|
||
-- * <leader>fr show recent files
|
||
-- * <leader>fb Foobar
|
||
-- we'll document:
|
||
-- * <leader>fn new file
|
||
-- * <leader>fe edit file
|
||
-- and hide <leader>1
|
||
|
||
wk.register({
|
||
f = {
|
||
name = "file", -- optional group name
|
||
f = { "<cmd>Telescope find_files<cr>", "Find File" }, -- create a binding with label
|
||
r = { "<cmd>Telescope oldfiles<cr>", "Open Recent File", noremap=false, buffer = 123 }, -- additional options for creating the keymap
|
||
n = { "New File" }, -- just a label. don't create any mapping
|
||
e = "Edit File", -- same as above
|
||
["1"] = "which_key_ignore", -- special label to hide it in the popup
|
||
b = { function() print("bar") end, "Foobar" } -- you can also pass functions!
|
||
},
|
||
}, { prefix = "<leader>" })
|
||
<
|
||
|
||
Click to see more examples ~
|
||
|
||
>lua
|
||
-- all of the mappings below are equivalent
|
||
|
||
-- method 2
|
||
wk.register({
|
||
["<leader>"] = {
|
||
f = {
|
||
name = "+file",
|
||
f = { "<cmd>Telescope find_files<cr>", "Find File" },
|
||
r = { "<cmd>Telescope oldfiles<cr>", "Open Recent File" },
|
||
n = { "<cmd>enew<cr>", "New File" },
|
||
},
|
||
},
|
||
})
|
||
|
||
-- method 3
|
||
wk.register({
|
||
["<leader>f"] = {
|
||
name = "+file",
|
||
f = { "<cmd>Telescope find_files<cr>", "Find File" },
|
||
r = { "<cmd>Telescope oldfiles<cr>", "Open Recent File" },
|
||
n = { "<cmd>enew<cr>", "New File" },
|
||
},
|
||
})
|
||
|
||
-- method 4
|
||
wk.register({
|
||
["<leader>f"] = { name = "+file" },
|
||
["<leader>ff"] = { "<cmd>Telescope find_files<cr>", "Find File" },
|
||
["<leader>fr"] = { "<cmd>Telescope oldfiles<cr>", "Open Recent File" },
|
||
["<leader>fn"] = { "<cmd>enew<cr>", "New File" },
|
||
})
|
||
<
|
||
|
||
**Tips:** The default label is `keymap.desc` or `keymap.rhs` or `""`,
|
||
|nvim_set_keymap()| to get more details about `desc` and `rhs`.
|
||
|
||
|
||
OPERATORS, MOTIONS AND TEXT OBJECTS ~
|
||
|
||
**WhichKey** provides help to work with operators, motions and text objects.
|
||
|
||
|
||
`[count]operator[count][text-object]`
|
||
- operators can be configured with the `operators` option
|
||
- set `plugins.presets.operators` to `true` to automatically configure vim built-in operators
|
||
- set this to `false`, to only include the list you configured in the `operators` option.
|
||
- see here <https://github.com/folke/which-key.nvim/blob/main/lua/which-key/plugins/presets/init.lua#L5> for the full list part of the preset
|
||
- text objects are automatically retrieved from **operator pending** key maps (`omap`)
|
||
- set `plugins.presets.text_objects` to `true` to configure built-in text objects
|
||
- see here <https://github.com/folke/which-key.nvim/blob/main/lua/which-key/plugins/presets/init.lua#L43>
|
||
- motions are part of the preset `plugins.presets.motions` setting
|
||
- see here <https://github.com/folke/which-key.nvim/blob/main/lua/which-key/plugins/presets/init.lua#L20>
|
||
|
||
How to disable some operators? (like v) ~
|
||
|
||
>lua
|
||
-- make sure to run this code before calling setup()
|
||
-- refer to the full lists at https://github.com/folke/which-key.nvim/blob/main/lua/which-key/plugins/presets/init.lua
|
||
local presets = require("which-key.plugins.presets")
|
||
presets.operators["v"] = nil
|
||
<
|
||
|
||
|
||
USAGE *which-key.nvim-which-key-usage*
|
||
|
||
When the **WhichKey** popup is open, you can use the following key bindings
|
||
(they are also displayed at the bottom of the screen):
|
||
|
||
- hit one of the keys to open a group or execute a key binding
|
||
- `<esc>` to cancel and close the popup
|
||
- `<bs>` go up one level
|
||
- `<c-d>` scroll down
|
||
- `<c-u>` scroll up
|
||
|
||
Apart from the automatic opening, you can also manually open **WhichKey** for a
|
||
certain `prefix`
|
||
|
||
|
||
don’t create any keymappings yourself to trigger WhichKey. Unlike with
|
||
_vim-which-key_, we do this fully automatically. Please remove any left-over
|
||
triggers you might have from using _vim-which-key_.
|
||
>vim
|
||
:WhichKey " show all mappings
|
||
:WhichKey <leader> " show all <leader> mappings
|
||
:WhichKey <leader> v " show all <leader> mappings for VISUAL mode
|
||
:WhichKey '' v " show ALL mappings for VISUAL mode
|
||
<
|
||
|
||
|
||
PLUGINS *which-key.nvim-which-key-plugins*
|
||
|
||
Four built-in plugins are included with **WhichKey**.
|
||
|
||
|
||
MARKS ~
|
||
|
||
Shows a list of your buffer local and global marks when you hit ` or ’
|
||
|
||
|
||
REGISTERS ~
|
||
|
||
Shows a list of your buffer local and global registers when you hit ” in
|
||
_NORMAL_ mode, or `<c-r>` in _INSERT_ mode.
|
||
|
||
|
||
PRESETS ~
|
||
|
||
Built-in key binding help for `motions`, `text-objects`, `operators`,
|
||
`windows`, `nav`, `z` and `g`
|
||
|
||
|
||
SPELLING ~
|
||
|
||
When enabled, this plugin hooks into `z=` and replaces the full-screen spelling
|
||
suggestions window by a list of suggestions within **WhichKey**.
|
||
|
||
|
||
COLORS *which-key.nvim-which-key-colors*
|
||
|
||
The table below shows all the highlight groups defined for **WhichKey** with
|
||
their default link.
|
||
|
||
---------------------------------------------------------------------------
|
||
Highlight Group Defaults to Description
|
||
------------------- ------------- -----------------------------------------
|
||
WhichKey Function the key
|
||
|
||
WhichKeyGroup Keyword a group
|
||
|
||
WhichKeySeparator DiffAdd the separator between the key and its
|
||
label
|
||
|
||
WhichKeyDesc Identifier the label of the key
|
||
|
||
WhichKeyFloat NormalFloat Normal in the popup window
|
||
|
||
WhichKeyBorder FloatBorder Normal in the popup window
|
||
|
||
WhichKeyValue Comment used by plugins that provide values
|
||
---------------------------------------------------------------------------
|
||
==============================================================================
|
||
2. Links *which-key.nvim-links*
|
||
|
||
1. *image*: https://user-images.githubusercontent.com/292349/116439438-669f8d00-a804-11eb-9b5b-c7122bd9acac.png
|
||
2. *image*: https://user-images.githubusercontent.com/292349/116439573-8f278700-a804-11eb-80ca-bb9263e6d937.png
|
||
3. *image*: https://user-images.githubusercontent.com/292349/116439609-98b0ef00-a804-11eb-9385-97c7d5ff4113.png
|
||
4. *image*: https://user-images.githubusercontent.com/292349/116439871-df9ee480-a804-11eb-9529-800e167db65c.png
|
||
5. *image*: https://user-images.githubusercontent.com/292349/118102022-1c361880-b38d-11eb-8e82-79ad266d9bb8.png
|
||
|
||
Generated by panvimdoc <https://github.com/kdheepak/panvimdoc>
|
||
|
||
vim:tw=78:ts=8:noet:ft=help:norl:
|