Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/echasnovski/mini.clue
Show next key clues. Part of 'mini.nvim' library.
https://github.com/echasnovski/mini.clue
lua mini-nvim neovim neovim-plugin
Last synced: 1 day ago
JSON representation
Show next key clues. Part of 'mini.nvim' library.
- Host: GitHub
- URL: https://github.com/echasnovski/mini.clue
- Owner: echasnovski
- License: mit
- Created: 2023-08-01T08:03:46.000Z (over 1 year ago)
- Default Branch: main
- Last Pushed: 2024-08-27T13:56:16.000Z (3 months ago)
- Last Synced: 2024-08-27T15:25:07.329Z (3 months ago)
- Topics: lua, mini-nvim, neovim, neovim-plugin
- Language: Lua
- Homepage:
- Size: 81.1 KB
- Stars: 47
- Watchers: 2
- Forks: 1
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
[](https://github.com/echasnovski/mini.nvim/blob/main/LICENSE)
### Show next key clues
See more details in [Features](#features) and [help file](doc/mini-clue.txt).
---
⦿ This is a part of [mini.nvim](https://github.com/echasnovski/mini.nvim) library. Please use [this link](https://github.com/echasnovski/mini.nvim/blob/main/readmes/mini-clue.md) if you want to mention this module.
⦿ All contributions (issues, pull requests, discussions, etc.) are done inside of 'mini.nvim'.
⦿ See the repository page to learn about common design principles and configuration recipes.
---
If you want to help this project grow but don't know where to start, check out [contributing guides of 'mini.nvim'](https://github.com/echasnovski/mini.nvim/blob/main/CONTRIBUTING.md) or leave a Github star for 'mini.nvim' project and/or any its standalone Git repositories.
## Demo
https://github.com/echasnovski/mini.nvim/assets/24854248/ea931966-067c-48af-93e9-36e9b8afb0ae
## Features
- Implement custom key query process to reach target key combination:
- Starts after customizable opt-in triggers (mode + keys).
- Each key press narrows down set of possible targets.
Pressing `` removes previous user entry.
Pressing `` or `` leads to an early stop.
Doesn't depend on 'timeoutlen' and has basic support for 'langmap'.
- Ends when there is at most one target left or user pressed ``. Results into emulating pressing all query keys plus possible postkeys.
- Show window (after configurable delay) with clues. It lists available next keys along with their descriptions (auto generated from descriptions present keymaps and user-supplied clues; preferring the former).
- Configurable "postkeys" for key combinations - keys which will be emulated after combination is reached during key query process.
- Provide customizable sets of clues for common built-in keys/concepts:
- `g` key.
- `z` key.
- Window commands.
- Built-in completion.
- Marks.
- Registers.
- Lua functions to disable/enable triggers globally or per buffer.
For more details see these tags in help:
- `*MiniClue-key-query-process*`.
- `*MiniClue-examples*`.
- `*MiniClue.config*`.
- `*MiniClue.gen_clues*`.
Notes:
- Works on all supported versions but using Neovim>=0.9 is recommended.
- There is no functionality to create mappings in order to clearly separate two different tasks.
The best suggested practice is to manually create mappings with descriptions (`desc` field in options), as they will be automatically used inside clue window.
- Triggers are implemented as special buffer-local mappings. This leads to several caveats:
- They will override same regular buffer-local mappings and have precedence over global one.
Example: having set `` as Normal mode trigger means that there should not be another `` mapping.
- They need to be the latest created buffer-local mappings or they will not function properly. Most common indicator of this is that some mapping starts to work only after clue window is shown.
Example: `g` is set as Normal mode trigger, but `gcc` from 'mini.comment' doesn't work right away. This is probably because there are some other buffer-local mappings starting with `g` which were created after mapping for `g` trigger. Most common places for this are in LSP server's `on_attach` or during tree-sitter start in buffer.
To check if trigger is the most recent buffer-local mapping, execute `:map ` (like `:nmap g` for previous example). Mapping for trigger should be the first listed.
This module makes the best effort to work out of the box and cover most common cases, but it is not foolproof. The solution here is to ensure that triggers are created after making all buffer-local mappings: run either `MiniClue.setup()` or `MiniClue.ensure_buf_triggers()`.
- Descriptions from existing mappings take precedence over user-supplied clues. This is to ensure that information shown in clue window is as relevant as possible. To add/customize description of an already existing mapping, use `MiniClue.set_mapping_desc()`.
- Due to technical difficulties, there is no foolproof support for Operator-pending mode triggers (like `a`/`i` from 'mini.ai'):
- Doesn't work as part of a command in "temporary Normal mode" (like after `` in Insert mode) due to implementation difficulties.
- Can have unexpected behavior with custom operators.
- Has (mostly solved) issues with macros:
- All triggers are disabled during macro recording due to technical reasons.
- The `@` and `Q` keys are specially mapped inside `MiniClue.setup()` to temporarily disable triggers.
## Config quick start
```lua
local miniclue = require('mini.clue')
miniclue.setup({
triggers = {
-- Leader triggers
{ mode = 'n', keys = '' },
{ mode = 'x', keys = '' },
-- Built-in completion
{ mode = 'i', keys = '' },
-- `g` key
{ mode = 'n', keys = 'g' },
{ mode = 'x', keys = 'g' },
-- Marks
{ mode = 'n', keys = "'" },
{ mode = 'n', keys = '`' },
{ mode = 'x', keys = "'" },
{ mode = 'x', keys = '`' },
-- Registers
{ mode = 'n', keys = '"' },
{ mode = 'x', keys = '"' },
{ mode = 'i', keys = '' },
{ mode = 'c', keys = '' },
-- Window commands
{ mode = 'n', keys = '' },
-- `z` key
{ mode = 'n', keys = 'z' },
{ mode = 'x', keys = 'z' },
},
clues = {
-- Enhance this by adding descriptions for mapping groups
miniclue.gen_clues.builtin_completion(),
miniclue.gen_clues.g(),
miniclue.gen_clues.marks(),
miniclue.gen_clues.registers(),
miniclue.gen_clues.windows(),
miniclue.gen_clues.z(),
},
})
```
## Installation
This plugin can be installed as part of 'mini.nvim' library (**recommended**) or as a standalone Git repository.
There are two branches to install from:
- `main` (default, **recommended**) will have latest development version of plugin. All changes since last stable release should be perceived as being in beta testing phase (meaning they already passed alpha-testing and are moderately settled).
- `stable` will be updated only upon releases with code tested during public beta-testing phase in `main` branch.
Here are code snippets for some common installation methods (use only one):
With mini.deps
Github repo
Branch Code snippet
'mini.nvim' library Main Follow recommended 'mini.deps' installation
Stable
Standalone plugin Main add('echasnovski/mini.clue')
Stable add({ source = 'echasnovski/mini.clue', checkout = 'stable' })
With folke/lazy.nvim
Github repo
Branch Code snippet
'mini.nvim' library
Main { 'echasnovski/mini.nvim', version = false },
Stable { 'echasnovski/mini.nvim', version = '*' },
Standalone plugin
Main { 'echasnovski/mini.clue', version = false },
Stable { 'echasnovski/mini.clue', version = '*' },
With junegunn/vim-plug
Github repo
Branch Code snippet
'mini.nvim' library
Main Plug 'echasnovski/mini.nvim'
Stable Plug 'echasnovski/mini.nvim', { 'branch': 'stable' }
Standalone plugin Main Plug 'echasnovski/mini.clue'
Stable Plug 'echasnovski/mini.clue', { 'branch': 'stable' }
**Important**: don't forget to call `require('mini.clue').setup()` to enable its functionality. **Needs to have triggers configured**.
**Note**: if you are on Windows, there might be problems with too long file paths (like `error: unable to create file : Filename too long`). Try doing one of the following:
- Enable corresponding git global config value: `git config --system core.longpaths true`. Then try to reinstall.
## Default config
```lua
-- No need to copy this inside `setup()`. Will be used automatically.
{
-- Array of extra clues to show
clues = {},
-- Array of opt-in triggers which start custom key query process.
-- **Needs to have something in order to show clues**.
triggers = {},
-- Clue window settings
window = {
-- Floating window config
config = {},
-- Delay before showing clue window
delay = 1000,
-- Keys to scroll inside the clue window
scroll_down = '',
scroll_up = '',
},
}
```
## Similar plugins
- [folke/which-key.nvim](https://github.com/folke/which-key.nvim)
- [anuvyklack/hydra.nvim](https://github.com/anuvyklack/hydra.nvim)