### Install LSP Server

Source: https://github.com/astronvim/astronvim/blob/main/README.md

Use the `:LspInstall` command followed by the server name to install a Language Server Protocol server. For example, `:LspInstall pyright` installs the Pyright server.

```vim
:LspInstall pyright
```

--------------------------------

### Ignore Configuration Example

Source: https://github.com/astronvim/astronvim/blob/main/_autodocs/TYPES.md

An example demonstrating how to configure ignored directories, filetypes, and buffer types.

```lua
ignore = {
  dirs = { "/tmp", "/var/tmp" },
  filetypes = { "gitcommit", "gitrebase" },
  buftypes = { "nofile", "prompt" }
}
```

--------------------------------

### Setup lazy.nvim and AstroNvim

Source: https://github.com/astronvim/astronvim/blob/main/_autodocs/README.md

Initializes lazy.nvim if not present and then configures AstroNvim with specified options. This setup is typically placed in `~/.config/nvim/init.lua`.

```lua
local lazypath = vim.fn.stdpath "data" .. "/lazy/lazy.nvim"
if not vim.uv.fs_stat(lazypath) then
  vim.fn.system { "git", "clone", "--filter=blob:none",
    "https://github.com/folke/lazy.nvim.git", "--branch=stable", lazypath }
end
vim.opt.rtp:prepend(lazypath)

require("lazy").setup({
  {
    "AstroNvim/AstroNvim",
    version = "^5",
    import = "astronvim.plugins",
    opts = {
      mapleader = " ",
      icons_enabled = true,
    }
  }
})
```

--------------------------------

### Specifying Build Steps for Plugins

Source: https://github.com/astronvim/astronvim/blob/main/_autodocs/PLUGIN_INITIALIZATION.md

Some plugins require build steps after installation or updates. This example shows how to specify a build command or a build function.

```lua
return {
  "nvim-treesitter/nvim-treesitter",
  build = ":TSUpdate",  -- Run :TSUpdate after install/update
}
```

```lua
{
  "AstroNvim/AstroNvim",
  build = function()
    -- Notify about pinned version updates
  end,
}
```

--------------------------------

### Install Debugger

Source: https://github.com/astronvim/astronvim/blob/main/README.md

Use the `:DapInstall` command followed by the debugger name to install a debugger. For example, `:DapInstall python` installs the Python debugger.

```vim
:DapInstall python
```

--------------------------------

### Install Language Server via Mason

Source: https://github.com/astronvim/astronvim/blob/main/_autodocs/README.md

Open the Mason interface to select and install desired language servers.

```vim
:Mason
" Then select and install desired language server
```

--------------------------------

### Install Language Parser

Source: https://github.com/astronvim/astronvim/blob/main/README.md

Use the `:TSInstall` command followed by the language name to install a Tree-sitter parser. For example, `:TSInstall python` installs the Python parser.

```vim
:TSInstall python
```

--------------------------------

### Essential AstroNvim Commands

Source: https://github.com/astronvim/astronvim/blob/main/_autodocs/QUICK_REFERENCE.md

These commands are useful for system checks, package management, and language server setup. Use `:Mason` to open the package manager UI and `:LspInstall` to install language servers.

```vim
:checkhealth astronvim     " Check system requirements
:Mason                     " Package manager UI
:LspInstall <language>     " Install language server
:TSInstall <language>      " Install treesitter parser
:DapInstall <debugger>     " Install debugger
:LspInfo                   " Show active language servers
:Lazy check                " Check for plugin updates
:Lazy update               " Update plugins
:AstroUpdate               " Update Lazy + Mason packages
```

--------------------------------

### M.setup()

Source: https://github.com/astronvim/astronvim/blob/main/_autodocs/api-reference/astronvim.md

A placeholder setup function that currently performs no operations. It is reserved for future use and can be overridden by lazy.nvim plugin configurations.

```APIDOC
## M.setup()

### Description
Placeholder setup function. Currently does nothing.

### Purpose
Reserved for future use or overrides by lazy.nvim plugin configuration.

### Method
`function M.setup()`

### Example:

```lua
local astronvim = require "astronvim"
astronvim.setup()  -- Safe to call; no-op in current implementation
```
```

--------------------------------

### Check Mason Package Installation Logs

Source: https://github.com/astronvim/astronvim/blob/main/_autodocs/QUICK_REFERENCE.md

If Mason packages fail to install, check the system for required tools like git and curl. Use `:MasonLog` to view detailed logs for troubleshooting.

```vim
:MasonLog " for details
```

--------------------------------

### Placeholder Setup Function

Source: https://github.com/astronvim/astronvim/blob/main/_autodocs/api-reference/astronvim.md

A placeholder setup function for AstroNvim. It is safe to call but currently performs no actions, reserved for future use or overrides by plugin configurations.

```lua
local astronvim = require "astronvim"
astronvim.setup()  -- Safe to call; no-op in current implementation
```

--------------------------------

### Post-Init Customization Example

Source: https://github.com/astronvim/astronvim/blob/main/_autodocs/PLUGIN_INITIALIZATION.md

After `astronvim.init()` completes, the merged configuration is accessible via `astronvim.config`. This allows for setting additional options or performing actions after initial plugin loading.

```lua
local astronvim = require "astronvim"
astronvim.init()

-- Now astronvim.config contains merged configuration
print(astronvim.config.mapleader)

-- Plugins are being loaded based on their triggers
-- User can now set additional options

```

--------------------------------

### Setup and Startup Deferral

Source: https://github.com/astronvim/astronvim/blob/main/_autodocs/api-reference/notify.md

Initializes the notify module and defers all `vim.notify` calls until a compatible notification plugin is loaded. This is used during AstroNvim initialization to prevent UI notifications during plugin setup.

```lua
local notify = require "astronvim.notify"
notify.setup()
notify.defer_startup()

-- All vim.notify calls here are queued
require "lazy".setup(specs)

-- Once lazy.nvim sets up a notification plugin that replaces vim.notify,
-- all queued notifications replay automatically
```

--------------------------------

### Backup Neovim Configuration (Linux/Mac OS)

Source: https://github.com/astronvim/astronvim/blob/main/README.md

Before installing AstroNvim, back up your existing Neovim configuration and data directories. This ensures you can revert to your previous setup if needed.

```shell
mv ~/.config/nvim ~/.config/nvim.bak
mv ~/.local/share/nvim ~/.local/share/nvim.bak
mv ~/.local/state/nvim ~/.local/state/nvim.bak
mv ~/.cache/nvim ~/.cache/nvim.bak
```

--------------------------------

### M.init()

Source: https://github.com/astronvim/astronvim/blob/main/_autodocs/api-reference/astronvim.md

Initializes AstroNvim by setting up configuration, notifications, and leader keys. This function is idempotent and performs essential setup tasks required for AstroNvim to function correctly.

```APIDOC
## M.init()

### Description
Initializes AstroNvim, setting up configuration, notifications, and leader keys.

### Method
`function M.init()`

### Behavior
1. Checks Neovim version >= 0.11.0; quits with error if too old
2. Returns early if `M.did_init` is already true (idempotent)
3. Sets up notification deferral via `astronvim.notify.setup()`
4. Retrieves plugin opts from lazy.nvim config
5. Auto-derives `pin_plugins` if not set (true if plugin.version exists)
6. Deep-extends M.config with lazy plugin options and user config
7. Sets global `mapleader` and `maplocalleader` if not already set
8. Sets global `icons_enabled` if icons are disabled

### Version Check:
- Requires `nvim-0.11` capability
- Displays error message and waits for user input before quitting if check fails

### Config Merge Order:
- Start: Default from `astronvim.config`
- Merge: lazy.nvim plugin opts (opts field from AstroNvim plugin spec)
- Merge: User config from init.lua (via lazy.nvim's opts_extend mechanism)
- Result: Final config in `M.config`

### Side Effects:
- Sets `vim.g.mapleader` (if not already set and mapleader configured)
- Sets `vim.g.maplocalleader` (if not already set and maplocalleader configured)
- Sets `vim.g.icons_enabled` (only if icons_enabled is false)
- Modifies `M.did_init` to true

### Example:

```lua
local astronvim = require "astronvim"
astronvim.init()

-- Now astronvim.config is fully merged and ready
print(astronvim.config.mapleader)  -- Output: " "
```
```

--------------------------------

### Plugin opts_extend Replace Example

Source: https://github.com/astronvim/astronvim/blob/main/_autodocs/TYPES.md

Demonstrates the behavior of regular 'opts' which replace default plugin configurations entirely, contrasting with 'opts_extend'.

```lua
-- Default
{plugin = {key2 = {a = 1, b = 2}}}

-- User
{plugin = {key2 = {c = 3}}}

-- Result (replaced)
{plugin = {key2 = {c = 3}}}
```

--------------------------------

### Custom Snapshot Management Example

Source: https://github.com/astronvim/astronvim/blob/main/_autodocs/api-reference/dev.md

Demonstrates how to generate a snapshot without writing, analyze plugin versions, and create a modified snapshot by filtering out specific plugins.

```lua
local dev = require "astronvim.dev"
local astrocore = require "astrocore"

-- Generate snapshot without writing
local snapshot = dev.generate_snapshot(false)

-- Analyze plugins
local versions = {}
for _, spec in ipairs(snapshot) do
  versions[spec[1]] = spec.version or spec.commit
end

-- Print summary
for name, version in pairs(versions) do
  print(string.format("%s: %s", name, version))
end

-- Custom write with modification
local modified_snapshot = {}
for _, spec in ipairs(snapshot) do
  if not spec[1]:match "test" then  -- Skip test plugins
    table.insert(modified_snapshot, spec)
  end
end
```

--------------------------------

### Update All Packages with Keybinding

Source: https://github.com/astronvim/astronvim/blob/main/_autodocs/README.md

Use this keybinding to initiate an update for all installed packages.

```vim
<Leader>pa
```

--------------------------------

### Version Pinning Example

Source: https://github.com/astronvim/astronvim/blob/main/_autodocs/api-reference/dev.md

Use version pinning for releases, allowing patch/minor updates. This requires the plugin to use semver tagging and is more stable for releases.

```lua
{ "author/plugin", version = "^1.2.3", optional = true }
```

--------------------------------

### Plugin opts_extend Merge Example

Source: https://github.com/astronvim/astronvim/blob/main/_autodocs/TYPES.md

Illustrates how the 'opts_extend' pattern merges default plugin options with user-provided configurations for a specific key.

```lua
-- Default
{plugin = {key1 = {a = 1, b = 2}}}

-- User
{plugin = {key1 = {c = 3}}}

-- Result (merged)
{plugin = {key1 = {a = 1, b = 2, c = 3}}}
```

--------------------------------

### Neovim LSP Server Management Commands

Source: https://github.com/astronvim/astronvim/blob/main/_autodocs/README.md

Commands for installing, inspecting, and debugging Neovim Language Server Protocol (LSP) servers.

```vim
:LspInstall <name>  " Install language server
:LspInfo            " Show LSP info
:LspLog             " Debug log
```

--------------------------------

### Conditionally Loading Plugins

Source: https://github.com/astronvim/astronvim/blob/main/_autodocs/PLUGIN_INITIALIZATION.md

Plugins can be loaded based on a condition. This example loads a plugin only if the Neovim version is 0.11 or higher.

```lua
return {
  "plugin-name",
  cond = function()
    return vim.fn.has "nvim-0.11" == 1
  end,
}
```

--------------------------------

### Install Treesitter Parsers

Source: https://github.com/astronvim/astronvim/blob/main/_autodocs/QUICK_REFERENCE.md

Use these commands to manage Treesitter parsers. Install missing parsers for specific languages or update all existing ones.

```vim
:TSInstall <language>   " Install missing parser
```

```vim
:TSUpdate               " Update all parsers
```

```vim
:TSLog                  " Show debug log
```

--------------------------------

### Extending AstroCore Configuration with opts_extend

Source: https://github.com/astronvim/astronvim/blob/main/_autodocs/CONFIGURATION.md

Example of extending the `treesitter.ensure_installed` configuration for AstroCore. This appends new languages to the default list.

```lua
-- In your init.lua
require("lazy").setup({
  "AstroNvim/AstroNvim",
  version = "^5",
  import = "astronvim.plugins",
  opts = {
    mapleader = " ",
  }
}, {
  spec = {
    {
      "AstroNvim/astrocore",
      opts = {
        treesitter = {
          ensure_installed = { "go", "rust", "typescript" },  -- Added to defaults
        }
      }
    }
  }
})

```

--------------------------------

### Initialize Lazy.nvim and AstroNvim

Source: https://github.com/astronvim/astronvim/blob/main/_autodocs/CONFIGURATION.md

This `init.lua` snippet sets up the Lazy.nvim package manager and initializes AstroNvim with custom options. It ensures Lazy.nvim is installed and then configures AstroNvim's core settings, including leader keys and icon enablement. It also includes a check to load user-specific configurations.

```lua
local lazypath = vim.fn.stdpath "data" .. "/lazy/lazy.nvim"
if not vim.uv.fs_stat(lazypath) then
  vim.fn.system { "git", "clone", "--filter=blob:none", 
    "https://github.com/folke/lazy.nvim.git", "--branch=stable", lazypath }
end
vim.opt.rtp:prepend(lazypath)

require("lazy").setup({
  {
    "AstroNvim/AstroNvim",
    version = "^5",
    import = "astronvim.plugins",
    opts = {
      mapleader = " ",
      maplocalleader = ",",
      icons_enabled = true,
    },
  },
}, {
  install = { colorscheme = { "astrotheme" } },
  checker = { enabled = true },
})

-- Load user configuration if it exists
local user_init = require("astronvim.config").config
if user_init then
  vim.notify("User configuration loaded", vim.log.levels.INFO)
end
```

--------------------------------

### Root Detection Configuration Example

Source: https://github.com/astronvim/astronvim/blob/main/_autodocs/TYPES.md

Configures how AstroNvim detects the project root directory using various methods like LSP, VCS markers, or project files.

```lua
---@type table[]
-- Example:
rooter.detector = {
  "lsp",                                    -- Detect from LSP
  { ".git", "_darcs", ".hg", ".bzr", ".svn" },  -- VCS markers
  { "lua", "MakeFile", "package.json" }    -- Project files
}
```

--------------------------------

### Install Language Server Configuration

Source: https://github.com/astronvim/astronvim/blob/main/_autodocs/QUICK_REFERENCE.md

Configure language servers for your projects. This snippet shows how to add servers like `pyright`, `lua_ls`, and `tsserver` to the AstroNvim configuration.

```lua
{
  "AstroNvim/astrolsp",
  opts = {
    servers = {
      pyright = {},      " Python
      lua_ls = {},       " Lua
      tsserver = {},     " TypeScript
    }
  }
}
```

--------------------------------

### Minimal AstroNvim init.lua Configuration

Source: https://github.com/astronvim/astronvim/blob/main/README.md

A minimal init.lua file to set up a base AstroNvim installation using lazy.nvim. This configuration imports AstroNvim and its default plugins.

```lua
local lazypath = vim.fn.stdpath "data" .. "/lazy/lazy.nvim"
if not vim.uv.fs_stat(lazypath) then
  -- 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(lazypath)

require("lazy").setup { "AstroNvim/AstroNvim", version = "^5", import = "astronvim.plugins" }
```

--------------------------------

### View AstroNvim Current Version

Source: https://github.com/astronvim/astronvim/blob/main/_autodocs/README.md

Execute this Lua command to display the currently installed version of AstroNvim.

```lua
:lua print(require("astronvim").version())
```

--------------------------------

### Lazy.nvim Plugin Specification Example

Source: https://github.com/astronvim/astronvim/blob/main/_autodocs/api-reference/plugins-overview.md

A standard lazy.nvim specification for defining plugin loading, dependencies, and configuration. Use this format when adding or customizing plugins.

```lua
return {
  "plugin-author/plugin-name",
  
  -- Lazy loading triggers
  event = "...",          -- Load on event
  cmd = { "..." },        -- Load on command
  
  -- Dependencies and integration
  dependencies = { ... },
  specs = { ... },        -- Add specs to other plugins
  
  -- Configuration
  opts = { ... },         -- Plugin options
  opts_extend = { ... },  -- Keys to extend (append) instead of replace
  
  -- Build and priority
  build = "...",          -- Run after install/update
  priority = 1000,        -- Load priority
}
```

--------------------------------

### Plugin Specification Example

Source: https://github.com/astronvim/astronvim/blob/main/_autodocs/README.md

Defines a plugin specification for lazy.nvim, including its name, event triggers, options, and potential extensions for other plugins.

```lua
return {
  "author/plugin-name",
  event = "...",
  opts = { ... },
  specs = { ... },  -- Extend other plugins
}
```

--------------------------------

### Configure Keyboard Chords with Which-key

Source: https://github.com/astronvim/astronvim/blob/main/_autodocs/QUICK_REFERENCE.md

Define custom key chords for actions. This example shows how to map a leader key sequence to quit all windows, with an optional description for Which-key integration.

```lua
-- Example: <Leader> + w + q = quit all
maps.n["<Leader>wq"] = { "<Cmd>qall<CR>", desc = "Quit all" }

-- Nested with Which-key:
maps.n["<Leader>w"] = { desc = "Window" }
maps.n["<Leader>wq"] = { "<Cmd>qall<CR>", desc = "Quit all" }
```

--------------------------------

### Configuring Plugin Mappings with the Specs System

Source: https://github.com/astronvim/astronvim/blob/main/_autodocs/PLUGIN_INITIALIZATION.md

The `specs` system allows merging configuration functions with existing plugin options. This example shows how to add custom mappings to astrocore.

```lua
specs = {
  {
    "AstroNvim/astrocore",
    opts = function(_, opts) 
      local maps = opts.mappings
      maps.n["<Leader>custom"] = { "<Cmd>custom<CR>", desc = "Custom" }
      return opts
    end
  }
}
```

--------------------------------

### Install AstroNvim Template

Source: https://github.com/astronvim/astronvim/blob/main/_autodocs/README.md

Clones the AstroNvim template repository to set up a new Neovim configuration. Ensure to remove the Git history of the template repository after cloning.

```bash
# Clone template
git clone https://github.com/AstroNvim/template ~/.config/nvim
rm -rf ~/.config/nvim/.git
vim
```

--------------------------------

### Access AstroNvim Modules

Source: https://github.com/astronvim/astronvim/blob/main/_autodocs/QUICK_REFERENCE.md

Examples of how to access core AstroNvim modules for version checking, plugin availability, options retrieval, buffer utilities, UI elements, and notification control.

```lua
-- Get AstroNvim version
local version = require("astronvim").version()

-- Check if plugin available
local available = require("astrocore").is_available("plugin-name")

-- Get plugin options
local opts = require("astrocore").plugin_opts("plugin-name")

-- Access buffer utilities
local valid = require("astrocore.buffer").is_valid(bufnr)
local large = require("astrocore.buffer").is_large(bufnr)

-- Get icon
local icon = require("astroui").get_icon("folder")

-- Pause/resume notifications
local notify = require("astronvim.notify")
notify.pause()
-- ... do work ...
notify.resume()
```

--------------------------------

### Plugin Spec Options Override

Source: https://github.com/astronvim/astronvim/blob/main/_autodocs/PLUGIN_INITIALIZATION.md

This example shows how plugin options provided in a lazy.nvim spec can override default configurations.

```lua
{
  "AstroNvim/AstroNvim",
  opts = {
    icons_enabled = false,
    custom_option = "value"
  }
}
```

--------------------------------

### Load Plugin on Command

Source: https://github.com/astronvim/astronvim/blob/main/_autodocs/PLUGIN_INITIALIZATION.md

This snippet ensures a plugin is loaded only when one of its associated commands is first invoked. For example, `:Mason` will trigger the `mason.nvim` plugin.

```lua
return {
  "mason.nvim",
  cmd = {
    "Mason",
    "MasonInstall",
    "MasonUninstall",
  }
}
```

--------------------------------

### Backup Neovim Configuration (Windows)

Source: https://github.com/astronvim/astronvim/blob/main/README.md

On Windows, back up your current Neovim and nvim-data folders using PowerShell. This is a crucial step before proceeding with the AstroNvim installation.

```powershell
Rename-Item -Path $env:LOCALAPPDATA\nvim -NewName $env:LOCALAPPDATA\nvim.bak
Rename-Item -Path $env:LOCALAPPDATA\nvim-data -NewName $env:LOCALAPPDATA\nvim-data.bak
```

--------------------------------

### Define Custom Key Mapping

Source: https://github.com/astronvim/astronvim/blob/main/_autodocs/QUICK_REFERENCE.md

Create custom key bindings for specific actions. This example defines a mapping for `<Leader>z` to display a test notification.

```lua
{
  "AstroNvim/astrocore",
  opts = function(_, opts) 
    local maps = opts.mappings
    maps.n["<Leader>z"] = {
      function() vim.notify "Test!" end,
      desc = "Test notification"
    }
    return opts
  end
}
```

--------------------------------

### Configure Blink.cmp for Fast Completion

Source: https://github.com/astronvim/astronvim/blob/main/_autodocs/api-reference/plugins-overview.md

Configure Blink.cmp for fast and fuzzy code completion with multiple sources. This setup is suitable for environments requiring quick access to LSP, snippets, and buffer completions.

```lua
{
  "saghen/blink.cmp",
  version = "^1",
  event = { "InsertEnter", "CmdlineEnter" },
  opts_extend = { "sources.default", "cmdline.sources", "term.sources" },
}
```

--------------------------------

### Configure Treesitter Language Parsers in AstroNvim

Source: https://github.com/astronvim/astronvim/blob/main/_autodocs/CONFIGURATION.md

Enable Treesitter for syntax highlighting and indentation. Configure auto-installation of parsers and specify languages to ensure are installed.

```lua
{
  "AstroNvim/astrocore",
  opts = {
    treesitter = {
      enabled = function(_, bufnr)
        return not require("astrocore.buffer").is_large(bufnr)
      end,
      highlight = true,            -- Enable syntax highlighting
      indent = true,               -- Enable indentation
      auto_install = true,         -- Auto-install missing parsers
      ensure_installed = {
        "bash", "c", "lua", "markdown", "python", "vim"
      },
    }
  }
}
```

--------------------------------

### Clone AstroNvim Template (Windows)

Source: https://github.com/astronvim/astronvim/blob/main/README.md

Clone the AstroNvim template repository to your local application data directory on Windows. Remove the .git directory and launch Neovim to complete the setup.

```powershell
git clone --depth 1 https://github.com/AstroNvim/template $env:LOCALAPPDATA\nvim
Remove-Item $env:LOCALAPPDATA\nvim\.git -Recurse -Force
vim
```

--------------------------------

### Lazy Configuration for nvim-lspconfig

Source: https://github.com/astronvim/astronvim/blob/main/_autodocs/api-reference/plugins-overview.md

This snippet configures the nvim-lspconfig plugin for language server protocol client setup. It specifies commands to trigger the plugin and an event for lazy loading.

```lua
{
  "neovim/nvim-lspconfig",
  cmd = { "LspInfo", "LspLog", "LspStart" },
  event = "User AstroFile",
}
```

--------------------------------

### Lazy Configuration for nvim-treesitter

Source: https://github.com/astronvim/astronvim/blob/main/_autodocs/api-reference/plugins-overview.md

This snippet shows the lazy loading configuration for the nvim-treesitter plugin. It specifies the plugin, its branch, when to load it, and a build command to run after installation.

```lua
{
  "nvim-treesitter/nvim-treesitter",
  branch = "main",
  event = "VeryLazy",
  build = ":TSUpdate",
}
```

--------------------------------

### Defer Startup Notifications

Source: https://github.com/astronvim/astronvim/blob/main/_autodocs/api-reference/notify.md

Pauses notifications and defers their resumption until `vim.notify` is replaced by a plugin or a 500ms timeout occurs. Ideal for preventing notifications during initial plugin setup.

```lua
local notify = require "astronvim.notify"
notify.setup()
notify.defer_startup()
-- Notifications deferred until a plugin replaces vim.notify or 500ms passes
```

--------------------------------

### Initialize Plugins with Lazy.nvim

Source: https://github.com/astronvim/astronvim/blob/main/_autodocs/PLUGIN_INITIALIZATION.md

Configure plugins by passing a table to `lazy.setup`. Use `import` to load plugins from a directory and `opts` to pass configuration. You can also specify plugin versions.

```lua
require("lazy").setup({
  {
    "AstroNvim/AstroNvim",
    version = "^5",
    import = "astronvim.plugins",
    opts = {
      mapleader = " ",
    }
  },
}, {
  spec = {
    -- Add/modify plugins here
    {
      "AstroNvim/astrocore",
      opts = {
        treesitter = {
          ensure_installed = { "go", "rust" }
        }
      }
    },
    -- Add custom plugins
    {
      "user/custom-plugin",
      opts = { ... }
    }
  }
})

```

--------------------------------

### Configure Leader and Local Leader Keys

Source: https://github.com/astronvim/astronvim/blob/main/_autodocs/KEYBINDINGS.md

Customize the global leader key (`mapleader`) and local leader key (`maplocalleader`) in your `init.lua` configuration. This example sets the leader key to space and the local leader key to comma.

```lua
opts = {
  mapleader = " ",
  maplocalleader = ",",
}
```

--------------------------------

### Integrate Custom Health Checks with AstroNvim

Source: https://github.com/astronvim/astronvim/blob/main/_autodocs/api-reference/health.md

Extend AstroNvim's health reporting by adding custom checks. This example shows how to start a custom health section and report status based on plugin availability.

```lua
-- In your init.lua or custom plugin config
local health = require("astronvim.health")
health.check()

-- Or extend with custom checks
vim.health.start("Custom checks")
if require("astrocore").is_available("my-plugin") then
  vim.health.ok("`my-plugin` is installed")
else
  vim.health.warn("`my-plugin` is not installed")
end
```

--------------------------------

### M.setup(notify?)

Source: https://github.com/astronvim/astronvim/blob/main/_autodocs/api-reference/notify.md

Initializes the pausable notification system by replacing `vim.notify`. It can optionally wrap an existing notification function.

```APIDOC
## M.setup(notify?)

### Description
Initializes the pausable notification system by replacing `vim.notify`.

### Parameters
#### Path Parameters
- **notify** (function?) - Optional - Original notification function to wrap; defaults to `vim.notify` if not provided

### Request Example
```lua
local notify = require "astronvim.notify"
notify.setup()  -- Use default vim.notify

-- or with custom notify function:
local custom_notifier = function(msg, level, opts)
  print(msg)
end
notify.setup(custom_notifier)
```
```

--------------------------------

### astronvim.init()

Source: https://github.com/astronvim/astronvim/blob/main/_autodocs/MANIFEST.txt

Initializes the AstroNvim environment. This is a core function for setting up AstroNvim.

```APIDOC
## astronvim.init()

### Description
Initialize AstroNvim. This function sets up the core environment and configurations.

### Method
`astronvim.init()`

### Parameters
None

### Response
None
```

--------------------------------

### astronvim.health.check()

Source: https://github.com/astronvim/astronvim/blob/main/_autodocs/MANIFEST.txt

Performs system requirement validation and checks the health of the AstroNvim installation.

```APIDOC
## astronvim.health.check()

### Description
Validate system requirements and check the overall health of the AstroNvim installation. This can help in troubleshooting.

### Method
`astronvim.health.check()`

### Parameters
None

### Response
- **results** (table) - A table containing the health check results.
```

--------------------------------

### Notification System API

Source: https://github.com/astronvim/astronvim/blob/main/_autodocs/README.md

Manages notifications within AstroNvim, allowing control over their flow and setup.

```APIDOC
## Notification System API

### Description
Manages notifications within AstroNvim, allowing control over their flow and setup.

### Functions
- **M.pause()** / **M.resume()** - Control notification flow
- **M.setup()** / **M.restore()** - Setup/teardown
- **M.defer_startup()** - Defer notifications during startup
```

--------------------------------

### AstroNvim Initialization

Source: https://github.com/astronvim/astronvim/blob/main/_autodocs/api-reference/astronvim.md

Initializes AstroNvim and demonstrates accessing the configured leader key for custom key mappings.

```lua
local astronvim = require "astronvim"
astronvim.init()

-- Access configured leader key
vim.api.nvim_set_keymap("n", astronvim.config.mapleader .. "w", ":w<CR>", { noremap = true })
```

--------------------------------

### Treesitter Parser Management Commands

Source: https://github.com/astronvim/astronvim/blob/main/_autodocs/README.md

Commands for installing and updating Treesitter parsers for syntax highlighting and analysis.

```vim
:TSInstall <lang>   " Install parser
:TSUpdate           " Update all parsers
:TSLog              " Debug log
```

--------------------------------

### Configure Rooter for Project Root Detection in AstroNvim

Source: https://github.com/astronvim/astronvim/blob/main/_autodocs/CONFIGURATION.md

Enable AstroCore's rooter to detect project root directories. Configure detectors, ignore lists for servers and directories, and scope.

```lua
{
  "AstroNvim/astrocore",
  opts = {
    rooter = {
      enabled = true,
      detector = { "lsp", { ".git", "_darcs", ".hg", ".bzr", ".svn" }, { "lua", "MakeFile", "package.json" } },
      ignore = {
        servers = {},              -- LSP servers to ignore
        dirs = {},                 -- Directories to ignore
      },
      autochdir = false,           -- Auto-change directory to root
      scope = "global",            -- "global" or "tabpage" scoped
      notify = false,              -- Notify on root change
    }
  }
}
```

--------------------------------

### Get Pending Notifications

Source: https://github.com/astronvim/astronvim/blob/main/_autodocs/api-reference/notify.md

Retrieve the queue of notifications that are waiting to be displayed. This function is useful for debugging or inspecting the state of the notification queue.

```lua
local notify = require "astronvim.notify"
notify.pause()
vim.notify("Test notification")
print(#notify.pending() .. " notifications queued")  -- Output: 1 notifications queued
```

--------------------------------

### M.defer_startup()

Source: https://github.com/astronvim/astronvim/blob/main/_autodocs/api-reference/notify.md

Pauses notifications and defers resumption until `vim.notify` is modified by a plugin or a timeout occurs.

```APIDOC
## M.defer_startup()

### Description
Pauses notifications and defers resumption until `vim.notify` is modified by a plugin or 500ms elapses.

### Use Case
Called during AstroNvim initialization to prevent notifications from interfering with plugin setup. Once plugins (like a notification plugin) replace `vim.notify`, notifications resume automatically.

### Request Example
```lua
local notify = require "astronvim.notify"
notify.setup()
notify.defer_startup()
-- Notifications deferred until a plugin replaces vim.notify or 500ms passes
```
```

--------------------------------

### Commit Pinning Example

Source: https://github.com/astronvim/astronvim/blob/main/_autodocs/api-reference/dev.md

Use commit pinning to lock to an exact commit, which is required if no version tag exists. This is typically used for development snapshots.

```lua
{ "author/plugin", commit = "abc123...", optional = true }
```

--------------------------------

### Get Neovim Version

Source: https://github.com/astronvim/astronvim/blob/main/_autodocs/api-reference/health.md

Execute the 'version' command in Neovim and extract the version string using a regular expression. This helps in verifying Neovim compatibility.

```vimscript
vim.fn.execute "version"
```

--------------------------------

### Add Language Parser with Treesitter

Source: https://github.com/astronvim/astronvim/blob/main/_autodocs/QUICK_REFERENCE.md

Use this snippet to ensure specific language parsers are installed for Treesitter. Add the desired language identifiers to the `ensure_installed` list.

```lua
{
  "AstroNvim/astrocore",
  opts = {
    treesitter = {
      ensure_installed = { "go", "rust" }
    }
  }
}
```

--------------------------------

### Show Which-key Bindings Documentation

Source: https://github.com/astronvim/astronvim/blob/main/_autodocs/QUICK_REFERENCE.md

To find documentation for key bindings, you can either wait for the Which-key menu to appear after pressing `<Leader>`, or use this command to directly show the documentation for the `which-key.nvim` plugin.

```vim
:Lazy show which-key.nvim
```

--------------------------------

### Configuring AstroCore Feature Flags

Source: https://github.com/astronvim/astronvim/blob/main/_autodocs/CONFIGURATION.md

Demonstrates how to configure AstroCore features, such as enabling `large_buf` with a specific size and toggling other features like `autopairs` and `cmp`.

```lua
{
  "AstroNvim/astrocore",
  opts = {
    features = {
      large_buf = { enabled = true, size = 1.5 * 1024 * 1024 },
      autopairs = true,
      cmp = true,
      diagnostics = true,
      highlighturl = true,
      notifications = true,
    }
  }
}

```

--------------------------------

### Initialize AstroNvim

Source: https://github.com/astronvim/astronvim/blob/main/_autodocs/api-reference/astronvim.md

Initializes AstroNvim by setting up configuration, notifications, and leader keys. It performs a Neovim version check and merges various configuration sources, including lazy.nvim plugin options and user configurations.

```lua
local astronvim = require "astronvim"
astronvim.init()

-- Now astronvim.config is fully merged and ready
print(astronvim.config.mapleader)  -- Output: " "
```

--------------------------------

### Configure Neo-tree.nvim for File Exploration

Source: https://github.com/astronvim/astronvim/blob/main/_autodocs/api-reference/plugins-overview.md

Configure Neo-tree.nvim to provide a robust file explorer with various data sources like filesystem, buffers, and git status. This is ideal for managing project files efficiently.

```lua
{
  "nvim-neo-tree/neo-tree.nvim",
  cmd = "Neotree",
  opts_extend = { "sources", "event_handlers" },
}
```

--------------------------------

### Initialize Notify System

Source: https://github.com/astronvim/astronvim/blob/main/_autodocs/api-reference/notify.md

Sets up the pausable notification system, optionally wrapping a custom notification function. This replaces the global `vim.notify`.

```lua
local notify = require "astronvim.notify"
notify.setup()  -- Use default vim.notify

-- or with custom notify function:
local custom_notifier = function(msg, level, opts)
  print(msg)  -- Custom implementation
end
notify.setup(custom_notifier)
```

--------------------------------

### Add Custom Key Binding

Source: https://github.com/astronvim/astronvim/blob/main/_autodocs/README.md

Defines a custom key binding for a specific command. This example maps `<Leader>custom` in normal mode to execute the `:custom` command.

```lua
{
  "AstroNvim/astrocore",
  opts = function(_, opts) 
    local maps = opts.mappings
    maps.n["<Leader>custom"] = { "<Cmd>custom<CR>", desc = "Custom" }
    return opts
  end
}
```

--------------------------------

### Load Plugin on Event

Source: https://github.com/astronvim/astronvim/blob/main/_autodocs/PLUGIN_INITIALIZATION.md

Configure a plugin to load automatically when a specific event fires, such as when a file is opened (`User AstroFile`) or after startup completes (`VeryLazy`).

```lua
return {
  "plugin-name",
  event = "User AstroFile"  -- Load when file opened
}
```

--------------------------------

### Configuration Merge Order Diagram

Source: https://github.com/astronvim/astronvim/blob/main/_autodocs/CONFIGURATION.md

Illustrates the flow of configuration application in AstroNvim, from default settings to the final merged configuration.

```text
Default Config
    ↓
    +─ Plugin Opts
    ↓
    +─ User Config
    ↓
    = Final Config
```

--------------------------------

### AstroNvim Custom Configuration Structure

Source: https://github.com/astronvim/astronvim/blob/main/_autodocs/QUICK_REFERENCE.md

Ensure your custom configuration follows this directory structure. The `init.lua` file must configure Lazy, and the `lua/user/init.lua` module is auto-loaded if it exists.

```directory
~/.config/nvim/ 
├── init.lua                " Must configure Lazy here
└── lua/user/init.lua      " User module (auto-loaded if exists)
```

--------------------------------

### Clone AstroNvim Template (Linux/Mac OS)

Source: https://github.com/astronvim/astronvim/blob/main/README.md

Clone the AstroNvim template repository to initialize your Neovim configuration. After cloning, remove the .git directory to prevent conflicts and then launch Neovim.

```shell
git clone --depth 1 https://github.com/AstroNvim/template ~/.config/nvim
rm -rf ~/.config/nvim/.git
vim
```

--------------------------------

### Configure LSP Servers

Source: https://github.com/astronvim/astronvim/blob/main/_autodocs/README.md

Sets up Language Server Protocol (LSP) servers for specific programming languages. This enables features like code completion, diagnostics, and go-to-definition.

```lua
{
  "AstroNvim/astrolsp",
  opts = {
    servers = {
      pyright = {},
      lua_ls = {},
    }
  }
}
```

--------------------------------

### Add Custom Mapping in AstroNvim

Source: https://github.com/astronvim/astronvim/blob/main/_autodocs/KEYBINDINGS.md

Extend the `opts.mappings` table to add a new custom keybinding for normal mode. This example shows how to bind `<Leader>z` to a custom Lua function.

```lua
{
  "AstroNvim/astrocore",
  opts = function(_, opts)నాలుగు
    local maps = opts.mappings
    -- Add custom mapping
    maps.n["<Leader>z"] = { function() vim.cmd("echo 'Custom!'") end, desc = "Custom action" }
    return opts
  end
}
```

--------------------------------

### AstroNvimOpts Configuration

Source: https://github.com/astronvim/astronvim/blob/main/_autodocs/TYPES.md

Defines the main configuration options for AstroNvim initialization. Use these to customize leader keys, icon rendering, and plugin pinning behavior.

```lua
---@class AstroNvimOpts
---@field mapleader string?
the leader key to map before setting up Lazy
---@field maplocalleader string?
the local leader key to map before setting up Lazy
---@field icons_enabled boolean?
whether to enable icons, default to `true`
---@field pin_plugins boolean?
whether to pin plugins or not, if `nil` then will pin if version is set.
```

--------------------------------

### Get AstroNvim Version

Source: https://github.com/astronvim/astronvim/blob/main/_autodocs/api-reference/astronvim.md

Retrieves the current AstroNvim version string. This function reads from `version.txt` and Git tags to provide detailed version information, including development status and commit hashes.

```lua
local astronvim = require "astronvim"
print(astronvim.version())  -- Output: v5.0.0-dev-15-g1a2b3c4d
```

--------------------------------

### Default Configuration Options

Source: https://github.com/astronvim/astronvim/blob/main/_autodocs/CONFIGURATION.md

Sets the default leader key, local leader key, and icon enablement status. This is the base configuration loaded by AstroNvim.

```lua
return {
  mapleader = " ",
  maplocalleader = ",",
  icons_enabled = true,
}
```

--------------------------------

### AstroCoreOpts Core Framework Options

Source: https://github.com/astronvim/astronvim/blob/main/_autodocs/TYPES.md

Represents the core framework options provided by the AstroCore plugin, extended by AstroNvim. This includes configurations for features, diagnostics, rooter, sessions, treesitter, autocmds, options, and mappings.

```lua
---@class AstroCoreOpts
---@field features table Feature enable/disable flags
---@field diagnostics table Diagnostic display configuration
---@field rooter table Project root detection settings
---@field sessions table Session auto-save configuration
---@field treesitter table Treesitter parser and feature configuration
---@field autocmds table Autocommand definitions
---@field options table Vim options/settings
---@field mappings table Key binding definitions
```

--------------------------------

### Configure Heirline.nvim for Statusline and Tabline

Source: https://github.com/astronvim/astronvim/blob/main/_autodocs/api-reference/plugins-overview.md

Set up Heirline.nvim to create customizable statuslines, tablines, and winbars. This plugin is useful for displaying vital information like mode, git branch, and file diagnostics.

```lua
{
  "rebelot/heirline.nvim",
  event = "BufEnter",
}
```

--------------------------------

### Lazy Configuration for Mason.nvim

Source: https://github.com/astronvim/astronvim/blob/main/_autodocs/api-reference/plugins-overview.md

This snippet configures the mason.nvim plugin, a package manager for language servers, formatters, linters, and debuggers. It specifies commands and options for extending registries.

```lua
{
  "mason-org/mason.nvim",
  cmd = { "Mason", "MasonInstall", "MasonUninstall", "MasonUninstallAll", "MasonLog" },
  opts_extend = { "registries" },
}
```

--------------------------------

### Declare Plugin Dependencies

Source: https://github.com/astronvim/astronvim/blob/main/_autodocs/PLUGIN_INITIALIZATION.md

Use this snippet to specify plugins that must be loaded before the main plugin. Optional dependencies can be marked with `optional = true`.

```lua
return {
  "plugin-name",
  dependencies = {
    "author/required-plugin",
    { "author/optional-plugin", optional = true },
  }
}
```

--------------------------------

### AstroNvim File Organization Structure

Source: https://github.com/astronvim/astronvim/blob/main/_autodocs/README.md

Illustrates the directory and file structure of the AstroNvim project.

```text
astronvim/
├── init.lua                          # Warning message (not for direct use)
├── lua/astronvim/
│   ├── init.lua                      # Main module
│   ├── config.lua                    # Default options
│   ├── notify.lua                    # Notification system
│   ├── health.lua                    # Health checks
│   ├── dev.lua                       # Developer utilities
│   ├── lazy_snapshot.lua             # Pinned versions (generated)
│   └── plugins/
│       ├── _astrocore.lua            # Core plugin config
│       ├── _astrolsp.lua             # LSP plugin config
│       ├── _astroui.lua              # UI plugin config
│       ├── _astrocore_*.lua          # Config specs
│       └── *.lua                     # Plugin configurations
├── version.txt                       # Version number
└── CHANGELOG.md                      # Release notes
```

--------------------------------

### Lazy Configuration for nvim-dap

Source: https://github.com/astronvim/astronvim/blob/main/_autodocs/api-reference/plugins-overview.md

This snippet configures the nvim-dap plugin, which provides Debug Adapter Protocol implementation with UI and REPL features. It's set up for lazy loading.

```lua
{
  "nvim-dap/nvim-dap",
  event = "User AstroFile",
}
```

--------------------------------

### Performance Profiling with Vim Commands

Source: https://github.com/astronvim/astronvim/blob/main/_autodocs/QUICK_REFERENCE.md

Use built-in Vim commands to profile editor performance and identify slow functions or startup bottlenecks. Results are logged to a file for analysis.

```vim
:profile start profile.log
:profile func *
" ... use editor normally ...
:profile stop
:e profile.log  " View results
```

```vim
:startuptime   " Show startup time breakdown
```

--------------------------------

### AstroNvim LSP Configuration Options

Source: https://github.com/astronvim/astronvim/blob/main/_autodocs/TYPES.md

Defines the structure for Language Server Protocol (LSP) configuration in AstroNvim. Use this to toggle LSP features, set server-specific configurations, and manage file operations.

```lua
---@class AstroLSPOpts
---@field features table LSP feature toggles
---@field config table Server-specific configurations
---@field defaults table Default LSP handler options
---@field file_operations table File operation timeout/settings
---@field formatting table Formatter configuration
---@field handlers table LSP handler overrides
---@field servers table Server configurations (extends)
---@field on_attach function? Custom on_attach callback
```

--------------------------------

### Dynamic Plugin Options with Functions

Source: https://github.com/astronvim/astronvim/blob/main/_autodocs/PLUGIN_INITIALIZATION.md

Use a function for plugin options to dynamically configure settings based on runtime conditions, such as checking global variables.

```lua
opts = function(_, opts)
  if vim.g.icons_enabled == false then
    opts.icons = false
  end
  return opts
end
```