refactor: clean up user example files to be easier to follow

lua/config/lazy.lua

@@ -1,17 +1,19 @@
 local lazypath = vim.fn.stdpath "data" .. "/lazy/lazy.nvim"
 if not vim.loop.fs_stat(lazypath) then
-  vim.g.astronvim_first_install = true
+  vim.g.astronvim_first_install = true -- lets AstroNvim know that this is an initial installation
   -- stylua: ignore
   vim.fn.system({ "git", "clone", "--filter=blob:none", "https://github.com/folke/lazy.nvim.git", "--branch=stable", lazypath })
 end
 vim.opt.rtp:prepend(vim.env.LAZY or lazypath)
 
 -- TODO: set to true on release
-local USE_STABLE = false -- use stable releases of AstroNvim
+-- Whether or not to use stable releases of AstroNvim
+local USE_STABLE = false
 
 local spec = {
   -- TODO: remove branch v4 on release
   { "AstroNvim/AstroNvim", branch = "v4", version = USE_STABLE and "*" or nil, import = "astronvim.plugins" },
+  -- { "AstroNvim/AstroNvim", version = "3.x", import = "astronvim.plugins" }, -- use this line to only get updates for v3 and avoid the breaking changes if v4 is released
 }
 if USE_STABLE then table.insert(spec, { import = "astronvim.lazy_snapshot" }) end -- pin plugins to known stable versions/commits
 

lua/config/options.lua

@@ -1,10 +1,11 @@
 -- Options are automatically loaded before lazy.nvim startup
 -- Default options that are always set: https://github.com/AstroNvim/AstroNvim/blob/main/lua/astronvim/options.lua
 -- Add any additional options here
-vim.opt.relativenumber = true -- sets vim.opt.relativenumber
-vim.opt.number = true -- sets vim.opt.number
-vim.opt.spell = false -- sets vim.opt.spell
-vim.opt.signcolumn = "auto" -- sets vim.opt.signcolumn to auto
-vim.opt.wrap = false -- sets vim.opt.wrap
 
-vim.g.mapleader = " " -- sets vim.g.mapleader
+-- vim.opt.relativenumber = true -- sets vim.opt.relativenumber
+-- vim.opt.number = true -- sets vim.opt.number
+-- vim.opt.spell = false -- sets vim.opt.spell
+-- vim.opt.signcolumn = "auto" -- sets vim.opt.signcolumn to auto
+-- vim.opt.wrap = false -- sets vim.opt.wrap
+
+-- vim.g.mapleader = " " -- sets vim.g.mapleader

lua/plugins/astrolsp.lua

@@ -1,39 +0,0 @@
-return {
-  "AstroNvim/astrolsp",
-  opts = {
-    -- Diagnostics configuration (for vim.diagnostics.config({...})) when diagnostics are on
-    diagnostics = {
-      virtual_text = true,
-      underline = true,
-    },
-    -- customize lsp formatting options
-    formatting = {
-      -- control auto formatting on save
-      format_on_save = {
-        enabled = true, -- enable or disable format on save globally
-        allow_filetypes = { -- enable format on save for specified filetypes only
-          -- "go",
-        },
-        ignore_filetypes = { -- disable format on save for specified filetypes
-          -- "python",
-        },
-      },
-      disabled = { -- disable formatting capabilities for the listed language servers
-        -- disable lua_ls formatting capability if you want to use StyLua to format your lua code
-        -- "lua_ls",
-      },
-      timeout_ms = 1000, -- default format timeout
-      -- filter = function(client) -- fully override the default formatting function
-      --   return true
-      -- end
-    },
-    -- enable servers that you already have installed without mason
-    servers = {
-      -- "pyright"
-    },
-    -- customize language server configuration options passed to `lspconfig`
-    config = {
-      -- clangd = { capabilities = { offsetEncoding = "utf-8" } },
-    },
-  },
-}

lua/plugins/astroui.lua

@@ -1,14 +0,0 @@
-return {
-  "AstroNvim/astroui",
-  opts = {
-    colorscheme = "astrodark", -- change colorscheme
-    highlights = {
-      init = { -- this table overrides highlights in all themes
-        -- Normal = { bg = "#000000" },
-      },
-      duskfox = { -- a table of overrides/changes to the duskfox theme
-        -- Normal = { bg = "#000000" },
-      },
-    },
-  },
-}

lua/plugins/colorscheme.lua

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

lua/plugins/community.lua

@@ -0,0 +1,23 @@
+return {
+  -- Add community imports to the `lua/config/lazy.lua` file in your Neovim configuration folder (typically ~/.config/nvim)
+  -- this guarantees that the community plugin specs are loaded before the user configuration
+
+  -- This is a good place to do further customize the options set by the community plugins/packs
+  -- {
+  --   "catppuccin/nvim",
+  --   opts = {
+  --     integrations = {
+  --       sandwich = false,
+  --       noice = true,
+  --       mini = true,
+  --       leap = true,
+  --       markdown = true,
+  --       neotest = true,
+  --       cmp = true,
+  --       overseer = true,
+  --       lsp_trouble = true,
+  --       rainbow_delimiters = true,
+  --     },
+  --   },
+  -- },
+}

lua/plugins/core.lua

@@ -1,28 +1,30 @@
+-- You can simply override any internal plugins using Lazy, here are some example operations:
 return {
   -- customize alpha options
-  {
+  -- {
-    "goolord/alpha-nvim",
+  --   "goolord/alpha-nvim",
-    opts = function(_, opts)
+  --   opts = function(_, opts)
-      -- customize the dashboard header
+  --     -- customize the dashboard header
-      opts.section.header.val = {
+  --     opts.section.header.val = {
-        " █████  ███████ ████████ ██████   ██████",
+  --       " █████  ███████ ████████ ██████   ██████",
-        "██   ██ ██         ██    ██   ██ ██    ██",
+  --       "██   ██ ██         ██    ██   ██ ██    ██",
-        "███████ ███████    ██    ██████  ██    ██",
+  --       "███████ ███████    ██    ██████  ██    ██",
-        "██   ██      ██    ██    ██   ██ ██    ██",
+  --       "██   ██      ██    ██    ██   ██ ██    ██",
-        "██   ██ ███████    ██    ██   ██  ██████",
+  --       "██   ██ ███████    ██    ██   ██  ██████",
-        " ",
+  --       " ",
-        "    ███    ██ ██    ██ ██ ███    ███",
+  --       "    ███    ██ ██    ██ ██ ███    ███",
-        "    ████   ██ ██    ██ ██ ████  ████",
+  --       "    ████   ██ ██    ██ ██ ████  ████",
-        "    ██ ██  ██ ██    ██ ██ ██ ████ ██",
+  --       "    ██ ██  ██ ██    ██ ██ ██ ████ ██",
-        "    ██  ██ ██  ██  ██  ██ ██  ██  ██",
+  --       "    ██  ██ ██  ██  ██  ██ ██  ██  ██",
-        "    ██   ████   ████   ██ ██      ██",
+  --       "    ██   ████   ████   ██ ██      ██",
-      }
+  --     }
-      return opts
+  --     return opts
-    end,
+  --   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",
@@ -62,16 +64,4 @@ return {
   --     )
   --   end,
   -- },
-  -- By adding to the which-key config and using our helper function you can add more which-key registered bindings
-  -- {
-  --   "folke/which-key.nvim",
-  --   config = function(plugin, opts)
-  --     require "plugins.configs.which-key"(plugin, opts) -- include the default astronvim config that calls the setup call
-  --     -- Add bindings which show up as group name
-  --     local wk = require "which-key"
-  --     wk.register({
-  --       b = { name = "Buffer" },
-  --     }, { mode = "n", prefix = "<leader>" })
-  --   end,
-  -- },
 }

lua/plugins/highlights.lua

@@ -0,0 +1,16 @@
+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
+return {
+  "AstroNvim/astroui",
+  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

@@ -0,0 +1,16 @@
+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
+return {
+  "AstroNvim/astrocore",
+  opts = {
+    -- modify core features of AstroNvim
+    features = {
+      max_file = { 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/lsp.lua

@@ -0,0 +1,68 @@
+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
+return {
+  "AstroNvim/astrolsp",
+  opts = {
+    -- Diagnostics configuration (for vim.diagnostics.config({...})) when diagnostics are on
+    diagnostics = {
+      virtual_text = true,
+      underline = true,
+    },
+    -- customize lsp formatting options
+    formatting = {
+      -- control auto formatting on save
+      format_on_save = {
+        enabled = true, -- enable or disable format on save globally
+        allow_filetypes = { -- enable format on save for specified filetypes only
+          -- "go",
+        },
+        ignore_filetypes = { -- disable format on save for specified filetypes
+          -- "python",
+        },
+      },
+      disabled = { -- disable formatting capabilities for the listed language servers
+        -- disable lua_ls formatting capability if you want to use StyLua to format your lua code
+        -- "lua_ls",
+      },
+      timeout_ms = 1000, -- default format timeout
+      -- filter = function(client) -- fully override the default formatting function
+      --   return true
+      -- end
+    },
+    -- enable servers that you already have installed without mason
+    servers = {
+      -- "pyright"
+    },
+    -- customize language server configuration options passed to `lspconfig`
+    config = {
+      -- clangd = { capabilities = { offsetEncoding = "utf-8" } },
+    },
+    -- customize how language servers are attached
+    setup_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
+
+      -- the key is the server that is being setup with `lspconfig`
+      -- 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
+    },
+    -- mappings to be set up on attaching of a language server
+    mappings = {
+      n = {
+        gl = { function() vim.diagnostic.open_float() end, desc = "Hover diagnostics" },
+        -- a `cond` key can provided as the string of a server capability to be required to attach, or a function with `client` and `bufnr` parameters from the `on_attach` that returns a boolean
+        -- gD = {
+        --   function() vim.lsp.buf.declaration() end,
+        --   desc = "Declaration of current symbol",
+        --   cond = "textDocument/declaration",
+        -- },
+        -- ["<leader>uY"] = {
+        --   function() require("astrolsp.toggles").buffer_semantic_tokens() end,
+        --   desc = "Toggle LSP semantic highlight (buffer)",
+        --   cond = function(client) return client.server_capabilities.semanticTokensProvider and vim.lsp.semantic_tokens end,
+        -- },
+      },
+    },
+  },
+}

lua/plugins/mappings.lua

@@ -1,18 +1,9 @@
+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
 return {
   "AstroNvim/astrocore",
   opts = {
-    features = {
-      max_file = { 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
-    },
-    -- Mapping data with "desc" stored directly by vim.keymap.set().
-    --
-    -- Please use this mappings table to set keyboard mapping since this is the
-    -- lower level configuration and more robust one. (which-key will
-    -- automatically pick-up stored data by this setting.)
     mappings = {
       -- first key is the mode
       n = {

lua/plugins/mason.lua

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

lua/plugins/null-ls.lua

@@ -1,3 +1,6 @@
+if true then return {} end -- REMOVE THIS LINE TO ACTIVATE THIS FILE
+
+-- Exapmle customization of Null-LS sources
 return {
   "jose-elias-alvarez/null-ls.nvim",
   opts = function(_, config)

lua/plugins/treesitter.lua

@@ -1,3 +1,6 @@
+if true then return {} end -- REMOVE THIS LINE TO ACTIVATE THIS FILE
+
+-- Exapmle customization of Treesitter
 return {
   "nvim-treesitter/nvim-treesitter",
   opts = function(_, opts)

lua/plugins/user.lua

@@ -1,6 +1,5 @@
+-- You can also add new plugins here as well using the lazy syntax:
 return {
-  -- You can also add new plugins here as well:
-  -- Add plugins, the lazy syntax
   -- "andweeb/presence.nvim",
   -- {
   --   "ray-x/lsp_signature.nvim",