Split into sections

README.md

@@ -113,7 +113,8 @@ nvim
 
 That's it! `vim.pack` will install all the plugins from your config. Use
 `:lua vim.pack.update(nil, { offline = true })` to inspect plugin state and
-`:lua vim.pack.update()` to fetch updates.
+`:lua vim.pack.update()` to fetch updates (`:write` applies updates, `:quit`
+cancels them).
 
 #### Read The Friendly Documentation
 
@@ -169,17 +170,36 @@ After installing all the dependencies continue with the [Install Kickstart](#ins
 #### Windows Installation
 
 <details><summary>Windows with Microsoft C++ Build Tools and CMake</summary>
-Installation may require installing build tools and updating the run command for `telescope-fzf-native`
+Kickstart's default config is make-only for `telescope-fzf-native.nvim`.
+If `make` is unavailable, the plugin is skipped.
 
-See `telescope-fzf-native` documentation for [more details](https://github.com/nvim-telescope/telescope-fzf-native.nvim#installation)
+Recommended: install `make` (see the chocolatey section below).
 
-This requires:
+If you want a CMake-only setup, customize `init.lua` in two places:
 
-- Install CMake and the Microsoft C++ Build Tools on Windows
+1. Include `telescope-fzf-native.nvim` when `cmake` is available:
 
 ```lua
-{'nvim-telescope/telescope-fzf-native.nvim', build = 'cmake -S. -Bbuild -DCMAKE_BUILD_TYPE=Release && cmake --build build --config Release && cmake --install build --prefix build' }
+if vim.fn.executable 'make' == 1 or vim.fn.executable 'cmake' == 1 then
+  table.insert(plugins, gh 'nvim-telescope/telescope-fzf-native.nvim')
+end
 ```
+
+2. In the `PackChanged` hook, use CMake when `make` is unavailable:
+
+```lua
+if name == 'telescope-fzf-native.nvim' then
+  if vim.fn.executable 'make' == 1 then
+    run_build(name, { 'make' }, ev.data.path)
+  elseif vim.fn.executable 'cmake' == 1 then
+    run_build(name, { 'cmake', '-S.', '-Bbuild', '-DCMAKE_BUILD_TYPE=Release' }, ev.data.path)
+    run_build(name, { 'cmake', '--build', 'build', '--config', 'Release', '--target', 'install' }, ev.data.path)
+  end
+  return
+end
+```
+
+See `telescope-fzf-native` documentation for [build details](https://github.com/nvim-telescope/telescope-fzf-native.nvim#installation).
 </details>
 <details><summary>Windows with gcc/make using chocolatey</summary>
 Alternatively, one can install gcc and make which don't require changing the config,

init.lua

@@ -84,7 +84,12 @@ I hope you enjoy your Neovim journey,
 P.S. You can delete this when you're done too. It's your config now! :)
 --]]
 
--- Enables faster startup time by caching your compiled Lua modules.
+-- ============================================================
+-- SECTION 1: FOUNDATION
+-- Core Neovim settings, leaders, options, basic keymaps, basic autocmds
+-- ============================================================
+do
+  -- Enable faster startup by caching compiled Lua modules
   vim.loader.enable()
 
   -- Set <space> as the leader key
@@ -175,7 +180,7 @@ vim.o.confirm = true
   vim.keymap.set('n', '<Esc>', '<cmd>nohlsearch<CR>')
 
   -- Diagnostic Config & Keymaps
--- See :help vim.diagnostic.Opts
+  --  See `:help vim.diagnostic.Opts`
   vim.diagnostic.config {
     update_in_insert = false,
     severity_sort = true,
@@ -232,7 +237,13 @@ vim.api.nvim_create_autocmd('TextYankPost', {
     group = vim.api.nvim_create_augroup('kickstart-highlight-yank', { clear = true }),
     callback = function() vim.hl.on_yank() end,
   })
+end
 
+-- ============================================================
+-- SECTION 2: PLUGIN MANAGER
+-- vim.pack, build hooks, install/update plugins, plugin specs
+-- ============================================================
+do
   -- [[ Install plugins with `vim.pack` ]]
   --  See `:help vim.pack`, `:help vim.pack-examples` or
   --  the excellent blog post from the creator of mini.nvim https://echasnovski.com/blog/2026-03-13-a-guide-to-vim-pack
@@ -254,7 +265,9 @@ local function run_build(name, cmd, cwd)
     end
   end
 
--- This autocommand runs after a plugin is installed or updated and runs the appropriate build command for that plugin if necessary.
+  -- This autocommand runs after a plugin is installed or updated and
+  --  runs the appropriate build command for that plugin if necessary.
+  --
   -- See `:help vim.pack-events`
   vim.api.nvim_create_autocmd('PackChanged', {
     callback = function(ev)
@@ -284,7 +297,7 @@ local gh = function(repo) return 'https://github.com/' .. repo end
 
   ---@type (string|vim.pack.Spec)[]
   local plugins = {
-  -- You can specify plugins using just a git URL. It will use the default branch (usually `main` or `master`)
+    -- You can specify plugins with a git URL. `vim.pack` then uses the default branch (usually `main` or `master`)
     gh 'NMAC427/guess-indent.nvim',
     gh 'lewis6991/gitsigns.nvim',
     gh 'folke/which-key.nvim',
@@ -297,14 +310,14 @@ local plugins = {
     gh 'WhoIsSethDaniel/mason-tool-installer.nvim',
     gh 'j-hui/fidget.nvim',
     gh 'stevearc/conform.nvim',
-  -- You can also specify plugin using a version range for its git tag.
+    -- You can also specify plugins with a version range for semver git tags
     --  See `:help vim.version.range()` for more info
     { src = gh 'saghen/blink.cmp', version = vim.version.range '1.*' },
     { src = gh 'L3MON4D3/LuaSnip', version = vim.version.range '2.*' },
     gh 'folke/tokyonight.nvim',
     gh 'folke/todo-comments.nvim',
     gh 'nvim-mini/mini.nvim',
-  -- It is also possible to specify a branch or a specific commit to checkout
+    -- You can also specify a branch or a specific commit
     { src = gh 'nvim-treesitter/nvim-treesitter', version = 'main' },
   }
 
@@ -313,9 +326,15 @@ if vim.fn.executable 'make' == 1 then table.insert(plugins, gh 'nvim-telescope/t
   -- Useful for getting pretty icons, but requires a Nerd Font.
   if vim.g.have_nerd_font then table.insert(plugins, gh 'nvim-tree/nvim-web-devicons') end
 
--- NOTE: Here is where the plugins are actually installed.
+  -- NOTE: Here is where the plugins are actually installed and added to the path
   vim.pack.add(plugins)
+end
 
+-- ============================================================
+-- SECTION 3: UI / CORE UX PLUGINS
+-- guess-indent, gitsigns, which-key, colorscheme, todo-comments, mini modules
+-- ============================================================
+do
   -- [[ Configure plugins ]]
   --  For most plugins you need to call their `.setup()` to start them
   --
@@ -323,10 +342,9 @@ vim.pack.add(plugins)
   --  which will automatically detect and set your indentation settings based on the current file.
   require('guess-indent').setup {}
 
--- Here is a more advanced example where we pass configuration
+  -- Here is a more advanced example that passes configuration options to `gitsigns.nvim`
--- options to `gitsigns.nvim`.
   --
--- See `:help gitsigns` to understand what the configuration keys do
+  -- See `:help gitsigns` to understand what each configuration key does.
   -- Adds git related signs to the gutter, as well as utilities for managing changes
   require('gitsigns').setup {
     signs = {
@@ -340,7 +358,7 @@ require('gitsigns').setup {
 
   -- Useful plugin to show you pending keybinds.
   require('which-key').setup {
-  -- delay between pressing a key and opening which-key (milliseconds)
+    -- Delay between pressing a key and opening which-key (milliseconds)
     delay = 0,
     icons = { mappings = vim.g.have_nerd_font },
     -- Document existing key chains
@@ -352,6 +370,73 @@ require('which-key').setup {
     },
   }
 
+  -- [[ Colorscheme ]]
+  -- You can easily change to a different colorscheme.
+  -- Change the name of the colorscheme plugin below, and then
+  -- change the command under that to load whatever the name of that colorscheme is.
+  --
+  -- If you want to see what colorschemes are already installed, you can use `:Telescope colorscheme`.
+  ---@diagnostic disable-next-line: missing-fields
+  require('tokyonight').setup {
+    styles = {
+      comments = { italic = false }, -- Disable italics in comments
+    },
+  }
+
+  -- Load the colorscheme here.
+  -- Like many other themes, this one has different styles, and you could load
+  -- any other, such as 'tokyonight-storm', 'tokyonight-moon', or 'tokyonight-day'.
+  vim.cmd.colorscheme 'tokyonight-night'
+
+  -- Highlight todo, notes, etc in comments
+  require('todo-comments').setup { signs = false }
+
+  -- Collection of various small independent plugins/modules
+
+  -- Better Around/Inside textobjects
+  --
+  -- Examples:
+  --  - va)  - [V]isually select [A]round [)]paren
+  --  - yiiq - [Y]ank [I]nside [I]+1 [Q]uote
+  --  - ci'  - [C]hange [I]nside [']quote
+  require('mini.ai').setup {
+    -- NOTE: Avoid conflicts with the built-in incremental selection mappings on Neovim>=0.12 (see `:help treesitter-incremental-selection`)
+    mappings = {
+      around_next = 'aa',
+      inside_next = 'ii',
+    },
+    n_lines = 500,
+  }
+
+  -- Add/delete/replace surroundings (brackets, quotes, etc.)
+  --
+  -- - saiw) - [S]urround [A]dd [I]nner [W]ord [)]Paren
+  -- - sd'   - [S]urround [D]elete [']quotes
+  -- - sr)'  - [S]urround [R]eplace [)] [']
+  require('mini.surround').setup()
+
+  -- Simple and easy statusline.
+  --  You could remove this setup call if you don't like it,
+  --  and try some other statusline plugin
+  local statusline = require 'mini.statusline'
+  -- Set `use_icons` to true if you have a Nerd Font
+  statusline.setup { use_icons = vim.g.have_nerd_font }
+
+  -- You can configure sections in the statusline by overriding their
+  -- default behavior. For example, here we set the section for
+  -- cursor location to LINE:COLUMN
+  ---@diagnostic disable-next-line: duplicate-set-field
+  statusline.section_location = function() return '%2l:%-2v' end
+
+  -- ... and there is more!
+  --  Check out: https://github.com/nvim-mini/mini.nvim
+end
+
+-- ============================================================
+-- SECTION 4: SEARCH & NAVIGATION
+-- Telescope setup, keymaps, LSP picker mappings
+-- ============================================================
+do
   -- [[ Fuzzy Finder (files, lsp, etc) ]]
   --
   -- Telescope is a fuzzy finder that comes with a lot of different things that
@@ -410,8 +495,8 @@ vim.keymap.set('n', '<leader>s.', builtin.oldfiles, { desc = '[S]earch Recent Fi
   vim.keymap.set('n', '<leader>sc', builtin.commands, { desc = '[S]earch [C]ommands' })
   vim.keymap.set('n', '<leader><leader>', builtin.buffers, { desc = '[ ] Find existing buffers' })
 
--- This runs on LSP attach per buffer (see main LSP attach function in 'neovim/nvim-lspconfig' config for more info,
+  -- Add Telescope-based LSP pickers when an LSP attaches to a buffer.
--- it is better explained there). This allows easily switching between pickers if you prefer using something else!
+  -- If you later switch picker plugins, this is where to update these mappings.
   vim.api.nvim_create_autocmd('LspAttach', {
     group = vim.api.nvim_create_augroup('telescope-lsp-attach', { clear = true }),
     callback = function(event)
@@ -469,7 +554,13 @@ vim.keymap.set(
 
   -- Shortcut for searching your Neovim configuration files
   vim.keymap.set('n', '<leader>sn', function() builtin.find_files { cwd = vim.fn.stdpath 'config' } end, { desc = '[S]earch [N]eovim files' })
+end
 
+-- ============================================================
+-- SECTION 5: LSP
+-- LSP keymaps, server configuration, Mason tools installations
+-- ============================================================
+do
   -- [[ LSP Configuration ]]
   -- Brief aside: **What is LSP?**
   --
@@ -641,7 +732,13 @@ for name, server in pairs(servers) do
     vim.lsp.config(name, server)
     vim.lsp.enable(name)
   end
+end
 
+-- ============================================================
+-- SECTION 6: FORMATTING
+-- conform.nvim setup and keymap
+-- ============================================================
+do
   -- [[ Formatting ]]
   require('conform').setup {
     notify_on_error = false,
@@ -672,10 +769,14 @@ require('conform').setup {
   }
 
   vim.keymap.set({ 'n', 'v' }, '<leader>f', function() require('conform').format { async = true } end, { desc = '[F]ormat buffer' })
+end
 
--- [[ Autocompletion Configuration ]]
+-- ============================================================
-
+-- SECTION 7: AUTOCOMPLETE & SNIPPETS
--- Snippet Engine
+-- blink.cmp and luasnip setup
+-- ============================================================
+do
+  -- [[ Snippet Engine ]]
   require('luasnip').setup {}
 
   -- `friendly-snippets` contains a variety of premade snippets.
@@ -685,7 +786,7 @@ require('luasnip').setup {}
   -- vim.pack.add { gh 'rafamadriz/friendly-snippets' }
   -- require('luasnip.loaders.from_vscode').lazy_load()
 
--- The autocomplete engine
+  -- [[ Autocomplete Engine ]]
   require('blink.cmp').setup {
     keymap = {
       -- 'default' (recommended) for mappings similar to built-in completions
@@ -739,101 +840,46 @@ require('blink.cmp').setup {
     -- By default, we use the Lua implementation instead, but you may enable
     -- the rust implementation via `'prefer_rust_with_warning'`
     --
-  -- See :h blink-cmp-config-fuzzy for more information
+    -- See `:help blink-cmp-config-fuzzy` for more information
     fuzzy = { implementation = 'lua' },
 
     -- Shows a signature help window while you type arguments for a function
     signature = { enabled = true },
   }
+end
 
--- [[ Colorscheme ]]
+-- ============================================================
--- You can easily change to a different colorscheme.
+-- SECTION 8: TREESITTER
--- Change the name of the colorscheme plugin below, and then
+-- Parser installation, syntax highlighting, folds, indentation
--- change the command under that to load whatever the name of that colorscheme is.
+-- ============================================================
---
+do
--- If you want to see what colorschemes are already installed, you can use `:Telescope colorscheme`.
----@diagnostic disable-next-line: missing-fields
-require('tokyonight').setup {
-  styles = {
-    comments = { italic = false }, -- Disable italics in comments
-  },
-}
-
--- Load the colorscheme here.
--- Like many other themes, this one has different styles, and you could load
--- any other, such as 'tokyonight-storm', 'tokyonight-moon', or 'tokyonight-day'.
-vim.cmd.colorscheme 'tokyonight-night'
-
--- Highlight todo, notes, etc in comments
-require('todo-comments').setup { signs = false }
-
--- Collection of various small independent plugins/modules
-
--- Better Around/Inside textobjects
---
--- Examples:
---  - va)  - [V]isually select [A]round [)]paren
---  - yinq - [Y]ank [I]nside [I]next [Q]uote
---  - ci'  - [C]hange [I]nside [']quote
-require('mini.ai').setup {
-  -- NOTE: Avoid conflicts with the built-in incremental selection mappings on Neovim>=0.12 (see `:help treesitter-incremental-selection`)
-  mappings = {
-    around_next = 'aa',
-    inside_next = 'ii',
-  },
-  n_lines = 500,
-}
-
--- Add/delete/replace surroundings (brackets, quotes, etc.)
---
--- - saiw) - [S]urround [A]dd [I]nner [W]ord [)]Paren
--- - sd'   - [S]urround [D]elete [']quotes
--- - sr)'  - [S]urround [R]eplace [)] [']
-require('mini.surround').setup()
-
--- Simple and easy statusline.
---  You could remove this setup call if you don't like it,
---  and try some other statusline plugin
-local statusline = require 'mini.statusline'
--- set use_icons to true if you have a Nerd Font
-statusline.setup { use_icons = vim.g.have_nerd_font }
-
--- You can configure sections in the statusline by overriding their
--- default behavior. For example, here we set the section for
--- cursor location to LINE:COLUMN
----@diagnostic disable-next-line: duplicate-set-field
-statusline.section_location = function() return '%2l:%-2v' end
-
--- ... and there is more!
---  Check out: https://github.com/nvim-mini/mini.nvim
-
   -- [[ Configure Treesitter ]]
---  Used ighlight, edit, and navigate code
+  --  Used to highlight, edit, and navigate code
   --
   --  See `:help nvim-treesitter-intro`
 
--- ensure basic parser are installed
+  -- Ensure basic parsers are installed
   local parsers = { 'bash', 'c', 'diff', 'html', 'lua', 'luadoc', 'markdown', 'markdown_inline', 'query', 'vim', 'vimdoc' }
   require('nvim-treesitter').install(parsers)
 
   ---@param buf integer
   ---@param language string
   local function treesitter_try_attach(buf, language)
-  -- check if parser exists and load it
+    -- Check if a parser exists and load it
     if not vim.treesitter.language.add(language) then return end
-  -- enables syntax highlighting and other treesitter features
+    -- Enable syntax highlighting and other treesitter features
     vim.treesitter.start(buf, language)
 
-  -- enables treesitter based folds
+    -- Enable treesitter based folds
-  -- for more info on folds see `:help folds`
+    -- For more info on folds see `:help folds`
     -- vim.wo.foldexpr = 'v:lua.vim.treesitter.foldexpr()'
     -- vim.wo.foldmethod = 'expr'
 
-  -- check if treesitter indentation is available for this language, and if so enable it
+    -- Check if treesitter indentation is available for this language, and if so enable it
     -- in case there is no indent query, the indentexpr will fallback to the vim's built in one
     local has_indent_query = vim.treesitter.query.get(language, 'indents') ~= nil
 
-  -- enables treesitter based indentation
+    -- Enable treesitter based indentation
     if has_indent_query then vim.bo.indentexpr = "v:lua.require'nvim-treesitter'.indentexpr()" end
   end
 
@@ -848,18 +894,24 @@ vim.api.nvim_create_autocmd('FileType', {
       local installed_parsers = require('nvim-treesitter').get_installed 'parsers'
 
       if vim.tbl_contains(installed_parsers, language) then
-      -- enable the parser if it is installed
+        -- Enable the parser if it is already installed
         treesitter_try_attach(buf, language)
       elseif vim.tbl_contains(available_parsers, language) then
-      -- if a parser is available in `nvim-treesitter` auto install it, and enable it after the installation is done
+        -- If a parser is available in `nvim-treesitter`, auto-install it and enable it after the installation is done
         require('nvim-treesitter').install(language):await(function() treesitter_try_attach(buf, language) end)
       else
-      -- try to enable treesitter features in case the parser exists but is not available from `nvim-treesitter`
+        -- Try to enable treesitter features in case the parser exists but is not available from `nvim-treesitter`
         treesitter_try_attach(buf, language)
       end
     end,
   })
+end
 
+-- ============================================================
+-- SECTION 9: OPTIONAL EXAMPLES / NEXT STEPS
+-- kickstart.plugins.* examples
+-- ============================================================
+do
   -- The following comments only work if you have downloaded the kickstart repo, not just copy pasted the
   -- init.lua. If you want these files, they are in the repository, so you can just download them and
   -- place them in the correct locations.
@@ -880,6 +932,7 @@ vim.api.nvim_create_autocmd('FileType', {
   --
   --  Uncomment the following line and add your plugins to `lua/custom/plugins/*.lua` to get going.
   -- require 'custom.plugins'
+end
 
 -- The line beneath this is called `modeline`. See `:help modeline`
 -- vim: ts=2 sts=2 sw=2 et

lua/custom/plugins/init.lua

@@ -3,6 +3,11 @@
 --
 -- See the kickstart.nvim README for more information
 
--- Example:
+-- Iterate over all Lua files in the plugins directory and load them
--- vim.pack.add({ 'https://github.com/folke/trouble.nvim' })
+local plugins_dir = vim.fn.stdpath 'config' .. '/lua/custom/plugins'
--- require('trouble').setup {}
+for _, file in ipairs(vim.fn.readdir(plugins_dir)) do
+  if file:match '%.lua$' and file ~= 'init.lua' then
+    local module = file:gsub('%.lua$', '')
+    require('custom.plugins.' .. module)
+  end
+end