neovim

Neovim Configuration Skill

A comprehensive guide for working with this modular, performance-optimized Neovim configuration built on lazy.nvim.

Quick Reference Metric Value Plugin Manager lazy.nvim Total Plugins 82 Target Startup <50ms Module Pattern M.setup() Leader Key Architecture Overview ~/.config/nvim/ ├── init.lua # Entry point ├── lua/ │ ├── config/ # Core configuration (11 modules) │ │ ├── lazy.lua # Plugin manager bootstrap │ │ ├── options.lua # Vim options │ │ ├── keymaps.lua # Key bindings │ │ ├── autocmds.lua # Autocommands │ │ └── performance.lua # Startup optimization │ ├── plugins/specs/ # Plugin specs (9 categories) │ │ ├── core.lua # Foundation (plenary, nui, devicons) │ │ ├── ui.lua # UI (lualine, bufferline, noice) │ │ ├── editor.lua # Editor (autopairs, flash, harpoon) │ │ ├── lsp.lua # LSP (lspconfig, mason, conform) │ │ ├── git.lua # Git (fugitive, gitsigns, diffview) │ │ ├── ai.lua # AI (copilot, ChatGPT) │ │ ├── debug.lua # DAP (nvim-dap, dap-ui) │ │ ├── tools.lua # Tools (telescope, neo-tree) │ │ └── treesitter.lua # Syntax (treesitter, textobjects) │ ├── kickstart/ # Kickstart-derived modules │ └── utils/ # Utility functions └── lazy-lock.json # Plugin version lock

Standard Module Pattern

All configuration modules follow the M.setup() pattern:

local M = {}

M.setup = function() -- Configuration logic here end

return M

Plugin Management (lazy.nvim) Adding a New Plugin

Add to the appropriate category file in lua/plugins/specs/:

-- lua/plugins/specs/tools.lua return { -- Existing plugins...

{ "author/plugin-name", event = "VeryLazy", -- Loading strategy dependencies = { "dep/name" }, -- Required plugins opts = { -- Plugin options }, config = function(_, opts) require("plugin-name").setup(opts) end, }, }

Loading Strategies Strategy When to Use Example lazy = true Default, load on demand Most plugins event = "VeryLazy" After UI loads UI enhancements event = "BufReadPre" When opening files Treesitter, gitsigns event = "InsertEnter" When typing Completion, autopairs cmd = "CommandName" On command invocation Heavy tools ft = "filetype" For specific filetypes Language plugins keys = {...} On keypress Motion plugins Plugin Commands Command Description :Lazy Open lazy.nvim dashboard :Lazy sync Update and install plugins :Lazy profile Show startup time analysis :Lazy clean Remove unused plugins :Lazy health Check plugin health LSP Configuration

See references/lsp.md for complete LSP reference.

LSP Stack mason.nvim (installer) ├── mason-lspconfig.nvim → nvim-lspconfig ├── mason-tool-installer.nvim (auto-install) └── mason-nvim-dap.nvim → nvim-dap

nvim-lspconfig ├── blink.cmp (completion) ├── conform.nvim (formatting) ├── nvim-lint (linting) └── trouble.nvim (diagnostics)

Adding an LSP Server -- In lua/plugins/specs/lsp.lua, add to mason-tool-installer list: ensure_installed = { "lua_ls", "pyright", "your_new_server", -- Add here }

-- Configure in lspconfig setup: servers = { your_new_server = { settings = { -- Server-specific settings }, }, }

LSP Keybindings Key Action gd Go to definition gr Go to references gI Go to implementation gD Go to declaration K Hover documentation rn Rename symbol ca Code action D Type definition ds Document symbols ws Workspace symbols Keybindings

See references/keybindings.md for complete reference.

Core Navigation Key Action Window navigation / Previous/next buffer sf Search files sg Search by grep Search buffers \ Toggle Neo-tree Adding Keybindings -- In lua/config/keymaps.lua M.setup(): vim.keymap.set('n', 'xx', function() -- Your action end, { desc = 'Description for which-key' })

-- Or in a plugin spec: keys = { { "xx", "Command", desc = "Description" }, }

Debugging (DAP)

See references/debugging.md for complete reference.

DAP Keybindings Key Action Continue/Start debugging Step over Step into Step out b Toggle breakpoint B Conditional breakpoint Adding a Debug Adapter -- In lua/plugins/specs/debug.lua local dap = require("dap")

dap.adapters.your_adapter = { type = "executable", command = "path/to/adapter", }

dap.configurations.your_filetype = { { type = "your_adapter", request = "launch", name = "Launch", program = "${file}", }, }

Performance Optimization Startup Optimization Layers Layer Technique Savings 1 vim.loader.enable() ~50ms 2 Skip vim._defaults ~180ms 3 Disable providers ~10ms 4 Disable builtins ~20ms 5 Deferred config ~30ms 6 Event-based loading Variable Profiling Startup :Lazy profile

Deferred Loading Pattern -- In init.lua vim.defer_fn(function() require('config.options').setup() require('config.keymaps').setup() require('config.autocmds').setup() end, 0)

Common Tasks Adding an Autocommand -- In lua/config/autocmds.lua M.setup(): vim.api.nvim_create_autocmd("FileType", { pattern = { "markdown", "text" }, callback = function() vim.opt_local.wrap = true vim.opt_local.spell = true end, })

Adding Vim Options -- In lua/config/options.lua M.setup(): vim.opt.your_option = value

Creating a Utility Function -- In lua/utils/init.lua local M = {}

M.your_function = function(args) -- Implementation end

return M

-- Usage: require('utils').your_function(args)

Plugin Categories Core (4 plugins)

plenary.nvim, nui.nvim, nvim-web-devicons, lazy.nvim

UI (11 plugins)

tokyonight, alpha-nvim, lualine, bufferline, noice, nvim-notify, which-key, indent-blankline, mini.indentscope, fidget, nvim-scrollbar

Editor (13 plugins)

nvim-autopairs, flash.nvim, clever-f, nvim-spectre, grug-far, harpoon, persistence, smartyank, vim-sleuth, vim-illuminate, tabular, todo-comments, toggleterm

LSP (12 plugins)

nvim-lspconfig, mason, mason-lspconfig, mason-tool-installer, lazydev, luvit-meta, SchemaStore, conform, nvim-lint, trouble, blink.cmp/nvim-cmp, LuaSnip

Git (7 plugins)

vim-fugitive, vim-rhubarb, gitsigns, diffview, vim-flog, git-conflict, octo

AI (3 plugins)

copilot.vim, ChatGPT.nvim, mcphub.nvim

Debug (8 plugins)

nvim-dap, nvim-dap-ui, nvim-dap-virtual-text, nvim-dap-python, nvim-dap-go, mason-nvim-dap, telescope-dap, nvim-nio

Tools (14 plugins)

telescope, telescope-fzf-native, telescope-ui-select, neo-tree, oil.nvim, nvim-bqf, rest.nvim, vim-dadbod, vim-dadbod-ui, vim-dadbod-completion, iron.nvim, markdown-preview, nvim-puppeteer, obsidian.nvim

Treesitter (3 plugins)

nvim-treesitter, nvim-treesitter-context, nvim-treesitter-textobjects

Troubleshooting Issue Solution Plugins not loading :Lazy sync LSP not starting :LspInfo, :Mason Icons missing Install a Nerd Font Slow startup :Lazy profile Treesitter errors :TSUpdate Keybinding conflicts :verbose map Health Check :checkhealth

Debug Logging -- Temporarily add to plugin config: log_level = vim.log.levels.DEBUG,

Resources lazy.nvim Mason.nvim Neovim Documentation Kickstart.nvim References references/configuration.md - Core configuration options references/plugins.md - All 82 plugins detailed references/plugin-deepdives.md - In-depth plugin guides references/lsp.md - LSP server configuration references/keybindings.md - Complete keybinding reference references/debugging.md - DAP debugging guide references/performance.md - Optimization techniques references/tools.md - CLI tools, utilities, and workflows references/troubleshooting.md - Common issues and solutions references/migration-0.11.md - Neovim 0.11 migration guide