mirror
/
kickstart.nvim
mirror of https://github.com/nvim-lua/kickstart.nvim.git
1
0
Fork 1
Code Issues Packages Projects Releases Wiki Activity
kickstart.nvim/README.md

6.4 KiB
Raw Blame History

nvim

Personal Neovim config based on kickstart.nvim, tuned for backend-heavy work in JavaScript/TypeScript, C/C++, Kubernetes, and server development.

This README is the working manual for what is configured, why it exists, and how to use it quickly.

Design principles

  • Additive, not disruptive: new plugins and mappings are added without replacing existing behavior.
  • Modular plugin specs: each concern lives in lua/custom/plugins/*.lua.
  • Terminal-friendly workflow: most actions map to short leader sequences and preserve CLI-first habits.
  • Keep startup stable: major features are lazy-loaded by command, filetype, or explicit keymaps where possible.

Repository layout

  • init.lua: base options, core plugin setup, LSP, formatting, treesitter.
  • lua/custom/plugins/*.lua: modular plugin specs and custom behavior.
  • doc/nvim.txt: Vim help document (:help nvim-config).
  • lazy-lock.json: plugin lockfile managed by lazy.nvim.

Quick validation commands

Run these after config changes:

nvim --headless "+qa"
nvim --headless "+checkhealth" "+qa"
luac -p init.lua lua/custom/**/*.lua

Useful maintenance commands:

nvim --headless "+Lazy! sync" "+qa"
nvim --headless "+MasonToolsInstallSync" "+qa"

Keymap manual

Git workflow

  • <leader>gg: open Neogit UI
  • <leader>gd: open Diffview
  • <leader>gD: close Diffview
  • <leader>gf: Diffview file history (current file)
  • <leader>gF: Diffview repo history
  • <leader>h...: Gitsigns hunk actions (:which-key <leader>h)

Diagnostics and code navigation

  • <leader>xx: Trouble diagnostics
  • <leader>xw: Trouble workspace diagnostics
  • <leader>xd: Trouble current buffer diagnostics
  • <leader>xq: Trouble quickfix list
  • <leader>xl: Trouble location list
  • <leader>tc: toggle treesitter context header
  • <leader>jm / <leader>jk: next/previous function start
  • <leader>jM / <leader>jK: next/previous function end
  • <leader>jc / <leader>jC: next/previous class start
  • Textobject select (operator-pending/visual): af/if for function, ac/ic for class

Tests and debug

  • <leader>nr: neotest run nearest
  • <leader>nf: neotest run current file
  • <leader>ns: neotest run suite (cwd)
  • <leader>nd: neotest debug nearest via DAP
  • <leader>nn: neotest summary toggle
  • <leader>no: neotest output for nearest test
  • <leader>nO: neotest output panel toggle
  • <leader>na: attach to running neotest process
  • <leader>nS: stop neotest run

Existing DAP keys are unchanged:

  • <F5> continue/start, <F1> step into, <F2> step over, <F3> step out
  • <F7> toggle dap-ui, <leader>b toggle breakpoint, <leader>B conditional bp

Search, replace, and explorer

  • <leader>sR: project search/replace with grug-far
  • <leader>eo: open Oil explorer view (optional, non-default explorer)

CMake workflow (optional)

  • <leader>cg: CMake generate
  • <leader>cb: CMake build
  • <leader>cr: CMake run
  • <leader>ct: CMake test
  • <leader>cc: CMake select build type

Plugin stack by workflow

LSP and language intelligence

  • nvim-lspconfig + mason-lspconfig + mason-tool-installer
  • Vue integration:
    • vue_ls enabled
    • ts_ls scoped to vue with @vue/typescript-plugin
    • keeps typescript-tools.nvim available for TS/JS workflows
  • Kubernetes/Helm integration:
    • yamlls with schema mappings for Kubernetes, Helm chart, Helmfile, and Kustomize
    • helm_ls enabled
    • vim-helm added for Helm syntax support

Treesitter and structural editing

  • nvim-treesitter uses current API (require('nvim-treesitter').setup()).
  • nvim-treesitter-context provides sticky scope context.
  • nvim-treesitter-textobjects adds structure-aware function/class jumps.

Debugging

  • Core: nvim-dap, nvim-dap-ui, mason-nvim-dap, nvim-dap-go.
  • JS/TS: nvim-dap-vscode-js configured with js-debug-adapter and pwa-node launch/attach defaults.
  • C/C++: codelldb installation via Mason and baseline launch profile (Launch current file (codelldb)).

Testing

  • neotest core with adapters:
    • neotest-jest
    • neotest-vitest
    • neotest-gtest

Notes for C++ tests:

  • neotest-gtest needs executable mapping per project (use :ConfigureGtest from the neotest summary window).

Formatting and linting

  • Formatting via conform.nvim:
    • JS/TS/JSON/YAML: prettierd -> prettier
    • C/C++: clang_format
    • Lua: stylua
  • Linting via nvim-lint:
    • markdown: markdownlint
    • dockerfile: hadolint
    • yaml / yaml.helm-values: yamllint

Linting is executable-aware for configured linters to avoid noisy diagnostics when a linter binary is unavailable.

Project workflow plugins

  • trouble.nvim: focused diagnostics/issues panel
  • grug-far.nvim: project-wide search/replace
  • oil.nvim: optional file editing explorer (does not replace default explorer)
  • cmake-tools.nvim: CMake build/run/test helpers (lazy and optional)

Mason-managed tools and servers

This config ensures installation for key tools used by the workflows above, including:

  • prettierd, prettier, clang-format
  • hadolint, yamllint, markdownlint, stylua
  • js-debug-adapter, codelldb
  • configured LSP servers from servers table (including helm_ls)

Check with :Mason and install manually if needed.

Typical workflows

JS/TS service workflow

  1. Edit with LSP + treesitter context.
  2. Run nearest test with <leader>nr or file with <leader>nf.
  3. Debug test or code path with <leader>nd / <F5>.
  4. Use <leader>sR for safe project refactors.

C/C++ workflow

  1. Navigate symbols with <leader>jm/jk/jc/jC.
  2. Build/test with CMake mappings if project uses CMake.
  3. Debug using existing DAP keys and select Launch current file (codelldb).
  4. Run gtest via neotest after :ConfigureGtest setup.

Kubernetes/Helm workflow

  1. Edit manifests with yamlls schema-backed completion/validation.
  2. Edit charts/templates with Helm support (helm_ls, vim-helm).
  3. Use <leader>sR for scoped multi-file YAML refactors.

Troubleshooting

  • Verify startup: nvim --headless "+qa"
  • Verify health: nvim --headless "+checkhealth" "+qa"
  • Verify LSP clients in current buffer: :LspInfo
  • Verify formatter mapping: :ConformInfo
  • Verify Mason state: :Mason
  • Re-sync plugins: :Lazy sync

If a new feature appears missing, first confirm lazy-loading trigger (keymap/filetype/command) was actually used.

Help docs

This repo ships a Vim help file:

  • :help nvim-config
  • :help nvimn-config