refactor: combine files to align with plugin organization and add more comments

init.lua

@@ -1,3 +1,5 @@
+-- This file simply bootstraps the installation of Lazy.nvim and then calls other files for execution
+-- This file doesn't necessarily need to be touched, BE CAUTIOUS editing this file and proceed at your own risk.
 local lazypath = vim.env.LAZY or vim.fn.stdpath "data" .. "/lazy/lazy.nvim"
 if not (vim.env.LAZY or vim.loop.fs_stat(lazypath)) then
   vim.g.astronvim_first_install = true -- lets AstroNvim know that this is an initial installation

lua/community.lua

@@ -1,6 +1,9 @@
 if true then return {} end -- REMOVE THIS LINE TO ACTIVATE THIS FILE
 
 -- AstroCommunity: import any community modules here
+-- We import this file in `lazy_setup.lua` before the `plugins/` folder.
+-- This guarantees that the specs are processed before any user plugins.
+
 ---@type LazySpec
 return {
   -- TODO: Remove branch v4 on release

lua/lazy_setup.lua

@@ -13,6 +13,7 @@ require("lazy").setup({
   { import = "community" },
   { import = "plugins" },
 } --[[@as LazySpec]], {
+  -- Configure any other `lazy.nvim` configuration options here
   install = { colorscheme = { "astrodark", "habamax" } },
   performance = {
     rtp = {

lua/plugins/astrocore.lua

@@ -0,0 +1,73 @@
+if true then return {} end -- REMOVE THIS LINE TO ACTIVATE THIS FILE
+
+-- AstroCore provides a central place to modify mappings, vim options, autocommands, and more!
+-- Configuration documentation can be found with `:h astrocore`
+-- NOTE: We highly recommend settig up the Lua Language Server (lua_ls) as this provides autocomplete and documentation while editing
+
+---@type LazySpec
+return {
+  "AstroNvim/astrocore",
+  ---@type AstroCoreOpts
+  opts = {
+    -- Configure core features of AstroNvim
+    features = {
+      large_buf = { size = 1024 * 100, lines = 10000 }, -- set global limits for large files for disabling features like treesitter
+      autopairs = true, -- enable autopairs at start
+      cmp = true, -- enable completion at start
+      highlighturl = true, -- highlight URLs at start
+      notifications = true, -- enable notifications at start
+    },
+    -- vim options can be configured here
+    options = {
+      opt = { -- vim.opt.<key>
+        relativenumber = true, -- sets vim.opt.relativenumber
+        number = true, -- sets vim.opt.number
+        spell = false, -- sets vim.opt.spell
+        signcolumn = "auto", -- sets vim.opt.signcolumn to auto
+        wrap = false, -- sets vim.opt.wrap
+      },
+      g = { -- vim.g.<key>
+        -- configure global vim variables (vim.g)
+        -- NOTE: `mapleader` and `maplocalleader` must be set in the AstroNvim opts or before `lazy.setup`
+        -- This can be found in the `lua/lazy_setup.lua` file
+      },
+    },
+    -- Mappings can be configured through AstroCore as well.
+    -- NOTE: keycodes follow the casing in the vimdocs. For example, `<Leader>` must be capitalized
+    mappings = {
+      -- first key is the mode
+      n = {
+        -- second key is the lefthand side of the map
+
+        -- navigate buffer tabs with `H` and `L`
+        -- L = {
+        --   function() require("astrocore.buffer").nav(vim.v.count > 0 and vim.v.count or 1) end,
+        --   desc = "Next buffer",
+        -- },
+        -- H = {
+        --   function() require("astrocore.buffer").nav(-(vim.v.count > 0 and vim.v.count or 1)) end,
+        --   desc = "Previous buffer",
+        -- },
+
+        -- mappings seen under group name "Buffer"
+        ["<Leader>bD"] = {
+          function()
+            require("astroui.status.heirline").buffer_picker(
+              function(bufnr) require("astrocore.buffer").close(bufnr) end
+            )
+          end,
+          desc = "Pick to close",
+        },
+        -- tables with just a `desc` key will be registered with which-key if it's installed
+        -- this is useful for naming menus
+        ["<Leader>b"] = { desc = "Buffers" },
+        -- quick save
+        -- ["<C-s>"] = { ":w!<cr>", desc = "Save File" },  -- change description but the same command
+      },
+      t = {
+        -- setting a mapping to false will disable it
+        -- ["<esc>"] = false,
+      },
+    },
+  },
+}

lua/plugins/astrolsp.lua

@@ -1,6 +1,9 @@
 if true then return {} end -- REMOVE THIS LINE TO ACTIVATE THIS FILE
 
 -- AstroLSP allows you to customize the features in AstroNvim's LSP configuration engine
+-- Configuration documentation can be found with `:h astrolsp`
+-- NOTE: We highly recommend settig up the Lua Language Server (lua_ls) as this provides autocomplete and documentation while editing
+
 ---@type LazySpec
 return {
   "AstroNvim/astrolsp",
@@ -51,7 +54,7 @@ return {
       -- clangd = { capabilities = { offsetEncoding = "utf-8" } },
     },
     -- customize how language servers are attached
-    setup_handlers = {
+    handlers = {
       -- a function without a key is simply the default handler, functions take two parameters, the server name and the configured options table for that server
       -- function(server, opts) require("lspconfig")[server].setup(opts) end
 
@@ -59,6 +62,31 @@ return {
       -- rust_analyzer = false, -- setting a handler to false will disable the set up of that language server
       -- pyright = function(_, opts) require("lspconfig").pyright.setup(opts) end -- or a custom handler function can be passed
     },
+    -- Configure buffer local auto commands to add when attaching a language server
+    autocmds = {
+      -- first key is the `augroup` to add the auto commands to (:h augroup)
+      lsp_document_highlight = {
+        -- Optional condition to create/delete auto command group
+        -- can either be a string of a client capability or a function of `fun(client, bufnr): boolean`
+        -- condition will be resolved for each client on each execution and if it ever fails for all clients,
+        -- the auto commands will be deleted for that buffer
+        cond = "textDocument/documentHighlight",
+        -- cond = function(client, bufnr) return client.name == "lua_ls" end,
+        -- list of auto commands to set
+        {
+          -- events to trigger
+          event = { "CursorHold", "CursorHoldI" },
+          -- the rest of the autocmd options (:h nvim_create_autocmd)
+          desc = "Document Highlighting",
+          callback = function() vim.lsp.buf.document_highlight() end,
+        },
+        {
+          event = { "CursorMoved", "CursorMovedI", "BufLeave" },
+          desc = "Document Highlighting Clear",
+          callback = function() vim.lsp.buf.clear_references() end,
+        },
+      },
+    },
     -- mappings to be set up on attaching of a language server
     mappings = {
       n = {
@@ -76,5 +104,11 @@ return {
         -- },
       },
     },
+    -- A custom `on_attach` function to be run after the default `on_attach` function
+    -- takes two parameters `client` and `bufnr`  (`:h lspconfig-setup`)
+    on_attach = function(client, bufnr)
+      -- this would disable semanticTokensProvider for all clients
+      -- client.server_capabilities.semanticTokensProvider = nil
+    end,
   },
 }

lua/plugins/astroui.lua

@@ -0,0 +1,38 @@
+if true then return {} end -- REMOVE THIS LINE TO ACTIVATE THIS FILE
+
+-- AstroUI provides the basis for configuring the AstroNvim User Interface
+-- Configuration documentation can be found with `:h astroui`
+-- NOTE: We highly recommend settig up the Lua Language Server (lua_ls) as this provides autocomplete and documentation while editing
+
+---@type LazySpec
+return {
+  "AstroNvim/astroui",
+  ---@type AstroUIOpts
+  opts = {
+    -- change colorscheme
+    colorscheme = "astrodark",
+    -- AstroUI allows you to easily modify highlight groups easily for any and all colorschemes
+    highlights = {
+      init = { -- this table overrides highlights in all themes
+        -- Normal = { bg = "#000000" },
+      },
+      astrotheme = { -- a table of overrides/changes when applying the astrotheme theme
+        -- Normal = { bg = "#000000" },
+      },
+    },
+    -- Icons can be configured throughout the interface
+    icons = {
+      -- configure the loading of the lsp in the status line
+      LSPLoading1 = "⠋",
+      LSPLoading2 = "⠙",
+      LSPLoading3 = "⠹",
+      LSPLoading4 = "⠸",
+      LSPLoading5 = "⠼",
+      LSPLoading6 = "⠴",
+      LSPLoading7 = "⠦",
+      LSPLoading8 = "⠧",
+      LSPLoading9 = "⠇",
+      LSPLoading10 = "⠏",
+    },
+  },
+}

lua/plugins/colorscheme.lua

@@ -1,10 +0,0 @@
-if true then return {} end -- REMOVE THIS LINE TO ACTIVATE THIS FILE
-
----@type LazySpec
-return {
-  "AstroNvim/astroui",
-  ---@type AstroUIOpts
-  opts = {
-    colorscheme = "astrodark", -- change colorscheme
-  },
-}

lua/plugins/core.lua

@@ -1,70 +0,0 @@
-if true then return {} end -- REMOVE THIS LINE TO ACTIVATE THIS FILE
-
--- You can simply override any internal plugins using Lazy, here are some example operations:
----@type LazySpec
-return {
-  -- customize alpha options
-  {
-    "goolord/alpha-nvim",
-    opts = function(_, opts)
-      -- customize the dashboard header
-      opts.section.header.val = {
-        " █████  ███████ ████████ ██████   ██████",
-        "██   ██ ██         ██    ██   ██ ██    ██",
-        "███████ ███████    ██    ██████  ██    ██",
-        "██   ██      ██    ██    ██   ██ ██    ██",
-        "██   ██ ███████    ██    ██   ██  ██████",
-        " ",
-        "    ███    ██ ██    ██ ██ ███    ███",
-        "    ████   ██ ██    ██ ██ ████  ████",
-        "    ██ ██  ██ ██    ██ ██ ██ ████ ██",
-        "    ██  ██ ██  ██  ██  ██ ██  ██  ██",
-        "    ██   ████   ████   ██ ██      ██",
-      }
-      return opts
-    end,
-  },
-
-  -- You can disable default plugins as follows:
-  { "max397574/better-escape.nvim", enabled = false },
-
-  -- You can also easily customize additional setup of plugins that is outside of the plugin's setup call
-  {
-    "L3MON4D3/LuaSnip",
-    config = function(plugin, opts)
-      require "astronvim.plugins.configs.luasnip"(plugin, opts) -- include the default astronvim config that calls the setup call
-      -- add more custom luasnip configuration such as filetype extend or custom snippets
-      local luasnip = require "luasnip"
-      luasnip.filetype_extend("javascript", { "javascriptreact" })
-    end,
-  },
-  {
-    "windwp/nvim-autopairs",
-    config = function(plugin, opts)
-      require "astronvim.plugins.configs.nvim-autopairs"(plugin, opts) -- include the default astronvim config that calls the setup call
-      -- add more custom autopairs configuration such as custom rules
-      local npairs = require "nvim-autopairs"
-      local Rule = require "nvim-autopairs.rule"
-      local cond = require "nvim-autopairs.conds"
-      npairs.add_rules(
-        {
-          Rule("$", "$", { "tex", "latex" })
-            -- don't add a pair if the next character is %
-            :with_pair(cond.not_after_regex "%%")
-            -- don't add a pair if  the previous character is xxx
-            :with_pair(
-              cond.not_before_regex("xxx", 3)
-            )
-            -- don't move right when repeat character
-            :with_move(cond.none())
-            -- don't delete if the next character is xx
-            :with_del(cond.not_after_regex "xx")
-            -- disable adding a newline when you press <cr>
-            :with_cr(cond.none()),
-        },
-        -- disable for .vim files, but it work for another filetypes
-        Rule("a", "a", "-vim")
-      )
-    end,
-  },
-}

lua/plugins/highlights.lua

@@ -1,18 +0,0 @@
-if true then return {} end -- REMOVE THIS LINE TO ACTIVATE THIS FILE
-
--- AstroUI allows you to easily modify highlight groups easily for any and all colorschemes
----@type LazySpec
-return {
-  "AstroNvim/astroui",
-  ---@type AstroUIOpts
-  opts = {
-    highlights = {
-      init = { -- this table overrides highlights in all themes
-        -- Normal = { bg = "#000000" },
-      },
-      astrotheme = { -- a table of overrides/changes when applying the astrotheme theme
-        -- Normal = { bg = "#000000" },
-      },
-    },
-  },
-}

lua/plugins/init.lua

@@ -1,18 +0,0 @@
-if true then return {} end -- REMOVE THIS LINE TO ACTIVATE THIS FILE
-
--- AstroCore allows you easy access to customize the default options provided in AstroNvim
----@type LazySpec
-return {
-  "AstroNvim/astrocore",
-  ---@type AstroCoreOpts
-  opts = {
-    -- modify core features of AstroNvim
-    features = {
-      large_buf = { size = 1024 * 100, lines = 10000 }, -- set global limits for large files for disabling features like treesitter
-      autopairs = true, -- enable autopairs at start
-      cmp = true, -- enable completion at start
-      highlighturl = true, -- highlight URLs at start
-      notifications = true, -- enable notifications at start
-    },
-  },
-}

lua/plugins/mappings.lua

@@ -1,45 +0,0 @@
-if true then return {} end -- REMOVE THIS LINE TO ACTIVATE THIS FILE
-
--- AstroCore provides a central place to modify mappings set up as well as which-key menu titles
----@type LazySpec
-return {
-  "AstroNvim/astrocore",
-  ---@type AstroCoreOpts
-  opts = {
-    mappings = {
-      -- first key is the mode
-      n = {
-        -- second key is the lefthand side of the map
-
-        -- navigate buffer tabs with `H` and `L`
-        -- L = {
-        --   function() require("astrocore.buffer").nav(vim.v.count > 0 and vim.v.count or 1) end,
-        --   desc = "Next buffer",
-        -- },
-        -- H = {
-        --   function() require("astrocore.buffer").nav(-(vim.v.count > 0 and vim.v.count or 1)) end,
-        --   desc = "Previous buffer",
-        -- },
-
-        -- mappings seen under group name "Buffer"
-        ["<Leader>bD"] = {
-          function()
-            require("astroui.status.heirline").buffer_picker(
-              function(bufnr) require("astrocore.buffer").close(bufnr) end
-            )
-          end,
-          desc = "Pick to close",
-        },
-        -- tables with just a `desc` key will be registered with which-key if it's installed
-        -- this is useful for naming menus
-        ["<Leader>b"] = { desc = "Buffers" },
-        -- quick save
-        -- ["<C-s>"] = { ":w!<cr>", desc = "Save File" },  -- change description but the same command
-      },
-      t = {
-        -- setting a mapping to false will disable it
-        -- ["<esc>"] = false,
-      },
-    },
-  },
-}

lua/plugins/mason.lua

@@ -1,6 +1,7 @@
 if true then return {} end -- REMOVE THIS LINE TO ACTIVATE THIS FILE
 
--- Example customization of mason plugins
+-- Customize Mason plugins
+
 ---@type LazySpec
 return {
   -- use mason-lspconfig to configure LSP installations

lua/plugins/none-ls.lua

@@ -1,6 +1,7 @@
 if true then return {} end -- REMOVE THIS LINE TO ACTIVATE THIS FILE
 
--- Example customization of Null-LS sources
+-- Customize None-ls sources
+
 ---@type LazySpec
 return {
   "nvimtools/none-ls.nvim",

lua/plugins/options.lua

@@ -1,17 +0,0 @@
-if true then return {} end -- REMOVE THIS LINE TO ACTIVATE THIS FILE
-
-return {
-  "AstroNvim/astrocore",
-  ---@type AstroCoreOpts
-  opts = {
-    options = {
-      opt = {
-        relativenumber = true, -- sets vim.opt.relativenumber
-        number = true, -- sets vim.opt.number
-        spell = false, -- sets vim.opt.spell
-        signcolumn = "auto", -- sets vim.opt.signcolumn to auto
-        wrap = false, -- sets vim.opt.wrap
-      },
-    },
-  },
-}

lua/plugins/treesitter.lua

@@ -1,6 +1,7 @@
 if true then return {} end -- REMOVE THIS LINE TO ACTIVATE THIS FILE
 
--- Example customization of Treesitter
+-- Customize Treesitter
+
 ---@type LazySpec
 return {
   "nvim-treesitter/nvim-treesitter",

lua/plugins/ui.lua

@@ -1,34 +0,0 @@
-if true then return {} end -- REMOVE THIS LINE TO ACTIVATE THIS FILE
-
----@type LazySpec
-return {
-  "AstroNvim/astroui",
-  ---@type AstroUIOpts
-  opts = {
-    icons = {
-      -- configure the loading of the lsp in the status line
-      LSPLoading1 = "⠋",
-      LSPLoading2 = "⠙",
-      LSPLoading3 = "⠹",
-      LSPLoading4 = "⠸",
-      LSPLoading5 = "⠼",
-      LSPLoading6 = "⠴",
-      LSPLoading7 = "⠦",
-      LSPLoading8 = "⠧",
-      LSPLoading9 = "⠇",
-      LSPLoading10 = "⠏",
-    },
-    text_icons = {
-      -- configure the loading of the lsp in the status line
-      LSPLoading1 = "|",
-      LSPLoading2 = "/",
-      LSPLoading3 = "-",
-      LSPLoading4 = "\\",
-
-      -- configure neotree
-      FolderClosed = "+",
-      FolderEmpty = "-",
-      FolderOpen = "-",
-    },
-  },
-}

lua/plugins/user.lua

@@ -1,12 +1,85 @@
 if true then return {} end -- REMOVE THIS LINE TO ACTIVATE THIS FILE
 
--- You can also add new plugins here as well using the lazy syntax:
+-- You can also add or configure plugins by creating files in this `plugins/` folder
+-- Here are some examples:
+
 ---@type LazySpec
 return {
+
+  -- == Examples of Adding Plugins ==
+
   "andweeb/presence.nvim",
   {
     "ray-x/lsp_signature.nvim",
     event = "BufRead",
     config = function() require("lsp_signature").setup() end,
   },
+
+  -- == Examples of Overriding Plugins ==
+
+  -- customize alpha options
+  {
+    "goolord/alpha-nvim",
+    opts = function(_, opts)
+      -- customize the dashboard header
+      opts.section.header.val = {
+        " █████  ███████ ████████ ██████   ██████",
+        "██   ██ ██         ██    ██   ██ ██    ██",
+        "███████ ███████    ██    ██████  ██    ██",
+        "██   ██      ██    ██    ██   ██ ██    ██",
+        "██   ██ ███████    ██    ██   ██  ██████",
+        " ",
+        "    ███    ██ ██    ██ ██ ███    ███",
+        "    ████   ██ ██    ██ ██ ████  ████",
+        "    ██ ██  ██ ██    ██ ██ ██ ████ ██",
+        "    ██  ██ ██  ██  ██  ██ ██  ██  ██",
+        "    ██   ████   ████   ██ ██      ██",
+      }
+      return opts
+    end,
+  },
+
+  -- You can disable default plugins as follows:
+  { "max397574/better-escape.nvim", enabled = false },
+
+  -- You can also easily customize additional setup of plugins that is outside of the plugin's setup call
+  {
+    "L3MON4D3/LuaSnip",
+    config = function(plugin, opts)
+      require "astronvim.plugins.configs.luasnip"(plugin, opts) -- include the default astronvim config that calls the setup call
+      -- add more custom luasnip configuration such as filetype extend or custom snippets
+      local luasnip = require "luasnip"
+      luasnip.filetype_extend("javascript", { "javascriptreact" })
+    end,
+  },
+
+  {
+    "windwp/nvim-autopairs",
+    config = function(plugin, opts)
+      require "astronvim.plugins.configs.nvim-autopairs"(plugin, opts) -- include the default astronvim config that calls the setup call
+      -- add more custom autopairs configuration such as custom rules
+      local npairs = require "nvim-autopairs"
+      local Rule = require "nvim-autopairs.rule"
+      local cond = require "nvim-autopairs.conds"
+      npairs.add_rules(
+        {
+          Rule("$", "$", { "tex", "latex" })
+            -- don't add a pair if the next character is %
+            :with_pair(cond.not_after_regex "%%")
+            -- don't add a pair if  the previous character is xxx
+            :with_pair(
+              cond.not_before_regex("xxx", 3)
+            )
+            -- don't move right when repeat character
+            :with_move(cond.none())
+            -- don't delete if the next character is xx
+            :with_del(cond.not_after_regex "xx")
+            -- disable adding a newline when you press <cr>
+            :with_cr(cond.none()),
+        },
+        -- disable for .vim files, but it work for another filetypes
+        Rule("a", "a", "-vim")
+      )
+    end,
+  },
 }