[!NOTE] legendary.nvim is looking for a new maintainer!

`legendary.nvim`

Features | Prerequisites | Installation | Quickstart | Configuration

</div>

Define your keymaps, commands, and autocommands as simple Lua tables, building a legend at the same time (like VS Code's Command Palette).

demo gif
<sup>Theme used in recording is onedarkpro.nvim. The finder UI is handled by telescope.nvim via dressing.nvim. See Prerequisites for details.</sup>

Table of Contents

Features

Define your keymaps, commands, augroup/autocmds, and even arbitrary Lua functions to run on the fly, as simple Lua tables, then bind them with legendary.nvim
Integration with which-key.nvim, use your existing which-key.nvim tables with legendary.nvim (see extensions)
Integration with lazy.nvim, automatically load keymaps defined via lazy.nvim's keys property on plugin specs (see extensions)
Execute normal, insert, and visual mode keymaps, commands, autocommands, and Lua functions when you select them
Show your most recently executed items at the top when triggered via legendary.nvim (can be disabled via config)
Uses vim.ui.select() so it can be hooked up to a fuzzy finder using something like dressing.nvim for a VS Code command palette like interface
Buffer-local keymaps, commands, functions and autocmds only appear in the finder for the current buffer
Help execute commands that take arguments by prefilling the command line instead of executing immediately
Search built-in keymaps and commands along with your user-defined keymaps and commands (may be disabled in config). Notice some missing? Comment on this discussion or submit a PR!
A legendary.toolbox module to help create lazily-evaluated keymaps and commands, and item filter. Have an idea for a new helper? Comment on this discussion or submit a PR!
Sort by frecency, a combined measure of how frequently and how recently you've used an item from the picker
A parser to convert Vimscript keymap commands (e.g. vnoremap <silent> <leader>f :SomeCommand<CR>) to legendary.nvim keymap tables (see Converting Keymaps From Vimscript)
Anonymous mappings; show mappings/commands in the finder without having legendary.nvim handle creating them
Extensions to automatically load keymaps and commands from other plugins

Prerequisites

(Optional) A vim.ui.select() handler; this provides the UI for the finder.
- I recommend telescope.nvim paired with dressing.nvim.

Installation

This project uses git tags to adhere to Semantic Versioning. To check the latest version, see the git tag list.

With lazy.nvim:

-- to use a version
{
  'mrjones2014/legendary.nvim',
  version = 'v2.13.9',
  -- since legendary.nvim handles all your keymaps/commands,
  -- its recommended to load legendary.nvim before other plugins
  priority = 10000,
  lazy = false,
  -- sqlite is only needed if you want to use frecency sorting
  -- dependencies = { 'kkharji/sqlite.lua' }
}
-- or, to get rolling updates
{
  'mrjones2014/legendary.nvim',
  -- since legendary.nvim handles all your keymaps/commands,
  -- its recommended to load legendary.nvim before other plugins
  priority = 10000,
  lazy = false,
  -- sqlite is only needed if you want to use frecency sorting
  -- dependencies = { 'kkharji/sqlite.lua' }
}

With vim-plug:

" if you want to use frecency sorting, sqlite is also needed
Plug "kkharji/sqlite.lua"

" to use a version
Plug "mrjones2014/legendary.nvim", { 'tag': 'v2.1.0' }
" or, to get rolling updates
Plug "mrjones2014/legendary.nvim"

Quickstart

If you use lazy.nvim for your plugin manager, legendary.nvim can automatically register keymaps defined via the keys property of lazy.nvim plugin specs. This lets you keep your plugin-specific keymaps where you define the plugin, and legendary.nvim automatically detects them. For example:

-- in a plugin spec:
{
  'folke/flash.nvim',
  keys = {
    {
      's',
      function()
        require('flash').jump()
      end,
      mode = { 'n', 'x', 'o' },
      desc = 'Jump forwards',
    },
    {
      'S',
      function()
        require('flash').jump({ search = { forward = false } })
      end,
      mode = { 'n', 'x', 'o' },
      desc = 'Jump backwards',
    },
  },
}

-- where you set up legendary.nvim
-- now the keymaps from the `flash.nvim` plugin spec will be automatically loaded
require('legendary').setup({ extensions = { lazy_nvim = true } })

Otherwise, register keymaps, commands, autocmds, and functions through setup, including opting into extensions which can automatically load keymaps and commands from other plugins:

require('legendary').setup({
  keymaps = {
    -- map keys to a command
    { '<leader>ff', ':Telescope find_files', description = 'Find files' },
    -- map keys to a function
    {
      '<leader>h',
      function()
        print('hello world!')
      end,
      description = 'Say hello',
    },
    -- Set options used during keymap creation
    { '<leader>s', ':SomeCommand<CR>', description = 'Non-silent keymap', opts = { silent = true } },
    -- create keymaps with different implementations per-mode
    {
      '<leader>c',
      { n = ':LinewiseCommentToggle<CR>', x = ":'<,'>BlockwiseCommentToggle<CR>" },
      description = 'Toggle comment',
    },
    -- create item groups to create sub-menus in the finder
    -- note that only keymaps, commands, and functions
    -- can be added to item groups
    {
      -- groups with same itemgroup will be merged
      itemgroup = 'short ID',
      description = 'A submenu of items...',
      icon = '',
      keymaps = {
        -- more keymaps here
      },
    },
    -- in-place filters, see :h legendary-tables or ./doc/table_structures/README.md
    { '<leader>m', description = 'Preview markdown', filters = { ft = 'markdown' } },
  },
  commands = {
    -- easily create user commands
    {
      ':SayHello',
      function()
        print('hello world!')
      end,
      description = 'Say hello as a command',
    },
    {
      -- groups with same itemgroup will be merged
      itemgroup = 'short ID',
      -- don't need to copy the other group data because
      -- it will be merged with the one from the keymaps table
      commands = {
        -- more commands here
      },
    },
    -- in-place filters, see :h legendary-tables or ./doc/table_structures/README.md
    { ':Glow', description = 'Preview markdown', filters = { ft = 'markdown' } },
  },
  funcs = {
    -- Make arbitrary Lua functions that can be executed via the item finder
    {
      function()
        doSomeStuff()
      end,
      description = 'Do some stuff with a Lua function!',
    },
    {
      -- groups with same itemgroup will be merged
      itemgroup = 'short ID',
      -- don't need to copy the other group data because
      -- it will be merged with the one from the keymaps table
      funcs = {
        -- more funcs here
      },
    },
  },
  autocmds = {
    -- Create autocmds and augroups
    { 'BufWritePre', vim.lsp.buf.format, description = 'Format on save' },
    {
      name = 'MyAugroup',
      clear = true,
      -- autocmds here
    },
  },
  -- load extensions
  extensions = {
    -- automatically load keymaps from lazy.nvim's `keys` option
    lazy_nvim = true,
    -- load keymaps and commands from nvim-tree.lua
    nvim_tree = true,
    -- load commands from smart-splits.nvim
    -- and create keymaps, see :h legendary-extensions-smart-splits.nvim
    smart_splits = {
      directions = { 'h', 'j', 'k', 'l' },
      mods = {
        move = '<C>',
        resize = '<M>',
      },
    },
    -- load commands from op.nvim
    op_nvim = true,
    -- load keymaps from diffview.nvim
    diffview = true,
  },
})

For more mapping features and more complicated setups see Table Structures.

To trigger the finder for your configured keymaps, commands, augroup/autocmds, and Lua functions:

Commands:

" search keymaps, commands, and autocmds
:Legendary

" search keymaps
:Legendary keymaps

" search commands
:Legendary commands

" search functions
:Legendary functions

" search autocmds
:Legendary autocmds

" repeat the last item executed via legendary.nvim's finder;
" by default, only executes

Legendary.nvim

Install / Use

README

`legendary.nvim`

Features

Prerequisites

Installation

Quickstart