feat: use more expressive code features

src/content/docs/configuration/custom_plugins.md

@@ -33,7 +33,7 @@ Overriding plugins are as simple as adding a plugin specification for that plugi
 
 Here are some examples of overwriting some plugins:
 
-```lua title="lua/plugins/overrided.lua"
+```lua title="lua/plugins/overrided.lua" {5-10} {17-23}
 return {
   {
     "AstroNvim/AstroLSP",
@@ -71,7 +71,7 @@ Not all plugins have custom `config` functions and will not have an `astronvim.p
 
 ::::
 
-```lua title="lua/plugins/extended_config.lua"
+```lua title="lua/plugins/extended_config.lua" {10-11}
 return {
   {
     "nvim-telescope/telescope.nvim",
@@ -95,19 +95,19 @@ return {
 
 Plugins can be easily disabled by simply setting the `enabled` option to `false`. Here is an example of disabling the core dashboard plugin, `alpha`:
 
-```lua title="lua/plugins/disabled.lua"
+```lua title="lua/plugins/disabled.lua" "enabled = false"
 return {
   { "goolord/alpha-nvim", enabled = false },
 }
 ```
 
 ## Lazy Loading
 
-Lazy loading can be used to delay plugin loading to speed up start up time. There are a few basic methods of lazy loading that can be easily added. The main keys here are `cmd`, `module`, `ft`, `keys`, `event`, `after`. More details of these and more options can be found in the [Lazy Documentation](https://github.com/folke/lazy.nvim#-plugin-spec). Here are a few examples:
+Lazy loading can be used to delay plugin loading to speed up start up time. There are a few basic methods of lazy loading that can be easily added. The main keys here are `lazy`, `cmd`, `ft`, `keys`, and `event`. More details of these and more options can be found in the [Lazy Documentation](https://github.com/folke/lazy.nvim#-plugin-spec). Here are a few examples:
 
-```lua title="lua/plugins/lazy_loaded.lua"
+```lua title="lua/plugins/lazy_loaded.lua" /((lazy|event|cmd|ft|keys) = (\S+|{.*}))/
 return {
-  -- by setting `lazy = true` the plugin will automatically be lazy loaded
+  -- by enabling the lazy option, the plugin will automatically be lazy loaded
   -- until it's module is called for example require("tokyonight")
   { "folke/tokyonight.nvim", lazy = true },
 
@@ -116,14 +116,20 @@ return {
 
   -- this plugin will be loaded when using `:ZenMode`
   { "folke/zen-mode.nvim", cmd = "ZenMode" },
+
+  -- this plugin will be loaded when using `:ZenMode`
+  { "folke/zen-mode.nvim", cmd = "ZenMode" },
+
+  -- this plugin will be loaded when opening a "markdown" file
+  { "lukas-reineke/headlines.nvim", ft = "markdown" },
 }
 ```
 
 ### Lazy Load File Related Plugins
 
 AstroNvim has many plugins that we load on the first real file that is open. This is used internally for plugins like Treesitter, LSP related plugins, and other various plugins related to interacting with files. We achieve this by creating a custom `User` `autocmd` event called `AstroFile`. This can also be used by users for lazy loading plugins on the first real file that is opened:
 
-```lua title="lua/plugins/nvim-colorizer.lua"
+```lua title="lua/plugins/nvim-colorizer.lua" {4}
 return {
   {
     "NvChad/nvim-colorizer.lua",
@@ -138,7 +144,7 @@ This will tell AstroNvim that this plugin should be loaded whenever the `User` a
 
 Similar to the file related plugins described above, we also have a similar hook for git related plugins. These shouldn't be loaded until a file is open that is in a git repository folder. We use this for stuff like the `gitsigns` plugin. This will check when a file is opened if it is in a git tracked folder and then load the plugin. This `User` `autocmd` event is `AstroGitFile`. **This does require access to the `git` command in your `PATH`.**
 
-```lua title="lua/plugins/gitsigns.lua"
+```lua title="lua/plugins/gitsigns.lua" {4}
 return {
   {
     "lewis6991/gitsigns.nvim",

src/content/docs/configuration/lua_completion.md

@@ -17,7 +17,7 @@ In `lazy.nvim` there are a couple formats that the `opts` can be specified in, e
 
 Most commonly, the `opts` will be specified as a simple table. This is useful if you simply want to extend the table without any special logic. For this case, you simply have to specify the type of the table above it.
 
-```lua title="lua/plugins/astrocore.lua"
+```lua title="lua/plugins/astrocore.lua" {3}
 return {
   "AstroNvim/astrocore",
   ---@type AstroCoreOpts
@@ -37,7 +37,7 @@ AstroLSP allows for language server configuration completion by utilizing types
 
 before the `config` table. Here is an example:
 
-```lua title="lua/plugins/astrolsp.lua"
+```lua title="lua/plugins/astrolsp.lua" {5}
 return {
   "AstroNvim/astrolsp",
   ---@type AstroLSPOpts
@@ -56,7 +56,7 @@ return {
 
 Other times a function may be required if you want to include any sort of special logic for calculating the table or for handling cases that table merging doesn't deal with properly such as list-like tables. Here you need to specify the type of the parameter in the function.
 
-```lua title="lua/plugins/astrocore.lua"
+```lua title="lua/plugins/astrocore.lua" {3}
 return {
   "AstroNvim/astrocore",
   ---@param opts AstroCoreOpts

src/content/docs/recipes/advanced_lsp.md

@@ -11,7 +11,7 @@ Our main tool for configuring and setting up language servers is with the [nvim-
 
 AstroLSP automatically calls these `setup` functions for language servers installed through Mason and for servers specified manually (See [LSP Setup Without Installer](#lsp-setup-without-installer)). AstroLSP also provides a simple `config` table in the plugin's options for extending the built in server configurations provided by `nvim-lspconfig`.
 
-```lua title="lua/plugins/astrolsp.lua"
+```lua title="lua/plugins/astrolsp.lua" {5-13}
 return {
   "AstroNvim/astrolsp",
   ---@type AstroLSPOpts
@@ -33,7 +33,7 @@ return {
 
 `nvim-lspconfig` is great, but it doesn't support all language servers that exist. You may want to set up a custom server where you manually define the `cmd` and the `root_dir`. This can also be done completely through `servers` and `config` tables similar to configuring servers that are supported by `nvim-lspconfig`! For these custom servers, the minimum requirement is defining a `cmd` in the `config` entry, but to get automatic starting of language servers you also need to set `filetypes` and `root_dir`. Here is a simple example setting up a Prolog LSP with `swipl`:
 
-```lua title="lua/plugins/astrolsp.lua"
+```lua title="lua/plugins/astrolsp.lua" {6-31}
 return {
   "AstroNvim/astrolsp",
   -- we need to use the function notation to get access to the `lspconfig` module
@@ -73,7 +73,7 @@ return {
 
 AstroNvim comes with [mason-lspconfig](https://github.com/williamboman/mason-lspconfig.nvim) as an easy interface for setting up and installing language servers, but this might not be adequate for all users. The LSP installer doesn't support all of the language servers that Neovim's LSP config supports and some users may already have the language servers installed on their machine and don't want to reinstall it separately. In these cases we have added an easy interface for setting up these servers. The following plugin specification for AstroLSP simply sets up `pyright` language server for a user with `pyright` already available on their system:
 
-```lua title="lua/plugins/astrolsp.lua"
+```lua title="lua/plugins/astrolsp.lua" {7-12}
 return {
   "AstroNvim/astrolsp",
   -- we must use the function override because table merging
@@ -84,6 +84,7 @@ return {
     opts.servers = opts.servers or {}
     vim.list_extend(opts.servers, {
       "pyright",
+      -- add more servers as needed...
     })
   end,
 }
@@ -93,7 +94,7 @@ return {
 
 AstroNvim has made formatting on save part of the default functionality out of the box. If you don't want your code to get auto formatted on save, you can disable it in the AstroLSP configuration:
 
-```lua title="lua/plugins/astrolsp.lua"
+```lua title="lua/plugins/astrolsp.lua" {6}
 return {
   "AstroNvim/astrolsp",
   ---@type AstroLSPOpts
@@ -107,7 +108,7 @@ return {
 
 We have also added an extension to just `true` or `false` for this option to give more the user the ability to disable the auto formatting for specific filetypes. For example:
 
-```lua title="lua/plugins/astrolsp.lua"
+```lua title="lua/plugins/astrolsp.lua" {6-12}
 return {
   "AstroNvim/astrolsp",
   ---@type AstroLSPOpts
@@ -127,7 +128,7 @@ return {
 
 If you would rather use a whitelist of filetypes for formatting on save rather than a blacklist type model, you can do that as well with the `allow_filetypes` table. If you have `allow_filetypes` it will take precedence over `ignore_filetypes`. So please only use one of these options at a time. Here is an example:
 
-```lua title="lua/plugins/astrolsp.lua"
+```lua title="lua/plugins/astrolsp.lua" {8-11}
 return {
   "AstroNvim/astrolsp",
   ---@type AstroLSPOpts
@@ -147,7 +148,7 @@ return {
 
 For even more control, you can provide a filter function with the key `filter`. This function takes a single parameter of the current buffer number and returns a boolean value of whether you want to format on save or not (`true` means format, `false` means do not format). This function will run on each save to calculate if it should format.
 
-```lua title="lua/plugins/astrolsp.lua"
+```lua title="lua/plugins/astrolsp.lua" {7-10}
 return {
   "AstroNvim/astrolsp",
   ---@type AstroLSPOpts
@@ -173,7 +174,7 @@ Since Neovim v0.8 there have been improvements to how language servers are used
 
 Using the `filter` option you can supply filter function to be run on each client that has formatting capabilities and if it returns `true` then it will be used for formatting and if it returns `false` then it will not be used. This applies to whenever you format your code either on save, with `<Leader>lf`, or with `:Format`.
 
-```lua title="lua/plugins/astrolsp.lua"
+```lua title="lua/plugins/astrolsp.lua" {6-19}
 return {
   "AstroNvim/astrolsp",
   ---@type AstroLSPOpts
@@ -202,7 +203,7 @@ return {
 
 Using the `disabled` option you can supply an array like list of language server client names and those clients will be disabled with you format your code either on save, with `<Leader>lf`, or with `:Format`.
 
-```lua title="lua/plugins/astrolsp.lua"
+```lua title="lua/plugins/astrolsp.lua" {6-9}
 return {
   "AstroNvim/astrolsp",
   ---@type AstroLSPOpts
@@ -221,7 +222,7 @@ return {
 
 When using the options together, a client listed in the `disabled` list will always be disabled and then all other clients will then be passed into the `filter` function. For example, we can simplify our previous `filter` function by just disabling the `lua_ls` client in the `disabled` table:
 
-```lua title="lua/plugins/astrolsp.lua"
+```lua title="lua/plugins/astrolsp.lua" {6-15}
 return {
   "AstroNvim/astrolsp",
   ---@type AstroLSPOpts
@@ -246,7 +247,7 @@ return {
 
 The `formatting` options also allows you to specify other parameters for the `vim.lsp.buf.format()` call. Any of the other formatting options are allowed to be used here to be used as the default options. This means being able to easily adjust the default `timeout_ms` for formatting in AstroNvim or making asynchronous formatting the default. For example you can do the following to increase the formatting timeout along with adjust the filtering:
 
-```lua title="lua/plugins/astrolsp.lua"
+```lua title="lua/plugins/astrolsp.lua" {6-7}
 return {
   "AstroNvim/astrolsp",
   ---@type AstroLSPOpts

src/content/docs/recipes/status.md

@@ -138,7 +138,7 @@ To build a component from the ground up, we can first start by selecting a `prov
 
 Using these options we can start building our component:
 
-```lua
+```lua {2-4}
 local status = require("astroui.status")
 local component = {
   provider = status.provider.mode_text({ padding = { left = 1, right = 1 } }),
@@ -147,23 +147,24 @@ local component = {
 
 This will give us a component where the text will be the current mode displayed as text. But now we want to be able to have the background of the mode to change colors along with the mode. This is where the `require("astronvim.utils.status").hl` module comes into play. There is a method there for getting the highlight for a mode with `require("astronvim.utils.status").hl.mode`. Each of these `hl` methods are designed to be passed in by name instead of resolving the function to the `hl` field in a Heirline component. For example, we can add the mode highlighting to our component as such:
 
-```lua
+```diff lang="lua"
 local status = require("astroui.status")
 local component = {
   provider = status.provider.mode_text({ padding = { left = 1, right = 1 } }),
-  hl = status.hl.mode,
++  hl = status.hl.mode,
 }
 ```
 
 This will give us a simple component where the background changes colors with each mode and displays the text of the current mode. If we want to make this component a bit prettier and add surrounding characters, we can use the `require("astronvim.utils.status").utils.surround` function with our component to do this. This surround method also handles setting the highlight group so we no longer need to set that inside of our component. An example of this would be:
 
-```lua
+```diff lang="lua"
 local status = require("astroui.status")
 local component = {
   provider = status.provider.mode_text({ padding = { left = 1, right = 1 } }),
+-  hl = status.hl.mode,
 }
-local surrounded_component =
-  status.utils.surround({ "", " " }, status.hl.mode_bg, component)
++local surrounded_component =
++  status.utils.surround({ "", " " }, status.hl.mode_bg, component)
 ```
 
 This function takes three parameters: the first parameter (left and right side respectively), the second parameter is the function for setting the color for the background of the component and the foreground of the separators, and the third parameter is the component that should be surrounded. In turn it gives us our final component that can be used inside of Heirline.
@@ -172,7 +173,7 @@ This function takes three parameters: the first parameter (left and right side r
 
 Building components from scratch is a powerful method that gives users complete control, but for the most part it's nice to have fully built components without having to think as much about what's going on internally. For this we have created several out of the box component building functions for things such as the mode, file details, git information, etc. With these, it becomes much easier to build components that you would want in your statusline. For example, to recreate our previous mode text component we can do this:
 
-```lua
+```lua {2-4}
 local status = require("astroui.status")
 local component = status.component.mode({
   mode_text = { padding = { left = 1, right = 1 } },
@@ -181,11 +182,11 @@ local component = status.component.mode({
 
 This will automatically set up the surrounding and colors that we want and defaults to it being a left aligned component. If you are going to place the component on the right side and want it to have the right side separators instead, you can do this:
 
-```lua
+```diff lang="lua"
 local status = require("astroui.status")
 local component = status.component.mode({
   mode_text = { padding = { left = 1, right = 1 } },
-  surround = { separator = "right" },
++  surround = { separator = "right" },
 })
 ```
 

src/content/docs/reference/autocmds.md

@@ -55,13 +55,16 @@ return {
     autocmds = {
       -- autocommands are organized into augroups for easy management
       autohidetabline = {
+        -- each augroup contains a list of auto commands
         {
           -- create a new autocmd on the "User" event
           event = "User",
-          desc = "Hide tabline when only one buffer and one tab", -- nice description
-          -- triggered when vim.t.bufs is updated
-          pattern = "AstroBufsUpdated", -- the pattern is the name of our User autocommand events
-          group = "autohidetabline", -- add the autocmd to the newly created augroup
+          -- the pattern is the name of our User autocommand events
+          pattern = "AstroBufsUpdated", -- triggered when vim.t.bufs is updated
+          -- nice description
+          desc = "Hide tabline when only one buffer and one tab",
+          -- add the autocmd to the newly created augroup
+          group = "autohidetabline",
           callback = function()
             -- if there is more than one buffer in the tab, show the tabline
             -- if there are 0 or 1 buffers in the tab, only show the tabline if there is more than one vim tab