From 52e04cd8df9aacb12a13063ca372eb156c9ee388 Mon Sep 17 00:00:00 2001 From: ray Date: Fri, 19 Dec 2025 21:44:01 +0000 Subject: [PATCH] update --- KEYMAPS.md | 242 ++++++++++++++++++++++++++++++++++++++ MIGRATION_PLAN.md | 2 +- README.md | 1 + init.lua | 2 +- lua/keymaps_reference.lua | 74 ++++++++++++ 5 files changed, 319 insertions(+), 2 deletions(-) create mode 100644 KEYMAPS.md create mode 100644 lua/keymaps_reference.lua diff --git a/KEYMAPS.md b/KEYMAPS.md new file mode 100644 index 0000000..8af3087 --- /dev/null +++ b/KEYMAPS.md @@ -0,0 +1,242 @@ +# Keymap Reference + +Living reference of every explicit keymap defined in this config. Use `:KeymapsGuide` to open this file inside Neovim in a floating window. + +## `lua/keymaps.lua` + +| Mode | Key | Description | Notes | +| --- | --- | --- | --- | +| n | `gd` | Vim goto-definition fallback | Executes `normal! gd` for tags/include jumps when no LSP | +| n | `gD` | Vim goto-declaration fallback | Executes `normal! gD` | +| n | `gr` | LSP references placeholder | `` so LSP buffers can override cleanly | +| n | `gI` | LSP implementation placeholder | `` so LSP buffers can override cleanly | +| n | `K` | Keyword help fallback | Uses `keywordprg` (e.g., `man`) when LSP hover is unavailable | +| n | `xx` | Diagnostics → location list | Populates current buffer diagnostics | +| n | `xX` | Diagnostics → quickfix | Populates project-wide diagnostics | +| n | `xe` | Diagnostics → buffer errors | Location list filtered to errors | +| n | `xE` | Diagnostics → all errors | Quickfix filtered to errors | +| n | `[d` | Diagnostics: previous item | Uses `vim.diagnostic.goto_prev` | +| n | `]d` | Diagnostics: next item | Uses `vim.diagnostic.goto_next` | +| n | `xd` | Diagnostic float | Opens hover window for cursor diagnostic | +| n | `xt` | Toggle diagnostics | Flips `vim.diagnostic.enable()` | +| n | `hi` | Highlight inspector | Shows highlight/capture stack under cursor | + +## `lua/netrw-config.lua` + +| Mode | Key | Description | +| --- | --- | --- | +| n | `te` | Open netrw in a new tab rooted at current file directory | +| n | `tE` | Open netrw in a new tab rooted at project cwd | + +## `lua/plugins/lsp.lua` *(buffer-local when an LSP client attaches)* + +| Mode | Key | Description | +| --- | --- | --- | +| n | `gd` | LSP: go to definition | +| n | `gr` | LSP: references | +| n | `gD` | LSP: declaration | +| n | `gI` | LSP: implementation | +| n | `K` | LSP hover | + +## `lua/plugins/none-ls.lua` + +| Mode | Key | Description | +| --- | --- | --- | +| n | `lt` | Toggle format-on-save flag | +| n | `lf` | Format current buffer (synchronous) | +| v | `lf` | Format visual selection | + +## `lua/plugins/gitsigns.lua` *(buffer-local when inside a git repo)* + +| Mode | Key | Description | +| --- | --- | --- | +| n | `]h` | Next hunk (`expr` mapping that respects `diff` windows) | +| n | `[h` | Previous hunk | +| n | `hs` | Stage current hunk | +| n | `hr` | Reset current hunk | +| v | `hs` | Stage visually selected range as hunk | +| v | `hr` | Reset visually selected range | +| n | `hS` | Stage entire buffer | +| n | `hu` | Undo last staged hunk | +| n | `hR` | Reset entire buffer | +| n | `hp` | Preview hunk | +| n | `hd` | Diff against index | +| n | `hD` | Diff against previous commit (`~`) | +| o/x | `ih` | Text object: select git hunk | + +## `lua/plugins/telescope.lua` + +### Launcher mappings (normal mode) + +| Key | Description | +| --- | --- | +| `ff` | Find files | +| `fg` | Live grep | +| `fb` | Open buffers picker (`` deletes buffers in picker) | +| `fh` | Help tags | +| `fr` | Recent files (oldfiles) | +| `/` | Fuzzy search current buffer | +| `fk` / `?` | Telescope keymaps picker | +| `fc` | Commands picker | +| `fs` | LSP document symbols | +| `fS` | LSP workspace symbols | + +### Telescope prompt mappings (`defaults.mappings`) + +| Mode | Key | Description | +| --- | --- | --- | +| i | `` / `` | Move selection down | +| i | `` / `` | Move selection up | +| i | `` | Close picker | +| i | `` | Accept selection | +| i | `` | Open selection in horizontal split | +| i | `` | Open selection in vertical split | +| i | `` | Open selection in tab | +| n | `` | Close picker | +| n | `` | Accept selection | +| n | `` | Horizontal split | +| n | `` | Vertical split | +| n | `` | New tab | +| n | `j` | Move selection down | +| n | `k` | Move selection up | + +### Picker-specific overrides + +| Context | Mode | Key | Description | +| --- | --- | --- | --- | +| `buffers` picker | i | `` | Delete highlighted buffer | + +## `lua/plugins/oil.lua` + +### Global launcher mappings + +| Mode | Key | Description | +| --- | --- | --- | +| n | `fo` | Open Oil in current window | +| n | `fO` | Open Oil in floating window | + +### Oil buffer mappings (`opts.keymaps`) + +| Key | Description | +| --- | --- | +| `g?` | Show Oil help | +| `` | Open entry in current window | +| `` | Open entry in vertical split | +| `` | Open entry in horizontal split | +| `` | Open entry in new tab | +| `` | Preview entry (vertical split belowright) | +| `` | Close Oil | +| `` | Refresh | +| `-` | Go to parent directory | +| `_` | Open Neovim cwd | +| `` ` `` | `:cd` into entry | +| `~` | `:tcd` into entry | +| `gs` | Change sort mode | +| `gx` | Open entry externally | +| `g.` | Toggle hidden files | +| `g\` | Toggle trash visibility | + +## `lua/plugins/ufo.lua` + +| Mode | Key | Description | +| --- | --- | --- | +| n | `zR` | Open all folds | +| n | `zM` | Close all folds | +| n | `zr` | Open folds except configured kinds | +| n | `zm` | Close folds with configured kinds | +| n | `K` | Peek fold under cursor; falls back to LSP hover | +| preview window | `` / `` | Scroll within UFO preview | +| preview window | `[` / `]` | Jump to top/bottom of preview | + +## `lua/plugins/undotree.lua` + +| Mode | Key | Description | +| --- | --- | --- | +| n | `u` | Toggle Undotree panel | + +## `lua/plugins/treesitter.lua` + +### Incremental selection + +| Key | Description | +| --- | --- | +| `` | Initialize/expand selection | +| `` | Expand to scope | +| `` | Shrink selection | + +### Textobject selection (`select.keymaps`) + +| Key | Target | +| --- | --- | +| `af` / `if` | Function outer / inner | +| `ac` / `ic` | Class outer / inner | +| `aa` / `ia` | Parameter outer / inner | +| `ai` / `ii` | Conditional outer / inner | +| `al` / `il` | Loop outer / inner | +| `a/` | Comment outer | + +### Textobject movement (`move` mappings) + +| Key | Action | +| --- | --- | +| `]f` / `]F` | Next function start / end | +| `[f` / `[F` | Previous function start / end | +| `]c` / `]C` | Next class start / end | +| `[c` / `[C` | Previous class start / end | +| `]a` / `]A` | Next parameter start / end | +| `[a` / `[A` | Previous parameter start / end | + +### Parameter swapping + +| Key | Description | +| --- | --- | +| `a` | Swap parameter with next | +| `A` | Swap parameter with previous | + +## `lua/plugins/comment.lua` + +| Mapping | Description | +| --- | --- | +| `gcc` | Toggle line comment | +| `gbc` | Toggle block comment | +| `gc` | Operator-pending line comment | +| `gb` | Operator-pending block comment | +| `gcO` / `gco` / `gcA` | Insert comment above / below / end-of-line | + +## `lua/plugins/surround.lua` + +| Mode | Mapping | Description | +| --- | --- | --- | +| normal | `ys{motion}{char}` | Add surround to motion | +| normal | `yss` | Surround current line | +| normal | `yS` | Surround motion with linewise behavior | +| normal | `ySS` | Surround current line linewise | +| insert | `s` | Surround following text object | +| insert | `S` | Surround current line | +| visual | `S` | Surround selection | +| visual line | `gS` | Surround visual-line selection | +| normal | `ds{char}` | Delete surround | +| normal | `cs{old}{new}` | Change surround | +| normal | `cS{old}{new}` | Change surround (linewise) | + +## `lua/plugins/cmp.lua` + +| Mode | Key | Description | +| --- | --- | --- | +| insert | `` | Manually trigger completion | +| insert | `` | Confirm selection (selects first item by default) | +| insert | `` | Next completion item | +| insert | `` | Previous completion item | +| insert | `` | Abort completion menu | + +## `lua/plugins/autopairs.lua` + +| Mode | Key | Description | +| --- | --- | --- | +| insert | `` | Fast wrap the previous text with a pair | + +## `lua/keymaps_reference.lua` + +| Command | Description | +| --- | --- | +| `:KeymapsGuide` | Open this reference in a floating window (read-only) | diff --git a/MIGRATION_PLAN.md b/MIGRATION_PLAN.md index 0d81e77..e85996d 100644 --- a/MIGRATION_PLAN.md +++ b/MIGRATION_PLAN.md @@ -480,7 +480,7 @@ Source of truth for the step-by-step rebuild. Keep this concise and up to date. - [ ] Verify linting (eslint_d, phpcs, markdownlint) ## Phase 12.6 — Final polish -- [ ] Review all keymaps and ensure they're documented +- [x] Review all keymaps and ensure they're documented (KEYMAPS.md + :KeymapsGuide) - [ ] Update README.md with final architecture and usage - [ ] Clean up any remaining debug code or temporary comments diff --git a/README.md b/README.md index da6bf23..c547b80 100644 --- a/README.md +++ b/README.md @@ -161,6 +161,7 @@ Record every decision here with a short rationale. Append new entries; do not re - **Validation**: Full config reload tested - all highlight groups load correctly - **Colorscheme integration**: Native Neovim colorscheme at `colors/paper-tonic-modern.lua` - **No overrides needed**: Modern implementation doesn't require separate override file +- 2025-12-12: Added `KEYMAPS.md` + `:KeymapsGuide` floating viewer to document every configured keymap (global + plugin-specific) grouped by source file. ## Project-Local Configuration (design) diff --git a/init.lua b/init.lua index dcda789..fdca763 100644 --- a/init.lua +++ b/init.lua @@ -8,6 +8,7 @@ require('netrw-config') require('keymaps') require('autocmds') require('abbreviations') +require('keymaps_reference') -- Bootstrap lazy.nvim local lazypath = vim.fn.stdpath('data') .. '/lazy/lazy.nvim' @@ -25,4 +26,3 @@ require('lazy').setup({ { import = 'plugins' }, }, }) - diff --git a/lua/keymaps_reference.lua b/lua/keymaps_reference.lua new file mode 100644 index 0000000..7255c4a --- /dev/null +++ b/lua/keymaps_reference.lua @@ -0,0 +1,74 @@ +local M = {} + +local reference_filename = "KEYMAPS.md" +local reference_path = vim.fn.stdpath("config") .. "/" .. reference_filename + +local function read_reference() + local lines = {} + local fd = io.open(reference_path, "r") + if not fd then + return { + ("Keymap reference file not found: %s"):format(reference_path), + "Create KEYMAPS.md to document mappings.", + } + end + + for line in fd:lines() do + table.insert(lines, line) + end + fd:close() + + if #lines == 0 then + lines = { "KEYMAPS.md is empty." } + end + + return lines +end + +local function open_float(lines) + local buf = vim.api.nvim_create_buf(false, true) + vim.api.nvim_buf_set_lines(buf, 0, -1, false, lines) + + vim.bo[buf].buftype = "nofile" + vim.bo[buf].bufhidden = "wipe" + vim.bo[buf].filetype = "markdown" + vim.bo[buf].swapfile = false + vim.bo[buf].modifiable = false + + local width = 0 + for _, line in ipairs(lines) do + width = math.max(width, vim.fn.strdisplaywidth(line)) + end + width = math.min(math.max(width + 4, 60), math.floor(vim.o.columns * 0.9)) + + local height = math.min(#lines, math.floor(vim.o.lines * 0.9)) + if height < 10 then + height = math.min(10, vim.o.lines - 2) + end + + local win_opts = { + relative = "editor", + width = width, + height = height, + row = math.floor((vim.o.lines - height) / 2), + col = math.floor((vim.o.columns - width) / 2), + style = "minimal", + border = "rounded", + } + + local win = vim.api.nvim_open_win(buf, true, win_opts) + vim.keymap.set("n", "q", "close", { buffer = buf, silent = true }) + vim.keymap.set("n", "", "close", { buffer = buf, silent = true }) + return win +end + +function M.open_reference() + local lines = read_reference() + open_float(lines) +end + +vim.api.nvim_create_user_command("KeymapsGuide", function() + M.open_reference() +end, { desc = "Show KEYMAPS.md in a floating window" }) + +return M