tenseleyflow/ndotfiles / 76a2ea1

+# Neovim Modern Workflow & Plugin Guide

+

+This guide extends the default Neovim keybinds with **modern workflows** (LSP, Telescope, Treesitter, Git, terminals) for Neovim ≥ 0.8. Designed for productivity on Wayland/Hyprland with lazy.nvim config.

+

+---

+

+## Modes Overview

+

+| Mode            | Description                                   | Enter From            |

+|-----------------|-----------------------------------------------|-----------------------|

+| **Normal**      | Navigation, commands                         | `Esc`                 |

+| **Insert**      | Insert/typing                                | `i`, `a`, `o`, `O`    |

+| **Visual**      | Select text (char, line, block)              | `v`, `V`, `Ctrl+v`    |

+| **Command**     | Ex commands (`:w`, `:q`)                     | `:`                   |

+| **Terminal**    | Interactive terminal buffer                  | `:term`, `<C-`>`      |

+

+---

+

+## Navigation Keybindings (Default)

+

+| Keybind    | Action                               |

+|------------|--------------------------------------|

+| `h`/`l`    | Left / right one character           |

+| `j`/`k`    | Down / up one line                   |

+| `w`/`e`/`b`| Next word / end word / back a word   |

+| `0` / `$`  | Start / end of line                  |

+| `gg` / `G` | First / last line of file            |

+| `{n}G`     | Jump to line n                       |

+| `Ctrl+u/d` | Scroll half screen up/down           |

+| `Ctrl+b/f` | Scroll full screen up/down           |

+| `%`        | Match brackets/parentheses           |

+| `/text`    | Search forward (n/N = next/prev)     |

+| `?text`    | Search backward (n/N = next/prev)    |

+| `*` / `#`  | Next/prev word under cursor          |

+

+---

+

+## Editing Essentials

+

+| Keybind | Action                                   |

+|---------|------------------------------------------|

+| `i`/`a` | Insert before / after cursor             |

+| `o`/`O` | New line below / above                   |

+| `x`     | Delete character                         |

+| `dd`    | Delete line                              |

+| `yy`    | Yank (copy) line                         |

+| `p`/`P` | Paste after / before cursor              |

+| `.`     | Repeat last command                      |

+| `{n}{op}` | Repeat operation n times (`5dd`)       |

+

+### Visual Mode Tricks

+- `v`/`V`/`Ctrl+v` → char/line/block selections

+- Block mode (`Ctrl+v` + `j/k`):

+  - `I` insert before selection (applies to all lines)

+  - `A` append after selection

+

+---

+

+## Custom Workflow Keymaps (from lazy config)

+

+| Keybind     | Action                              |

+|-------------|-------------------------------------|

+| `<C-s>`     | Save (normal/insert/visual)         |

+| `<leader>q` | Quit                                |

+| `<leader>sv`| Vertical split                      |

+| `<leader>sh`| Horizontal split                    |

+| `<leader>to`| New tab                             |

+| `<leader>ff`| Telescope: find files               |

+| `<leader>fg`| Telescope: live grep                |

+| `<leader>fb`| Telescope: buffers                  |

+| `<leader>fh`| Telescope: help tags                |

+| `-`         | Oil file manager float              |

+| `<C-`>`     | Toggle floating terminal            |

+| `<leader>tr`| Run task (Overseer)                 |

+| `<leader>tt`| Task list toggle                    |

+| `<leader>f` | Format buffer/file (Conform)        |

+

+---

+

+## LSP Workflow (Language Server Protocol)

+

+Requires `mason.nvim` + `nvim-lspconfig`.

+

+| Keybind     | Action                               |

+|-------------|--------------------------------------|

+| `gd`        | Goto definition                      |

+| `gD`        | Goto declaration                     |

+| `gi`        | Goto implementation                  |

+| `gr`        | List references                      |

+| `K`         | Hover docs                           |

+| `<leader>rn`| Rename symbol                        |

+| `<leader>ca`| Code action                          |

+| `<leader>fd`| Format buffer (LSP/formatter)        |

+

+---

+

+## Git Integration

+

+- **Gitsigns.nvim**  

+  - Shows inline git diff signs, hunk navigation (`]c` / `[c`), staging hunks (`:Gitsigns stage_hunk`).

+

+- **LazyGit.nvim**  

+  - `:LazyGit` launches interactive TUI for Git inside Neovim.

+

+---

+

+## Telescope (Fuzzy Finder)

+

+- `<leader>ff` → Files

+- `<leader>fg` → Live grep

+- `<leader>fb` → Buffers

+- `<leader>fh` → Help tags

+

+Extra: type `/` inside Telescope for fuzzy-in-list filtering.

+

+---

+

+## Treesitter (Syntax Engine)

+

+- Auto-installs parsers for `bash`, `c/cpp`, `lua`, `python`, `rust`, `json`, `yaml`, `toml`, `html/css/js/ts`, `markdown`, `fish`, **fortran**.

+- Provides better highlighting + indenting.

+

+---

+

+## Formatting (Conform.nvim)

+

+| Language     | Formatter(s)                         |

+|--------------|--------------------------------------|

+| Lua          | stylua                               |

+| Python       | ruff_format, black                   |

+| Shell/Fish   | shfmt, fish_indent                   |

+| C/C++        | clang-format                         |

+| JS/TS/HTML   | prettier                             |

+| JSON/YAML    | jq / prettier                        |

+| TOML         | taplo                                |

+| Markdown     | prettier                             |

+| Fortran      | fprettify                            |

+

+---

+

+## Debugging (nvim-dap + dap-ui)

+

+- `:DapToggleBreakpoint` → set/clear breakpoint

+- `:DapContinue` → run/start

+- `:DapStepOver` / `:DapStepInto` / `:DapStepOut`

+- DAP UI auto-opens on session start.

+

+---

+

+## Bonus: Multi-Cursor

+

+- Native block selections: `Ctrl+v` + `I`/`A`

+- True multi-cursor: install **vim-visual-multi**

+  - `Ctrl+n` → add cursor to next occurrence

+  - `Ctrl+p` → add cursor to prev

+  - `Ctrl+x` → skip

+

+---

+

+## Quick Efficiency Tips

+- Use `.` to repeat edits, `:noh` to clear highlights

+- Combine motions: `d2w` (delete 2 words), `c$` (change to end of line)

+- Use **Overseer** for project build/run/test integration

+- Map `-` (Oil) for directory browsing like a mini file manager

+- Use `<C-`>` as a popup shell without leaving Neovim

+- Keep `<leader>` easy (`<Space>` in this config) for speed

+

+---

+-- smooth editing, LSP, Treesitter, Telescope, formatting, Git, terminals, and a few QoL boosts.

+

+---------------------------------------------------------------

+-- 0) Bootstrap lazy.nvim (plugin manager)

+---------------------------------------------------------------

+local lazypath = vim.fn.stdpath("data") .. "/lazy/lazy.nvim"

+if not vim.loop.fs_stat(lazypath) then

+  vim.fn.system({

+    "git", "clone", "--filter=blob:none",

+    "https://github.com/folke/lazy.nvim.git", "--branch=stable", lazypath,

+  })

+end

+vim.opt.rtp:prepend(lazypath)

+

+---------------------------------------------------------------

+-- 1) Core settings (Wayland-safe clipboard, sensible defaults)

+---------------------------------------------------------------

+vim.g.mapleader = " "

+vim.g.maplocalleader = ","

+

+local opt = vim.opt

+opt.number = true

+opt.relativenumber = true

+opt.signcolumn = "yes"

+opt.termguicolors = true

+opt.cursorline = true

+opt.wrap = false

+opt.scrolloff = 5

+opt.sidescrolloff = 8

+opt.expandtab = true

+opt.shiftwidth = 2

+opt.tabstop = 2

+opt.smartindent = true

+opt.ignorecase = true

+opt.smartcase = true

+opt.incsearch = true

+opt.splitbelow = true

+opt.splitright = true

+opt.updatetime = 300

+opt.timeoutlen = 400

+opt.undofile = true

+opt.clipboard = "unnamedplus"   -- uses wl-clipboard on Wayland if installed

+

+---------------------------------------------------------------

+-- 2) Plugins via lazy.nvim

+---------------------------------------------------------------

+require("lazy").setup({

+  -- UI + UX ---------------------------------------------------

+  { "folke/tokyonight.nvim", lazy = false, priority = 1000, opts = { style = "night" } },

+  { "nvim-lualine/lualine.nvim", dependencies = { "nvim-tree/nvim-web-devicons" },

+    opts = { options = { theme = "auto", globalstatus = true } } },

+  { "folke/which-key.nvim", event = "VeryLazy", opts = {} },

+  { "stevearc/dressing.nvim", event = "VeryLazy", opts = {} },

+  { "rcarriga/nvim-notify", opts = { timeout = 2000 } },

+  { "folke/noice.nvim", event = "VeryLazy", dependencies = { "MunifTanjim/nui.nvim", "rcarriga/nvim-notify" },

+    opts = { presets = { command_palette = true, long_message_to_split = true } } },

+  { "lukas-reineke/indent-blankline.nvim", main = "ibl", opts = {} },

+  { "numToStr/Comment.nvim", opts = {} },

+  { "kylechui/nvim-surround", event = "VeryLazy", opts = {} },

+

+  -- Files, search, projects ----------------------------------

+  { "nvim-telescope/telescope.nvim", dependencies = { "nvim-lua/plenary.nvim" } },

+  { "nvim-telescope/telescope-fzf-native.nvim", build = "make", cond = function() return vim.fn.executable("make") == 1 end },

+  { "ahmedkhalf/project.nvim", opts = { detection_methods = { "pattern", "lsp" }, patterns = { ".git", "pyproject.toml", "package.json", "Makefile" } } },

+  { "stevearc/oil.nvim", opts = { view_options = { show_hidden = true } } },

+

+  -- Git -------------------------------------------------------

+  { "lewis6991/gitsigns.nvim", opts = {} },

+  { "kdheepak/lazygit.nvim", cmd = { "LazyGit" } },

+

+  -- Terminal & task runner -----------------------------------

+  { "akinsho/toggleterm.nvim", version = "*", opts = { open_mapping = [[<C-`>]], direction = "float" } },

+  { "stevearc/overseer.nvim", opts = {} },

+

+  -- Treesitter ------------------------------------------------

+  { "nvim-treesitter/nvim-treesitter", build = ":TSUpdate", opts = {

+      ensure_installed = {

+        "bash", "c", "cpp", "lua", "python", "rust", "json", "yaml", "toml",

+        "html", "css", "javascript", "typescript", "markdown", "markdown_inline",

+        "make", "fish", "fortran"

+      },

+      highlight = { enable = true },

+      indent = { enable = true },

+    }

+  },

+

+  -- LSP, format, lint ----------------------------------------

+  { "williamboman/mason.nvim", opts = { ui = { border = "rounded" } } },

+  { "williamboman/mason-lspconfig.nvim" },

+  { "neovim/nvim-lspconfig" },

+  { "stevearc/conform.nvim", opts = {

+      notify_on_error = false,

+      format_on_save = function(buf)

+        -- Disable on big files

+        local ok, stats = pcall(vim.loop.fs_stat, vim.api.nvim_buf_get_name(buf))

+        if ok and stats and stats.size > 512 * 1024 then return end

+        return { timeout_ms = 2000, lsp_fallback = true }

+      end,

+      formatters_by_ft = {

+        lua = { "stylua" },

+        python = { "ruff_format", "black" },

+        sh = { "shfmt" }, bash = { "shfmt" }, zsh = { "shfmt" }, fish = { "fish_indent" },

+        c = { "clang_format" }, cpp = { "clang_format" },

+        javascript = { "prettier" }, typescript = { "prettier" },

+        json = { "jq", "prettier" }, yaml = { "prettier" }, toml = { "taplo" },

+        html = { "prettier" }, css = { "prettier" }, markdown = { "prettier" },

+        fortran = { "fprettify" },

+      },

+    }

+  },

+

+  -- Debugging (optional, light defaults) ---------------------

+  { "mfussenegger/nvim-dap" },

+  { "rcarriga/nvim-dap-ui", dependencies = { "mfussenegger/nvim-dap" } },

+}, {

+  install = { colorscheme = { "tokyonight" } },

+  change_detection = { notify = false },

+})

+

+---------------------------------------------------------------

+-- 3) Post-plugin config (LSP, Telescope, keymaps, etc.)

+---------------------------------------------------------------

+-- Colorscheme

+vim.cmd.colorscheme("tokyonight")

+

+-- Lualine

+require("lualine").setup({})

+

+-- Telescope

+local telescope = require("telescope")

+telescope.setup({ defaults = { mappings = { i = { ["<C-j>"] = "move_selection_next", ["<C-k>"] = "move_selection_previous" } } } })

+pcall(telescope.load_extension, "fzf")

+

+-- Oil: simple file manager toggle

+vim.keymap.set("n", "-", function() require("oil").toggle_float() end, { desc = "Oil file manager" })

+

+-- ToggleTerm: float terminal with <C-`>

+-- (Already mapped via opts. Add extra terminals if desired.)

+

+-- Overseer: tasks (build, run, test)

+vim.keymap.set("n", "<leader>tt", ":OverseerToggle<CR>", { desc = "Toggle task list" })

+vim.keymap.set("n", "<leader>tr", ":OverseerRun<CR>",    { desc = "Run a task" })

+

+-- Gitsigns

+require("gitsigns").setup()

+

+-- Treesitter

+require("nvim-treesitter.configs").setup({})

+

+-- Mason + LSPConfig

+require("mason").setup()

+local mlsp = require("mason-lspconfig")

+mlsp.setup({ ensure_installed = {

+  "pyright", "ruff_lsp", "lua_ls", "clangd", "rust_analyzer", "bashls",

+  "jsonls", "yamlls", "html", "cssls", "ts_ls", "marksman", "taplo", "fortls"

+}})

+

+local lspconfig = require("lspconfig")

+local capabilities = vim.lsp.protocol.make_client_capabilities()

+local ok_cmp, cmp_lsp = pcall(require, "cmp_nvim_lsp")

+if ok_cmp then capabilities = cmp_lsp.default_capabilities(capabilities) end

+

+-- Pretty borders

+local handlers = {

+  ["textDocument/hover"] = vim.lsp.with(vim.lsp.handlers.hover, { border = "rounded" }),

+  ["textDocument/signatureHelp"] = vim.lsp.with(vim.lsp.handlers.signature_help, { border = "rounded" }),

+}

+

+-- on_attach: buffer-local mappings

+local on_attach = function(_, bufnr)

+  local nmap = function(keys, func, desc)

+    vim.keymap.set("n", keys, func, { buffer = bufnr, desc = desc })

+  end

+  nmap("gd", vim.lsp.buf.definition, "Goto Definition")

+  nmap("gr", vim.lsp.buf.references, "References")

+  nmap("gD", vim.lsp.buf.declaration, "Goto Declaration")

+  nmap("gi", vim.lsp.buf.implementation, "Goto Implementation")

+  nmap("K",  vim.lsp.buf.hover, "Hover")

+  nmap("<leader>rn", vim.lsp.buf.rename, "Rename symbol")

+  nmap("<leader>ca", vim.lsp.buf.code_action, "Code Action")

+  nmap("<leader>fd", function() vim.lsp.buf.format({ async = true }) end, "Format buffer")

+end

+

+mlsp.setup_handlers({ function(server)

+  lspconfig[server].setup({ capabilities = capabilities, on_attach = on_attach, handlers = handlers })

+end })

+

+-- Lua LS: tuned for Neovim config dev

+lspconfig.lua_ls.setup({

+  capabilities = capabilities,

+  on_attach = on_attach,

+  settings = { Lua = { diagnostics = { globals = { "vim" } }, workspace = { checkThirdParty = false } } }

+})

+

+-- Ruff: prefer as linter + fixer with Pyright for types

+lspconfig.ruff_lsp.setup({ capabilities = capabilities, on_attach = on_attach })

+

+-- DAP minimal sugar

+local dap_ok, dapui = pcall(require, "dapui")

+if dap_ok then

+  dapui.setup()

+  local dap = require("dap")

+  dap.listeners.after.event_initialized["dapui_config"] = function() dapui.open() end

+  dap.listeners.before.event_terminated["dapui_config"] = function() dapui.close() end

+  dap.listeners.before.event_exited["dapui_config"]      = function() dapui.close() end

+end

+

+---------------------------------------------------------------

+-- 4) Keymaps you’ll actually use (and remember)

+---------------------------------------------------------------

+local map = vim.keymap.set

+-- Save, quit

+map({"n","i","v"}, "<C-s>", function() vim.cmd("silent w") end, { desc = "Save" })

+map("n", "<leader>q", ":q<CR>", { desc = "Quit" })

+

+-- Windows and tabs

+map("n", "<leader>sv", ":vsplit<CR>", { desc = "Split vertical" })

+map("n", "<leader>sh", ":split<CR>",  { desc = "Split horizontal" })

+map("n", "<leader>to", ":tabnew<CR>",  { desc = "New tab" })

+

+-- Telescope

+map("n", "<leader>ff", function() require("telescope.builtin").find_files() end, { desc = "Find files" })

+map("n", "<leader>fg", function() require("telescope.builtin").live_grep()  end, { desc = "Live grep" })

+map("n", "<leader>fb", function() require("telescope.builtin").buffers()    end, { desc = "Buffers" })

+map("n", "<leader>fh", function() require("telescope.builtin").help_tags()  end, { desc = "Help tags" })

+

+-- Move lines (visual)

+map("v", "J", ":m '>+1<CR>gv=gv")

+map("v", "K", ":m '<-2<CR>gv=gv")

+

+-- Clear search

+map("n", "<Esc>", ":noh<CR>", { silent = true })

+

+-- Format

+map("n", "<leader>f", function() require("conform").format({ lsp_fallback = true }) end, { desc = "Format file" })

+

+---------------------------------------------------------------

+-- 5) Small QoL autocommands

+---------------------------------------------------------------

+-- Restore cursor to last position

+vim.api.nvim_create_autocmd("BufReadPost", {

+  callback = function()

+    local mark = vim.api.nvim_buf_get_mark(0, '"')

+    local lcount = vim.api.nvim_buf_line_count(0)

+    if mark[1] > 0 and mark[1] <= lcount then

+      pcall(vim.api.nvim_win_set_cursor, 0, mark)

+    end

+  end

+})

+

+-- Highlight on yank

+vim.api.nvim_create_autocmd("TextYankPost", {

+  callback = function() vim.highlight.on_yank({ higroup = "IncSearch", timeout = 120 }) end

+})

+

+-- Wayland clipboard fix hint (if clipboard missing)

+if vim.env.WAYLAND_DISPLAY and vim.o.clipboard ~= "unnamedplus" then

+  vim.notify("Tip: install 'wl-clipboard' and set clipboard=unnamedplus for system clipboard.", vim.log.levels.INFO)

+end

+

+---------------------------------------------------------------

+-- 6) Add language tools via Mason: :Mason

+--    Choose servers/formatters: pyright, ruff, lua_ls, clangd, rust_analyzer, bashls,

+--    jsonls, yamlls, html, cssls, tsserver/ts_ls, marksman, taplo, fortls, etc.

+--    Then enjoy: <leader>ff (files), <leader>fg (grep), <C-`> (terminal), - (Oil),

+--    <leader>f (format), gd/gr/K, and :OverseerRun for project tasks.

+---------------------------------------------------------------