From 30f0d55e60832e9172e565c8fb03b419515058f7 Mon Sep 17 00:00:00 2001 From: Tom van der Lee Date: Thu, 10 Sep 2026 22:30:45 +0200 Subject: Add README to the Neovim config Documents the file/folder layout, what each lua/plugins/*.lua group contains, the managed language servers, how to add a new plugin, and the (now fully independent) relationship to Vim's own vimrc. --- neovim/.config/nvim/README.md | 83 +++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 83 insertions(+) create mode 100644 neovim/.config/nvim/README.md (limited to 'neovim/.config') diff --git a/neovim/.config/nvim/README.md b/neovim/.config/nvim/README.md new file mode 100644 index 0000000..5092af0 --- /dev/null +++ b/neovim/.config/nvim/README.md @@ -0,0 +1,83 @@ +# Neovim config + +Standalone, Neovim-only Lua config — independent of `../../vim/.vim/vimrc` +(Vim's own config; it is not read by Neovim at all). Plugin manager is +[lazy.nvim](https://github.com/folke/lazy.nvim), which bootstraps itself on +first launch — no submodule needed. + +## Layout + +``` +init.lua Entry point: sets , then loads config/* in order +ftplugin/ + python.lua Per-filetype settings for *.py (tabstop/shiftwidth/etc.) +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 + 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) +lazy-lock.json Plugin versions pinned by lazy.nvim - commit changes + to this whenever plugins are added/updated +.gitignore Ignores spell/ (spellfile downloads) +``` + +`lua/config/*` and `lua/plugins/*` are auto-loaded: `init.lua` does +`require("config.lazy")`, which calls `require("lazy").setup("plugins", ...)` +— lazy.nvim automatically picks up every file under `lua/plugins/`, so a new +file dropped there just needs to `return { "author/repo", ... }` (or a list of +such tables) and it's included on next launch. + +## What's in `lua/plugins/` + +| 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 | +| `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 | +| `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 | +| `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 | + +## Language servers + +Managed by Mason, auto-installed via `lua/plugins/lsp.lua`'s +`ensure_installed`: `pyright`, `lua_ls`, `bashls`, `terraformls`, `yamlls`, +`ts_ls`, `cssls`, `html`. `clangd` is enabled separately (not +Mason-installed) since it already ships with Xcode Command Line Tools. + +Refactoring/navigation (rename, code actions, references, go-to-definition, +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. + +## Adding a new plugin + +Drop a new file in `lua/plugins/` (or add to an existing group file if it +belongs there) returning a lazy.nvim spec, e.g.: + +```lua +return { + "author/plugin-name", + opts = {}, +} +``` + +Restart Neovim (or `:Lazy sync`) to install it, then commit the updated +`lazy-lock.json` alongside your change. + +## Relationship to Vim + +Vim and Neovim used to share one `vimrc` (`has('nvim')` branches handled the +differences). They're now fully independent: Vim keeps `../../vim/.vim/vimrc` +with its own plugin manager (vim-plug) and completion (YouCompleteMe + +jedi-vim); nothing under this directory affects Vim, and nothing in +`vim/.vim` affects Neovim. -- cgit v1.3