From a5e8bbeb9d79d905a193e95a39acd29bc37e6c66 Mon Sep 17 00:00:00 2001 From: Tom van der Lee Date: Wed, 16 Sep 2026 08:47:13 +0200 Subject: Updated dotfiles --- neovim/.config/nvim/README.md | 135 ++++++++++++++++++++++++++++++++++++++++-- 1 file changed, 130 insertions(+), 5 deletions(-) (limited to 'neovim/.config/nvim/README.md') diff --git a/neovim/.config/nvim/README.md b/neovim/.config/nvim/README.md index 5092af0..0e50788 100644 --- a/neovim/.config/nvim/README.md +++ b/neovim/.config/nvim/README.md @@ -15,6 +15,8 @@ lua/config/ Everything that isn't a plugin declaration options.lua vim.opt settings (search, undo, whitespace display, ...) keymaps.lua Global keymaps not owned by a specific plugin autocmds.lua Global autocmds not owned by a specific plugin + project_run.lua Helper for project-local run/debug configs (see below) + dap_node.lua Node/js-debug-adapter wiring for nvim-dap (see below) lazy.lua Bootstraps lazy.nvim and points it at lua/plugins/ lua/plugins/ One file per plugin (or small plugin group), each returning a lazy.nvim plugin spec (or list of specs) @@ -34,18 +36,23 @@ such tables) and it's included on next launch. | File | Plugin(s) | Purpose | |---|---|---| | `colorscheme.lua` | vim-janah | Color scheme, falls back to `desert` if it fails to load | -| `statusline.lua` | vim-airline, vim-airline-themes, tmuxline.vim | Status/tab line | +| `statusline.lua` | lualine.nvim | Status line | | `filetree.lua` | neo-tree.nvim | File explorer sidebar with git-status colors (`e` to toggle) | -| `fuzzyfinder.lua` | ctrlp.vim | Fuzzy file finder (ripgrep-backed if `rg` is on PATH) | -| `editing.lua` | nerdcommenter, quick-scope | Comment toggling, `f`/`F`/`t`/`T` target highlighting | -| `git.lua` | vim-fugitive, vim-signify | `:Git` commands, git-diff gutter signs | +| `fuzzyfinder.lua` | telescope.nvim, telescope-ui-select.nvim | Fuzzy file finder (``), live grep (`fg`), buffers (`fb`); also overrides `vim.ui.select` globally so overseer's/dap's pickers are Telescope windows | +| `editing.lua` | quick-scope | `f`/`F`/`t`/`T` target highlighting (comment toggling is Neovim's built-in `gc`/`gcc`) | +| `git.lua` | vim-fugitive, gitsigns.nvim | `:Git` commands, git-diff gutter signs | | `ale.lua` | ALE | Linters/fixers only — `g:ale_disable_lsp = 1` so it doesn't fight the LSP client's diagnostics/hover/go-to-def | -| `langs.lua` | vim-ansible-yaml, vim-terraform | Only loaded if `ansible`/`terraform` is on PATH (lazy.nvim `cond`) | | `claude-code.lua` | claude-code.nvim (+ plenary.nvim) | `:ClaudeCode` and friends | +| `toggleterm.lua` | toggleterm.nvim | Scratch terminal toggle — ``, vertical split on the right matching claude-code.nvim's placement/ratio | | `treesitter.lua` | nvim-treesitter (`main` branch) | Parser installs + syntax highlighting | | `autopairs.lua` | nvim-autopairs, nvim-ts-autotag | Auto-close brackets/quotes/HTML+JSX tags | | `completion.lua` | blink.cmp (+ friendly-snippets) | Completion popup, Tab-to-accept (`super-tab` preset) | | `lsp.lua` | nvim-lspconfig, mason.nvim, mason-lspconfig.nvim | Installs & enables language servers, wires blink.cmp's capabilities into them | +| `dap.lua` | nvim-dap, nvim-dap-ui, nvim-dap-virtual-text, mason-nvim-dap.nvim | Debugger core + UI, installs debug adapters via Mason (`d*`) | +| `dap-python.lua` | nvim-dap-python | Python launch configs, wired to Mason's debugpy install | +| `overseer.lua` | overseer.nvim | Save/run/rerun arbitrary run configurations for any language (`r*`) | +| `which-key.lua` | which-key.nvim | Keymap discoverability popup; labels the `d`/`r`/etc. groups | +| `indent-detect.lua` | guess-indent.nvim | Detects each buffer's real indentation and matches shiftwidth/tabstop to it | ## Language servers @@ -59,6 +66,112 @@ hover) come from Neovim's built-in default LSP keymaps (`:help lsp-defaults`) once a server attaches — `grn`, `gra`, `grr`, `gri`, `gO`, `K`, ``. No extra plugin or keymap needed for these. +## Debugging + +Python and Node.js (JavaScript/TypeScript), via `nvim-dap` + `nvim-dap-ui`. +The `debugpy` and `js-debug-adapter` adapters are installed and kept up to +date by Mason (via `mason-nvim-dap.nvim`, the DAP equivalent of +`mason-lspconfig.nvim`), so `:Mason` shows them alongside the language +servers. Keymaps live under `d` — `db` to set a breakpoint, +`dc` to start/continue (picks a registered config from any window, +not just the source buffer; resumes in place if a session is already stopped +at a breakpoint), `do`/`di`/`dO` to step over/into/out, `dt` +to terminate, `du` to reopen the UI if you close it manually (it +opens/closes itself automatically around a session). Press `d` and +wait to see the full list via which-key. + +Python's adapter/config setup lives in `lua/plugins/dap-python.lua`, wrapping +the `nvim-dap-python` plugin. Node's lives in `lua/config/dap_node.lua` +instead — there's no maintained `nvim-dap-python`-style plugin for it (the +community option, `nvim-dap-vscode-js`, expects an older, manually-built +vscode-js-debug layout that doesn't match what Mason's `js-debug-adapter` +package installs), so that file resolves the Mason install path directly and +registers the `pwa-node` adapter + default `javascript`/`typescript`/ +`javascriptreact`/`typescriptreact` configs itself. It's called eagerly from +`dap.lua`'s own `config()` rather than being its own `lua/plugins/*` entry, +since it isn't an installable plugin — same reasoning as +`lua/config/project_run.lua`. + +Adding another language later (e.g. C/C++ via `codelldb`) means adding its +adapter to `dap.lua`'s `ensure_installed`, and either writing its own +`dap-.lua` plugin file (if a wrapper plugin exists, following the +`dap-python.lua` pattern) or a `lua/config/dap_.lua` module called +from `dap.lua`'s `config()` (if not, following the `dap_node.lua` pattern) — +including `lazy = false` on `dap.lua` itself either way, so the adapter is +registered from startup rather than only after a buffer of that filetype is +opened (the `dc` picker works from any window, so it can't rely on +that to lazy-trigger the adapter). + +`overseer.lua` sets `dap = true`, which patches `nvim-dap` so a debug +configuration can set `preLaunchTask`/`postDebugTask` to the name of an +overseer task (or `"${defaultBuildTask}"` for whichever task is tagged +`BUILD`) — useful for "build, then debug" workflows once a compiled +language is added; not needed for plain Python/Node scripts. + +## Run configurations + +`overseer.nvim` provides PyCharm-style saved/rerunnable run configurations +for any language or toolchain (shell commands, npm scripts, make, cargo, +python scripts, ...) — it isn't tied to LSP/DAP language support. Keymaps +live under `r` — `rr` to run a task (prompts for a template +or a raw command), `rl` to rerun the last task, `ro` to +toggle the task list/output window, `rq` for quick actions +(restart/stop/dispose) on a selected task. Press `r` and wait to see +the full list via which-key. + +`overseer.lua`'s `component_aliases.default` adds the `open_output` +component (`on_start = "always"`, `focus = false`) on top of overseer's own +defaults, so starting *any* task — custom, `.nvim.lua`-declared, or +auto-detected (npm/make/etc.) — docks its output automatically instead of +running silently until you manually `ro`. + +## Project-local run/debug configs + +A project can drop a `.nvim.lua` anywhere in its directory tree and have it +auto-sourced (after a one-time `:help :trust` prompt — it runs arbitrary +Lua, so trust it deliberately, not reflexively). This is the PyCharm-style +"named configuration" mechanism, without adopting any other editor's file +format. + +This is **not** core Vim/Neovim `'exrc'` (deliberately left off in +options.lua) — `exrc` only checks the literal cwd once at startup, so it +misses a project's `.nvim.lua` whenever Neovim didn't happen to start with +cwd exactly there. Instead, an autocmd in `lua/config/autocmds.lua` searches +*upward* from cwd on `VimEnter`/`DirChanged` (stopping at `$HOME`, same +nearest-ancestor pattern LSP root-dir detection uses) and reads the file via +`vim.secure.read` — the same trust mechanism `exrc` itself uses, so `:trust` +still manages the allowlist unchanged, it's just found reliably regardless +of how you opened Neovim. + +`lua/config/project_run.lua` gives that file one call per config that +registers both a `rr` run task and a matching `dc` debug +config from the *same* declaration, instead of repeating the command across +two separate files: + +```lua +-- /.nvim.lua +require("config.project_run").python({ + name = "Run app", + program = vim.fn.getcwd() .. "/main.py", + args = { "--flag" }, -- optional, shared by both run and debug +}) + +require("config.project_run").node({ + name = "Run app", + program = vim.fn.getcwd() .. "/index.js", -- or npmScript = "dev" for `npm run dev` + args = { "--flag" }, -- optional, shared by both run and debug +}) +``` + +`dap.lua` and `overseer.lua` are both `lazy = false` specifically so this +works immediately when the autocmd sources the file, rather than needing +the plugins already triggered by a keymap first. + +(`nvim-dap` and `overseer.nvim` also natively read `.vscode/launch.json` and +`.vscode/tasks.json` respectively, if you'd rather use that ecosystem's +format for some reason — but `project_run.lua` is the recommended path here +since it states each command once.) + ## Adding a new plugin Drop a new file in `lua/plugins/` (or add to an existing group file if it @@ -74,6 +187,18 @@ return { Restart Neovim (or `:Lazy sync`) to install it, then commit the updated `lazy-lock.json` alongside your change. +If a plugin backs a keymap or command meant to work from any window — not +scoped to a particular filetype/buffer, like the run/debug pickers, the +fuzzy finder, or the file explorer — set `lazy = false` rather than gating +it behind `ft`/`event`, even though lazy.nvim would otherwise recommend one. +A trigger tied to "some buffer of type X was opened" silently breaks the +moment the keymap fires before that's happened (this bit `dap-python.lua`: +it lazy-loaded on `ft = "python"`, so debugging broke whenever `dc` +was pressed before any `.py` buffer had been opened this session). Plain +per-buffer editing conveniences (`autopairs.lua`'s `InsertEnter`, +`ale.lua`'s `BufReadPre`, `which-key.lua`'s `VeryLazy`) don't have this +problem and can stay lazy. + ## Relationship to Vim Vim and Neovim used to share one `vimrc` (`has('nvim')` branches handled the -- cgit v1.3