Skip to main content
Keymaps are keyboard shortcuts that execute commands in Neovim. Magictt centralizes core keymaps in lua/magictt/core/keymaps.lua, while plugin-specific keymaps are defined in their respective plugin files.

​
Where to Add Keymaps

​
Core Keymaps

General-purpose keymaps go in lua/magictt/core/keymaps.lua.

​
Plugin-Specific Keymaps

Plugin keymaps should be defined in the plugin’s config function (e.g., lua/magictt/plugins/telescope.lua:30-36).

​
Keymap Syntax

The basic syntax for creating a keymap: 
vim.keymap.set(mode, keys, command, options)

​
Parameters

  • mode - The mode(s) where the keymap applies:
    • "n" - Normal mode
    • "i" - Insert mode
    • "v" - Visual mode
    • "x" - Visual block mode
    • "t" - Terminal mode
    • "c" - Command mode
  • keys - The key combination to trigger the command
  • command - The command to execute (string or function)
  • options - Optional table with:
    • desc - Description (shown in which-key)
    • silent - Don’t show command in command line
    • noremap - Don’t allow remapping
    • buffer - Apply to current buffer only

​
Real Examples from Magictt

​
Leader Key (keymaps.lua:1-2)

The leader key is set to space: 
vim.g.mapleader = " "

​
Exit Insert Mode (keymaps.lua:6)

keymap.set("i", "jk", "<ESC>", { desc = "Exit insert mode with jk" })
Press jk quickly in insert mode to return to normal mode.

​
File Explorer (keymaps.lua:7)

keymap.set("n", "<leader>pv", vim.cmd.Ex, { desc = "Open explorer" })
Press <space>pv in normal mode to open the file explorer.

​
Clear Search Highlights (keymaps.lua:12)

keymap.set("n", "<leader>nh", ":nohl<CR>", { desc = "Clear search highlights" })

​
Window Management (keymaps.lua:22-25)

keymap.set("n", "<leader>sv", "<C-w>v", { desc = "Split window vertically" })
keymap.set("n", "<leader>sh", "<C-w>s", { desc = "Split window horizontally" })
keymap.set("n", "<leader>se", "<C-w>=", { desc = "Make splits equal size" })
keymap.set("n", "<leader>sx", "<cmd>close<CR>", { desc = "Close current split" })

​
Tab Management (keymaps.lua:27-31)

keymap.set("n", "<leader>to", "<cmd>tabnew<CR>", { desc = "Open new tab" })
keymap.set("n", "<leader>tx", "<cmd>tabclose<CR>", { desc = "Close current tab" })
keymap.set("n", "<leader>tn", "<cmd>tabn<CR>", { desc = "Go to next tab" })
keymap.set("n", "<leader>tp", "<cmd>tabp<CR>", { desc = "Go to previous tab" })
keymap.set("n", "<leader>tf", "<cmd>tabnew %<CR>", { desc = "Open current buffer in new tab" })

​
Number Increment/Decrement (keymaps.lua:16-17)

keymap.set("n", "<leader>+", "<C-a>", { desc = "Increment number" })
keymap.set("n", "<leader>-", "<C-x>", { desc = "Decrement number" })

​
Adding Your Own Keymaps

1

Open keymaps.lua

Open the core keymaps file:
nvim lua/magictt/core/keymaps.lua
2

Add your keymap

Add a new keymap using the established pattern:
local keymap = vim.keymap

-- Your custom keymap
keymap.set("n", "<leader>cc", ":!cargo check<CR>", { desc = "Run cargo check" })
3

Test the keymap

Save the file and restart Neovim (or run :source %). Test your new keymap.
4

Verify in which-key

Press <leader> and wait a moment. Which-key will show your new keymap with its description.

​
Best Practices

​
1. Use Descriptive Names

Always include a desc option so the keymap appears in which-key: 
-- Good
keymap.set("n", "<leader>ff", "<cmd>Telescope find_files<cr>", { desc = "Fuzzy find files in cwd" })

-- Bad (no description)
keymap.set("n", "<leader>ff", "<cmd>Telescope find_files<cr>")
Use consistent prefixes for related functions:
  • <leader>f - Find/search operations (Telescope)
  • <leader>s - Split window operations
  • <leader>t - Tab operations
  • <leader>m - Misc operations (Mason, etc.)

​
3. Avoid Conflicts

Check existing keymaps before adding new ones: 
:map <leader>x
Or use which-key by pressing <leader> and browsing.

​
4. Use Leader Key for Custom Commands

The leader key (<space>) is reserved for user-defined keymaps. Avoid overriding default Vim keymaps unless intentional.

​
5. Make It Memorable

Choose intuitive key combinations:
  • <leader>ff - Find Files
  • <leader>fs - Find String
  • <leader>sv - Split Vertically
  • <leader>sh - Split Horizontally

​
Advanced Patterns

​
Function Keymaps

Execute a Lua function: 
keymap.set("n", "<leader>cf", function()
  vim.lsp.buf.format({ async = true })
end, { desc = "Format current buffer" })

​
Buffer-Specific Keymaps

Keymaps that only apply to the current buffer: 
keymap.set("n", "<leader>r", ":!python %<CR>", { 
  desc = "Run Python file",
  buffer = true 
})

​
Multiple Modes

Apply the same keymap to multiple modes: 
keymap.set({"n", "v"}, "<leader>y", '"+y', { desc = "Yank to system clipboard" })

​
Conditional Keymaps

Create keymaps based on conditions: 
if vim.fn.executable("cargo") == 1 then
  keymap.set("n", "<leader>cr", ":!cargo run<CR>", { desc = "Cargo run" })
end

​
Plugin-Specific Keymaps

When adding a plugin, define its keymaps in the plugin file’s config function: 
-- lua/magictt/plugins/my-plugin.lua
return {
  "author/my-plugin",
  config = function()
    local plugin = require("my-plugin")
    plugin.setup()
    
    -- Plugin keymaps
    local keymap = vim.keymap
    keymap.set("n", "<leader>mp", ":MyPluginCommand<CR>", { desc = "My plugin command" })
  end,
}
This keeps plugin keymaps close to their configuration and makes them easier to manage.

​
Common Key Notations

  • <CR> - Enter
  • <ESC> - Escape
  • <C-x> - Ctrl + x
  • <S-x> - Shift + x
  • <A-x> or <M-x> - Alt + x
  • <leader> - Space (in Magictt)
  • <cmd> - Execute command mode command

​
Viewing All Keymaps

To see all keymaps: 
:map     " All modes
:nmap    " Normal mode
:imap    " Insert mode
:vmap    " Visual mode
Or use which-key by pressing <leader> and browsing available keymaps.

Build docs developers (and LLMs) love

Get started for freeTalk to us