# Neovim Keybindings

**Custom keybindings** in `~/.config/nvim/init.lua` let you personalize Neovim. Use `vim.keymap.set()` to define them.

## Basic syntax

```lua
vim.keymap.set(mode, lhs, rhs, options)
```

- `mode` — `'n'` (normal), `'i'` (insert), `'v'` (visual), `'c'` (command), `''` (all modes)
- `lhs` — keys you press (left-hand side)
- `rhs` — command/keys executed (right-hand side)
- `options` — table of flags

## Common keybindings

```lua
-- Normal mode
vim.keymap.set('n', '<Space>w', ':w<CR>')        -- save
vim.keymap.set('n', '<Space>q', ':q<CR>')        -- quit
vim.keymap.set('n', '<Space>e', ':Explore<CR>')  -- file browser

-- Insert mode
vim.keymap.set('i', 'jk', '<Esc>')               -- exit insert with jk
vim.keymap.set('i', '<C-s>', '<Esc>:w<CR>')      -- save from insert

-- Visual mode
vim.keymap.set('v', '<', '<gv')                  -- indent and stay selected
vim.keymap.set('v', '>', '>gv')
```

`<CR>` is Enter, `<Esc>` is Escape, `<C-x>` is Ctrl+x, `<M-x>` is Alt+x, `<S-x>` is Shift+x.

## Options table

```lua
vim.keymap.set('n', '<leader>x', ':Some Command<CR>', {
    noremap = true,    -- don't expand recursively
    silent = true,     -- no "command executed" message
    buffer = 0,        -- local to buffer 0 (current)
})
```

`noremap = true` is important: prevents the mapped key from being expanded again if it's mapped to another key.

`silent = true` suppresses the status message (cleaner UI).

## Leader key and personal namespace

Remap leader to something accessible:

```lua
vim.g.mapleader = ' '           -- leader is Space
vim.g.maplocalleader = ','      -- local leader is Comma
```

Then build a namespace for personal commands:

```lua
-- File operations
vim.keymap.set('n', '<leader>w', ':w<CR>')
vim.keymap.set('n', '<leader>q', ':q<CR>')
vim.keymap.set('n', '<leader>e', ':Explore<CR>')

-- Navigation
vim.keymap.set('n', '<leader>j', ':bn<CR>')      -- next buffer
vim.keymap.set('n', '<leader>k', ':bp<CR>')      -- prev buffer

-- LSP (if configured)
vim.keymap.set('n', '<leader>d', vim.lsp.buf.definition)
vim.keymap.set('n', '<leader>h', vim.lsp.buf.hover)
```

`<leader>` is expanded at runtime to your leader key (Space in this case).

## Repeatable custom commands

For complex operations, create ex commands:

```lua
vim.api.nvim_create_user_command('JsonFormat', ':silent %!jq .', {})
```

Then map to it:

```lua
vim.keymap.set('n', '<leader>j', ':JsonFormat<CR>')
```

## Special keys and chords

Common special keys: `<C-...>` (Ctrl), `<M-...>` (Alt/Meta), `<S-...>` (Shift), `<CR>` (Enter), `<Tab>`, `<Esc>`, `<BS>` (backspace).

Multi-key chords are harder (require plugins like `which-key` for readability), but simple sequences work:

```lua
-- This would require :set timeoutlen=300 or similar
vim.keymap.set('n', 'gf', vim.lsp.buf.definition)  -- go-to definition
```

## Check existing keybindings

`:map` shows normal and visual maps, `:imap` shows insert maps, `:verbose map <key>` shows where a key is mapped.

Avoid shadowing important keys (`:`, `/`, `?`, `Esc`). Start with leader-based bindings to stay safe.

## Example minimal config

```lua
-- ~/.config/nvim/init.lua
vim.g.mapleader = ' '

-- Options
vim.opt.number = true
vim.opt.expandtab = true
vim.opt.shiftwidth = 4

-- Keybindings
vim.keymap.set('n', '<leader>w', ':w<CR>', { silent = true })
vim.keymap.set('n', '<leader>q', ':q<CR>', { silent = true })
vim.keymap.set('i', 'jk', '<Esc>')
```

Keybindings are personal — tailor them to your workflow. Start simple, add as needed.