### Setup and Get File Icon

Source: https://github.com/nvim-tree/nvim-web-devicons/blob/master/_autodocs/INDEX.md

Demonstrates the one-time setup for the plugin and how to retrieve an icon for a specific filename and extension.

```lua
-- Setup (one-time)
require('nvim-web-devicons').setup()

-- Get icon for a file in explorer
local icon, hl = require('nvim-web-devicons').get_icon("init.lua", "lua")
```

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

### Complete nvim-web-devicons Setup Example

Source: https://github.com/nvim-tree/nvim-web-devicons/blob/master/_autodocs/configuration.md

A comprehensive example demonstrating how to configure global overrides, filename overrides, extension overrides, OS overrides, and various display options like color_icons, default, strict, variant, and blend.

```lua
require('nvim-web-devicons').setup {
  -- Global overrides for any icon
  override = {
    zsh = {
      icon = "",
      color = "#428850",
      cterm_color = "65",
      name = "Zsh"
    }
  },

  -- Overrides for specific filenames
  override_by_filename = {
    [".gitignore"] = {
      icon = "",
      color = "#f1502f",
      name = "Gitignore"
    }
  },

  -- Overrides for file extensions
  override_by_extension = {
    ["log"] = {
      icon = "",
      color = "#81e043",
      name = "Log"
    }
  },

  -- Overrides for operating systems
  override_by_operating_system = {
    ["apple"] = {
      icon = "",
      color = "#A2AAAD",
      cterm_color = "248",
      name = "Apple"
    }
  },

  -- Color and display options
  color_icons = true,
  default = true,
  strict = true,
  variant = "dark",
  blend = 0
}
```

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

### Setup and Manual Refresh Example

Source: https://github.com/nvim-tree/nvim-web-devicons/blob/master/_autodocs/api-refresh.md

Demonstrates setting up the plugin for automatic refresh and manually calling refresh after changing the background or colorscheme.

```lua
local devicons = require('nvim-web-devicons')

-- Setup with automatic refresh on background change
devicons.setup()

-- Manually refresh after changing background
vim.o.background = "light"
devicons.refresh()

-- Manually refresh all highlights after changing colorscheme
vim.api.nvim_exec_autocmds("ColorScheme", {})
-- refresh() is called automatically via autocommand

-- Force refresh highlights if they become corrupted
devicons.refresh()

-- In a config, force theme to dark and refresh
devicons.setup { variant = "dark" }
devicons.refresh()  -- Reload with dark theme

-- Refresh after changing vim.o.background dynamically
local function toggle_background()
  if vim.o.background == "light" then
    vim.o.background = "dark"
  else
    vim.o.background = "light"
  end
  -- refresh() is called automatically, but you can force it:
  devicons.refresh()
end
```

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

### Import and Usage Example

Source: https://github.com/nvim-tree/nvim-web-devicons/blob/master/_autodocs/exported-symbols.md

Demonstrates how to import the nvim-web-devicons module and use its setup and get_icon functions.

```lua
local M = require('nvim-web-devicons')

-- Usage
M.setup()
local icon, hl = M.get_icon("file.lua", "lua")
```

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

### Setup nvim-web-devicons

Source: https://github.com/nvim-tree/nvim-web-devicons/blob/master/_autodocs/quick-reference.md

Call the setup function once to initialize the plugin. Options can be passed to customize icon behavior.

```lua
require('nvim-web-devicons').setup()
```

```lua
require('nvim-web-devicons').setup {
  color_icons = true,
  default = true,
  variant = "dark"
}
```

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

### Icon Usage Example

Source: https://github.com/nvim-tree/nvim-web-devicons/blob/master/_autodocs/types.md

Demonstrates how to use the Icon type for setup overrides, reconstructing Icon data from retrieved colors, and defining custom icons.

```lua
local lua_icon = {
  icon = "",
  color = "#51a0cf",
  cterm_color = "111",
  name = "Lua"
}

-- Used in setup overrides
require('nvim-web-devicons').setup {
  override = {
    lua = lua_icon
  }
}

-- Returned by get_icon_colors()
local icon, color, cterm = require('nvim-web-devicons').get_icon_colors("file.lua", "lua")
-- Can reconstruct Icon from parts:
local icon_data = {
  icon = icon,
  color = color,
  cterm_color = cterm,
  name = "Lua"
}

-- Create custom icon
require('nvim-web-devicons').set_icon {
  myformat = {
    icon = "⚙",
    color = "#FF6B6B",
    cterm_color = "196",
    name = "MyFormat"
  }
}
```

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

### Setup nvim-web-devicons with Custom Options

Source: https://github.com/nvim-tree/nvim-web-devicons/blob/master/_autodocs/configuration.md

Provide a table of options to the setup function to customize icon overrides, color highlighting, and lookup behavior.

```lua
require('nvim-web-devicons').setup({
  override = {
    ["my_custom_icon"] = { icon = "", color = "#ff0000" },
  },
  override_by_extension = {
    ["lua"] = { icon = "", color = "#0000ff" },
  },
  color_icons = true,
  default = true,
  strict = true,
  variant = "dark",
  blend = 50
})
```

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

### Setup Theme Variants

Source: https://github.com/nvim-tree/nvim-web-devicons/blob/master/_autodocs/quick-reference.md

Illustrates how to force dark or light themes, or to follow the system's background setting using the `setup` function.

```lua
-- Force dark theme
setup { variant = "dark" }

-- Force light theme
setup { variant = "light" }

-- Follow vim.o.background (default)
setup { variant = nil }
```

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

### Get All Icons

Source: https://github.com/nvim-tree/nvim-web-devicons/blob/master/_autodocs/INDEX.md

Provides an example of how to retrieve all defined icons and iterate through them.

```lua
-- Get all icons and iterate
for key, icon_data in pairs(require('nvim-web-devicons').get_icons()) do
  print(key .. ": " .. icon_data.icon)
end
```

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

### Install nvim-web-devicons with lazy.nvim

Source: https://github.com/nvim-tree/nvim-web-devicons/blob/master/README.md

Use this snippet to install the plugin with lazy.nvim.

```lua
{ "nvim-tree/nvim-web-devicons", opts = {} }
```

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

### Configure nvim-web-devicons Setup

Source: https://github.com/nvim-tree/nvim-web-devicons/blob/master/_autodocs/INDEX.md

Use the `setup()` function to configure nvim-web-devicons. This includes setting up icon overrides and display options. Refer to `configuration.md` for a complete option reference.

```lua
require('nvim-web-devicons').setup {
  -- Per-icon overrides by category
  override = { ... },
  override_by_filename = { ... },
  override_by_extension = { ... },

  -- Display options
  color_icons = true,        -- Enable per-icon colors
  default = false,           -- Return default if no match
  strict = false,            -- Strict lookup mode
  variant = nil,             -- "light", "dark", or follow background
  blend = nil                -- Highlight blend value
}
```

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

### Setup nvim-web-devicons

Source: https://github.com/nvim-tree/nvim-web-devicons/blob/master/_autodocs/README.md

Initialize the nvim-web-devicons plugin. This is the first step before using any other functions.

```lua
-- Setup
require('nvim-web-devicons').setup()
```

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

### Install nvim-web-devicons with packer.nvim

Source: https://github.com/nvim-tree/nvim-web-devicons/blob/master/README.md

Use this snippet to install the plugin with packer.nvim.

```lua
use 'nvim-tree/nvim-web-devicons'
```

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

### Has Loaded

Source: https://github.com/nvim-tree/nvim-web-devicons/blob/master/README.md

Checks if the `setup` function has already been called.

```APIDOC
## has_loaded

### Description
Checks if the `setup` function has already been called.

### Method
`require'nvim-web-devicons'.has_loaded()`

### Response
Returns `true` if setup has been called, `false` otherwise.
```

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

### Install luacheck with LuaRocks

Source: https://github.com/nvim-tree/nvim-web-devicons/blob/master/CONTRIBUTING.md

Install the luacheck linter locally using LuaRocks, the preferred method.

```sh
luarocks install --local luacheck
```

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

### Install nvim-web-devicons with vim-plug

Source: https://github.com/nvim-tree/nvim-web-devicons/blob/master/README.md

Use this snippet to install the plugin with vim-plug.

```vim
Plug 'nvim-tree/nvim-web-devicons'
```

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

### setup(opts)

Source: https://github.com/nvim-tree/nvim-web-devicons/blob/master/_autodocs/exported-symbols.md

Initializes the nvim-web-devicons plugin with optional configuration. This function must be called before using other functions in the module.

```APIDOC
## setup(opts)

### Description
Initialize the plugin with configuration options.

### Signature
`function(opts: table): void`

### Parameters
#### Path Parameters
- `opts` (table, optional): Configuration table

### Options
- `override` (table)
- `override_by_filename` (table)
- `override_by_extension` (table)
- `override_by_operating_system` (table)
- `override_by_desktop_environment` (table)
- `override_by_window_manager` (table)
- `color_icons` (boolean)
- `default` (boolean)
- `strict` (boolean)
- `variant` (string): "light" or "dark"
- `blend` (number)
```

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

### Setup and State Functions

Source: https://github.com/nvim-tree/nvim-web-devicons/blob/master/_autodocs/quick-reference.md

Functions for initializing the plugin, checking its loaded status, refreshing icons, and setting up highlights.

```APIDOC
## Function signatures

### Setup and state

```lua
setup(opts)                      -- Initialize with options
has_loaded() → bool              -- Check if initialized
refresh()                        -- Refresh icons/theme
set_up_highlights(allow_override)-- Register highlights
```
```

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

### Setup nvim-web-devicons with Custom Icons

Source: https://github.com/nvim-tree/nvim-web-devicons/blob/master/README.md

Configure the plugin to add custom icons, override existing ones, and set highlight group properties. This setup might need to be re-called if the colorscheme changes.

```lua
require'nvim-web-devicons'.setup {
 -- your personal icons can go here (to override)
 -- you can specify color or cterm_color instead of specifying both of them
 -- DevIcon will be appended to `name`
 override = {
  zsh = {
    icon = "",
    color = "#428850",
    cterm_color = "65",
    name = "Zsh"
  }
 };
 -- globally enable different highlight colors per icon (default to true)
 -- if set to false all icons will have the default icon's color
 color_icons = true;
 -- globally enable default icons (default to false)
 -- will get overriden by `get_icons` option
 default = true;
 -- globally enable "strict" selection of icons - icon will be looked up in
 -- different tables, first by filename, and if not found by extension; this
 -- prevents cases when file doesn't have any extension but still gets some icon
 -- because its name happened to match some extension (default to false)
 strict = true;
 -- set the light or dark variant manually, instead of relying on `background`
 -- (default to nil)
 variant = "light|dark";
 -- override blend value for all highlight groups :h highlight-blend.
 -- setting this value to `0` will make all icons opaque. in practice this means
 -- that icons width will not be affected by pumblend option (see issue #608)
 -- (default to nil)
 blend = 0;
 -- same as `override` but specifically for overrides by filename
 -- takes effect when `strict` is true
 override_by_filename = {
  [=".gitignore"=] = {
    icon = "",
    color = "#f1502f",
    name = "Gitignore"
  }
 };
 -- same as `override` but specifically for overrides by extension
 -- takes effect when `strict` is true
 override_by_extension = {
  ["log"] = {
    icon = "",
    color = "#81e043",
    name = "Log"
  }
 };
 -- same as `override` but specifically for operating system
 -- takes effect when `strict` is true
 override_by_operating_system = {
  ["apple"] = {
    icon = "",
    color = "#A2AAAD",
    cterm_color = "248",
    name = "Apple",
  },
 };
}
```

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

### Install luacheck with Pacman

Source: https://github.com/nvim-tree/nvim-web-devicons/blob/master/CONTRIBUTING.md

Install the luacheck linter using the Pacman package manager on Arch Linux.

```sh
pacman -S luacheck
```

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

### Install stylua with Pacman

Source: https://github.com/nvim-tree/nvim-web-devicons/blob/master/CONTRIBUTING.md

Install the stylua code formatter using the Pacman package manager on Arch Linux.

```sh
pacman -S stylua
```

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

### Setup

Source: https://github.com/nvim-tree/nvim-web-devicons/blob/master/_autodocs/quick-reference.md

Initializes the nvim-web-devicons module. It can be called with no arguments for default settings or with an options table to customize icon behavior.

```APIDOC
## setup

### Description
Initializes the nvim-web-devicons module. Accepts an optional table of options to customize its behavior.

### Method
`require('nvim-web-devicons').setup(options)

### Parameters
#### Options Table (Optional)
- **color_icons** (boolean) - If true, enables colored icons.
- **default** (boolean) - If true, enables default icons.
- **variant** (string) - Specifies the icon variant to use (e.g., "dark").

### Request Example
```lua
-- Minimal setup
require('nvim-web-devicons').setup()

-- With options
require('nvim-web-devicons').setup {
  color_icons = true,
  default = true,
  variant = "dark"
}
```
```

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

### Setup Options

Source: https://github.com/nvim-tree/nvim-web-devicons/blob/master/_autodocs/quick-reference.md

Configure nvim-web-devicons by setting various options to customize icon behavior, overrides, and theme variants.

```APIDOC
## Setup options

| Option                       | Type  | Default | Use                                   |
|------------------------------|-------|---------|---------------------------------------|
| `override`                   | table | {}      | Override any icon by name             |
| `override_by_filename`       | table | {}      | Override by exact filename            |
| `override_by_extension`      | table | {}      | Override by file extension            |
| `override_by_operating_system` | table | {}      | Override by OS name                   |
| `override_by_desktop_environment` | table | {}      | Override by DE name                   |
| `override_by_window_manager` | table | {}      | Override by WM name                   |
| `color_icons`                | bool  | true    | Enable per-icon colors                |
| `default`                    | bool  | false   | Return default when no match          |
| `strict`                     | bool  | false   | Search filename-first mode            |
| `variant`                    | string| nil     | Force light/dark theme                |
| `blend`                      | number| nil     | Highlight blend (0-100)               |
```

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

### Setup Options

Source: https://github.com/nvim-tree/nvim-web-devicons/blob/master/_autodocs/quick-reference.md

Configure nvim-web-devicons behavior using various options like overriding icons, enabling colors, and setting strict matching.

```lua
-- setup(opts)
-- Example usage (assuming setup function exists and is called elsewhere):
-- require('nvim-web-devicons').setup({
--   override = { ["my_file.txt"] = { icon = "", color = "#ff0000" } },
--   color_icons = true,
--   default = true
-- })
```

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

### Check if nvim-web-devicons is Loaded

Source: https://github.com/nvim-tree/nvim-web-devicons/blob/master/README.md

Verify if the plugin's setup function has already been executed.

```lua
require'nvim-web-devicons'.has_loaded()
```

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

### Function Signatures: Setup and State

Source: https://github.com/nvim-tree/nvim-web-devicons/blob/master/_autodocs/quick-reference.md

Functions for initializing the plugin, checking its loaded state, refreshing icons, and registering highlights.

```lua
setup(opts)                      -- Initialize with options
has_loaded() → bool              -- Check if initialized
refresh()                        -- Refresh icons/theme
set_up_highlights(allow_override)-- Register highlights
```

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

### Install stylua with Cargo

Source: https://github.com/nvim-tree/nvim-web-devicons/blob/master/CONTRIBUTING.md

Install the stylua code formatter using Cargo, the Rust package manager.

```sh
cargo install stylua
```

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

### Build Project with Make

Source: https://github.com/nvim-tree/nvim-web-devicons/blob/master/CONTRIBUTING.md

Run the main make command to install plugins, generate colors and variants, and perform style checks and linting.

```sh
make
```

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

### has_loaded()

Source: https://github.com/nvim-tree/nvim-web-devicons/blob/master/_autodocs/exported-symbols.md

Checks if the setup function has been called, indicating whether the plugin has been initialized.

```APIDOC
## has_loaded()

### Description
Check if setup has been called.

### Signature
`function(): boolean`

### Returns
- `true` if loaded, `false` otherwise
```

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

### Get Icon and Color with Default Fallback

Source: https://github.com/nvim-tree/nvim-web-devicons/blob/master/_autodocs/api-get-icon-color.md

Shows how to use the `default = true` option to get a fallback icon and color when no specific match is found for an unknown file extension.

```lua
-- Get icon and color with default fallback
local icon, color = devicons.get_icon_color("unknown.xyz", "xyz", { default = true })
```

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

### Configure filetype mappings in plugin setup

Source: https://github.com/nvim-tree/nvim-web-devicons/blob/master/_autodocs/api-set-icon-by-filetype.md

Set filetype icon mappings within a plugin's setup routine. This ensures mappings are applied when the plugin is initialized.

```lua
local devicons = require('nvim-web-devicons')

-- In a plugin setup
if vim.fn.exists('*my_plugin_setup') then
  devicons.set_icon_by_filetype {
    ["my_plugin"] = "lua",  -- Use Lua icon for my_plugin filetype
    ["another_type"] = "json"
  }
end
```

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

### Icon Definition Structure Example

Source: https://github.com/nvim-tree/nvim-web-devicons/blob/master/_autodocs/types.md

An example of an icon definition structure, highlighting that the 'name' field is distinct from the iconName type.

```lua
-- In icon data structure
local icon_def = {
  -- ... other fields ...
  name = "Lua"  -- This is a different concept; see Icon.name
}
```

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

### Setup with Dark Variant and Refresh

Source: https://github.com/nvim-tree/nvim-web-devicons/blob/master/_autodocs/api-refresh.md

Configures the plugin to use the dark variant and then manually refreshes the icons and highlights.

```lua
-- Change variant and refresh
require('nvim-web-devicons').setup { variant = "dark" }
require('nvim-web-devicons').refresh()
```

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

### has_loaded

Source: https://github.com/nvim-tree/nvim-web-devicons/blob/master/_autodocs/api-utility-functions.md

Checks if the nvim-web-devicons plugin has been initialized by calling setup(). Useful for preventing double initialization or ensuring the plugin is ready before use.

```APIDOC
## has_loaded

### Description
Returns whether `setup()` has been called and the plugin is initialized.

### Signature
`function M.has_loaded()`

### Return Values
- loaded (boolean): true if setup() has been called, false otherwise

### Example Usage
```lua
local devicons = require('nvim-web-devicons')

-- Check if already initialized
if not devicons.has_loaded() then
  devicons.setup()
end

-- Guard against double initialization
if devicons.has_loaded() then
  return  -- Already initialized
end
devicons.setup()
```
```

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

### set_up_highlights

Source: https://github.com/nvim-tree/nvim-web-devicons/blob/master/_autodocs/api-utility-functions.md

Manually registers Neovim highlight groups for all icons. This function is typically called automatically by `setup()` but can be invoked to refresh highlights, especially after a colorscheme change.

```APIDOC
## set_up_highlights

### Description
Registers Neovim highlight groups for all icons, setting up GUI colors (fg) and terminal colors (ctermfg).

This function is called automatically during `setup()` and is rarely needed manually.

### Signature
`function M.set_up_highlights(allow_override)`

### Parameters
- allow_override (boolean): Optional. If true, overrides existing highlights; if false, skips highlights that already exist. Defaults to false.

### Behavior
- If `color_icons = false` globally, only sets up the default icon's highlight.
- Iterates through all icons and registers a highlight group for each.
- Highlight group name is `DevIcon<name>` where `<name>` is the icon's name field.
- Skips icons without valid name or color fields.
- Skips icons where highlight group already exists unless `allow_override = true`.

### Example Usage
```lua
local devicons = require('nvim-web-devicons')

-- Automatic call during setup (no need to call manually)
devicons.setup()

-- Manual re-setup of all highlights
devicons.set_up_highlights(true)

-- Refresh highlights after loading a colorscheme that clears highlights
vim.cmd('colorscheme my_colorscheme')
require('nvim-web-devicons').set_up_highlights(true)
```
```

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

### Test Cterm Highlighting

Source: https://github.com/nvim-tree/nvim-web-devicons/blob/master/CONTRIBUTING.md

Start Neovim with TERM=xterm-256color to test cterm highlighting for icons.

```sh
TERM=xterm-256color nvim ...
```

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

### Render Multiple Icons with Colors

Source: https://github.com/nvim-tree/nvim-web-devicons/blob/master/_autodocs/api-get-icon-color.md

Demonstrates iterating through a list of files, getting the icon and color for each, and printing the icon (implicitly in its color) alongside the filename.

```lua
-- Combine multiple icons with their colors for UI rendering
local files = {"init.lua", "main.rs", "config.json"}
for _, file in ipairs(files) do
  local icon, color = devicons.get_icon_color(file)
  if icon then
    print(string.format("%s %s", icon, file))  -- Show icon in its color
  end
end
```

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

### Get Icon Function Call

Source: https://github.com/nvim-tree/nvim-web-devicons/blob/master/_autodocs/quick-reference.md

Demonstrates how to call the `get_icon` function with filename, filetype, and options for default and strict matching.

```lua
get_icon("file.lua", "lua", {
  default = true,  -- Return default if no match
  strict = true    -- Filename-first lookup
})
```

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

### Get All Icons

Source: https://github.com/nvim-tree/nvim-web-devicons/blob/master/_autodocs/quick-reference.md

Retrieve all defined icons, categorized by filename, extension, operating system, desktop environment, or window manager.

```lua
local devicons = require('nvim-web-devicons')

local all = devicons.get_icons()              -- Merged table
local by_filename = devicons.get_icons_by_filename()
local by_ext = devicons.get_icons_by_extension()
local by_os = devicons.get_icons_by_operating_system()
local by_de = devicons.get_icons_by_desktop_environment()
local by_wm = devicons.get_icons_by_window_manager()
```

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

### Get Icon Data Example

Source: https://github.com/nvim-tree/nvim-web-devicons/blob/master/_autodocs/quick-reference.md

Example of how to retrieve icon data, including specific icons by name and the default icon.

```APIDOC
## Get icon data

```lua
local devicons = require('nvim-web-devicons')

local icon_table = devicons.get_icons()
local lua_icon = icon_table["lua"]
-- {
--   icon = "",
--   color = "#51a0cf",
--   cterm_color = "111",
--   name = "Lua"
-- }

local default = devicons.get_default_icon()
local icon_name = devicons.get_icon_name_by_filetype("lua")
```
```

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

### Example Icon Structure in Lua

Source: https://github.com/nvim-tree/nvim-web-devicons/blob/master/CONTRIBUTING.md

Defines the required structure for adding an icon to the default icon tables. Ensure each key-value pair is on a new line.

```lua
[".gitconfig"] = { icon = "", color = "#41535b", cterm_color = "0", name = "GitConfig" },
```

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

### Get Icon for Lua Filetype

Source: https://github.com/nvim-tree/nvim-web-devicons/blob/master/_autodocs/api-get-icon-by-filetype.md

Retrieves the icon and highlight group for the 'lua' filetype. This is a basic usage example.

```lua
local devicons = require('nvim-web-devicons')

-- Get icon for Lua filetype
local icon, hl_group = devicons.get_icon_by_filetype("lua")
-- icon = ""
-- hl_group = "DevIconLua"
```

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

### Get Icon for C++ Filetype

Source: https://github.com/nvim-tree/nvim-web-devicons/blob/master/_autodocs/api-get-icon-by-filetype.md

Retrieves the icon for the 'cpp' filetype. Note that the highlight group is not explicitly shown in this commented example.

```lua
-- Get icon for C++ filetype
local icon, hl_group = devicons.get_icon_by_filetype("cpp")
-- icon = ""
```

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

### Get Filetype Icon

Source: https://github.com/nvim-tree/nvim-web-devicons/blob/master/_autodocs/INDEX.md

Shows how to get an icon based on the current buffer's filetype, commonly used in statuslines.

```lua
-- Get icon for current buffer's filetype in statusline
local icon = require('nvim-web-devicons').get_icon_by_filetype(vim.bo.filetype)
```

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

### Initialize nvim-web-devicons with Defaults

Source: https://github.com/nvim-tree/nvim-web-devicons/blob/master/_autodocs/api-setup.md

Call this function to initialize the plugin with default settings. It must be called before using other plugin functions.

```lua
require('nvim-web-devicons').setup()
```

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

### nvim-web-devicons Setup

Source: https://github.com/nvim-tree/nvim-web-devicons/blob/master/_autodocs/api-setup.md

Initializes the nvim-web-devicons plugin with user-provided configuration options. This function must be called before using other plugin functions. It loads icon tables, sets up Neovim highlight groups, and registers autocommands for colorscheme changes.

```APIDOC
## M.setup(opts)

### Description
Initializes the nvim-web-devicons plugin with user-provided configuration options. This function must be called before using other plugin functions. It loads icon tables based on the current or configured color variant, sets up Neovim highlight groups, creates autocommands for colorscheme changes, and registers the `:NvimWebDeviconsHiTest` command.

Calling `setup()` multiple times after initialization is idempotent and returns early if already loaded.

### Method
Lua Function

### Parameters
#### Function Parameters
- **opts** (table, optional, default: `{}`) - Configuration table with optional keys: `override`, `override_by_filename`, `override_by_extension`, `override_by_operating_system`, `override_by_desktop_environment`, `override_by_window_manager`, `color_icons`, `default`, `strict`, `variant`, `blend`

### Configuration options (opts table)
- **override** (table, optional, default: `{}`) - Global icon overrides applied to all icons. Keys are icon names, values are Icon tables.
- **override_by_filename** (table, optional, default: `{}`) - Override icons matched by exact filename (case-insensitive). Takes effect when `strict = true`.
- **override_by_extension** (table, optional, default: `{}`) - Override icons matched by file extension. Takes effect when `strict = true`.
- **override_by_operating_system** (table, optional, default: `{}`) - Override icons matched by operating system name.
- **override_by_desktop_environment** (table, optional, default: `{}`) - Override icons matched by desktop environment name.
- **override_by_window_manager** (table, optional, default: `{}`) - Override icons matched by window manager name.
- **color_icons** (boolean, optional, default: `true`) - Enable per-icon color highlighting. If false, all icons use the default icon's color.
- **default** (boolean, optional, default: `false`) - Enable returning a default icon when no specific match is found.
- **strict** (boolean, optional, default: `false`) - Enable strict icon lookup: check by filename first, then by extension. Prevents extension matches for files without extensions.
- **variant** (string, optional, default: `nil`) - Force a light or dark color variant: `"light"` or `"dark"`. If nil, uses `vim.o.background`.
- **blend** (number, optional, default: `nil`) - Set the blend value for all highlight groups (0-100). Affects icon opacity and interaction with `pumblend`.

### Side effects
- Calls `refresh_icons()` to load appropriate theme variant based on `opts.variant` or `vim.o.background`
- Calls `apply_user_icons()` to apply all overrides
- Calls `M.set_up_highlights()` to create Neovim highlight groups
- Registers an autocmd on `ColorScheme` event to re-apply highlights
- Registers an autocmd on `OptionSet background` event (via `refresh()` call)
- Creates the `:NvimWebDeviconsHiTest` user command
- Sets `loaded = true` flag to prevent re-initialization

### Request Example
```lua
-- Basic setup with defaults
require('nvim-web-devicons').setup()

-- Setup with custom icon overrides
require('nvim-web-devicons').setup {
  color_icons = true,
  default = true,
  strict = true,
  variant = "dark",
  override = {
    zsh = {
      icon = "",
      color = "#428850",
      cterm_color = "65",
      name = "Zsh"
    }
  },
  override_by_filename = {
    [".gitignore"] = {
      icon = "",
      color = "#f1502f",
      name = "Gitignore"
    }
  },
  override_by_extension = {
    ["log"] = {
      icon = "",
      color = "#81e043",
      name = "Log"
    }
  }
}

-- Setup with blend to make icons opaque
require('nvim-web-devicons').setup {
  color_icons = true,
  blend = 0
}

-- Setup with light variant
require('nvim-web-devicons').setup {
  variant = "light"
}
```

### Notes
- The variant is automatically updated when `vim.o.background` changes (unless explicitly set in opts)
- To change settings after setup, you must directly modify icon data or use the `set_icon()`, `set_default_icon()`, and `refresh()` functions
- Colorscheme changes trigger a re-application of highlights via the ColorScheme autocommand

### Related functions
- `M.has_loaded()` — Check if setup has been called
- `M.refresh()` — Manually refresh icons and highlights
- `M.set_icon()` — Override individual icons after setup
- `M.set_default_icon()` — Change the default icon after setup
```

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

### Function Signatures: Get by Filetype

Source: https://github.com/nvim-tree/nvim-web-devicons/blob/master/_autodocs/quick-reference.md

Retrieve icon information specifically by filetype. Supports getting icon, highlight name, color, and the icon's name.

```lua
get_icon_by_filetype(ft, opts) → icon, hl_name
get_icon_color_by_filetype(ft, opts) → icon, color
get_icon_colors_by_filetype(ft, opts) → icon, color, cterm_color
get_icon_cterm_color_by_filetype(ft, opts) → icon, cterm_color
get_icon_name_by_filetype(ft) → icon_name
```

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

### Example Usage of nvim-web-devicons Category Functions

Source: https://github.com/nvim-tree/nvim-web-devicons/blob/master/_autodocs/api-get-icons-by-category.md

Demonstrates how to use various get_icons_by_* functions to retrieve and process icon data for different categories. It shows iterating through filename, extension, and OS icons, accessing specific extension icons, and checking for support of certain environments.

```lua
local devicons = require('nvim-web-devicons')

-- Get all filename icons (like .gitignore, Dockerfile, etc)
local by_filename = devicons.get_icons_by_filename()
for filename, icon_data in pairs(by_filename) do
  print(string.format("File: %s -> %s", filename, icon_data.icon))
end

-- Get all extension icons
local by_ext = devicons.get_icons_by_extension()
local lua_icon = by_ext["lua"]
if lua_icon then
  print("Lua icon: " .. lua_icon.icon)
end

-- Get all OS icons
local by_os = devicons.get_icons_by_operating_system()
for os_name, icon_data in pairs(by_os) do
  print(string.format("OS: %s -> %s", os_name, icon_data.icon))
end

-- Get desktop environment icons
local by_de = devicons.get_icons_by_desktop_environment()
print("Available desktop environments: " .. vim.tbl_count(by_de))

-- Get window manager icons
local by_wm = devicons.get_icons_by_window_manager()
if by_wm["i3"] then
  print("i3 window manager is supported")
end

-- Check which extensions are available
local extensions = devicons.get_icons_by_extension()
local supported_exts = {}
for ext, _ in pairs(extensions) do
  table.insert(supported_exts, ext)
end
table.sort(supported_exts)
print("Supported extensions: " .. table.concat(supported_exts, ", "))
```

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

### Check Plugin Initialization Status

Source: https://github.com/nvim-tree/nvim-web-devicons/blob/master/_autodocs/api-utility-functions.md

Use `has_loaded()` to determine if the nvim-web-devicons plugin has been initialized by calling `setup()`. This is useful for guarding against double initialization or ensuring the plugin is ready before use.

```lua
local devicons = require('nvim-web-devicons')

-- Check if already initialized
if not devicons.has_loaded() then
  devicons.setup()
end

-- Guard against double initialization
if devicons.has_loaded() then
  return  -- Already initialized
end
devicons.setup()
```

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

### Conventional Commits Subject Examples

Source: https://github.com/nvim-tree/nvim-web-devicons/blob/master/CONTRIBUTING.md

Examples of valid Conventional Commits subjects for pull request titles. These are validated by the Semantic Pull Request Subject CI job.

```txt
feat: add gradle icons
fix: update rust icon
feat(#192): :NvimWebDeviconsHiTest
```

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

### Configure nvim-web-devicons with Custom Overrides

Source: https://github.com/nvim-tree/nvim-web-devicons/blob/master/_autodocs/api-setup.md

Set up the plugin with custom icon overrides for global, filename, and extension-based matching. This example also configures color icons, default icon behavior, strict matching, and a dark variant.

```lua
require('nvim-web-devicons').setup {
  color_icons = true,
  default = true,
  strict = true,
  variant = "dark",
  override = {
    zsh = {
      icon = "",
      color = "#428850",
      cterm_color = "65",
      name = "Zsh"
    }
  },
  override_by_filename = {
    [ ".gitignore" ] = {
      icon = "",
      color = "#f1502f",
      name = "Gitignore"
    }
  },
  override_by_extension = {
    ["log"] = {
      icon = "",
      color = "#81e043",
      name = "Log"
    }
  }
}
```

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

### Get Icon by Filetype for Statusline/Winbar

Source: https://github.com/nvim-tree/nvim-web-devicons/blob/master/_autodocs/INDEX.md

This snippet shows how to get an icon based on the current buffer's filetype, suitable for display in statuslines or winbars. It prints the icon and filetype if an icon is found.

```lua
local devicons = require('nvim-web-devicons')

-- Show icon for current file's filetype
local ft = vim.bo.filetype
local icon = devicons.get_icon_by_filetype(ft)
if icon then
  print(icon .. " " .. ft)
end
```

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

### SetupOptions for nvim-web-devicons

Source: https://github.com/nvim-tree/nvim-web-devicons/blob/master/_autodocs/types.md

Use this structure to configure icon mappings and behavior. Options like `override`, `color_icons`, `default`, `strict`, `variant`, and `blend` allow for fine-grained control over icon display.

```lua
{
  override = { [string] = Icon },              -- Optional
  override_by_filename = { [string] = Icon },  -- Optional
  override_by_extension = { [string] = Icon }, -- Optional
  override_by_operating_system = { [string] = Icon }, -- Optional
  override_by_desktop_environment = { [string] = Icon }, -- Optional
  override_by_window_manager = { [string] = Icon }, -- Optional
  color_icons = boolean,                        -- Optional, default: true
  default = boolean,                            -- Optional, default: false
  strict = boolean,                             -- Optional, default: false
  variant = "light" | "dark" | nil,            -- Optional, default: nil
  blend = number,                               -- Optional, default: nil
}
```

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

### Get All Icons

Source: https://github.com/nvim-tree/nvim-web-devicons/blob/master/_autodocs/README.md

Functions to retrieve comprehensive lists of icons.

```APIDOC
## get_icons()

### Description
Returns a merged table of all icons configured in the plugin.

### Signature
`get_icons()`

### Parameters
None
```

```APIDOC
## get_icons_by_filename()

### Description
Retrieves icons categorized by filename.

### Signature
`get_icons_by_filename()`

### Parameters
None
```

```APIDOC
## get_icons_by_extension()

### Description
Retrieves icons categorized by file extension.

### Signature
`get_icons_by_extension()`

### Parameters
None
```

```APIDOC
## get_icons_by_operating_system()

### Description
Retrieves icons categorized by operating system.

### Signature
`get_icons_by_operating_system()`

### Parameters
None
```

```APIDOC
## get_icons_by_desktop_environment()

### Description
Retrieves icons categorized by desktop environment.

### Signature
`get_icons_by_desktop_environment()`

### Parameters
None
```

```APIDOC
## get_icons_by_window_manager()

### Description
Retrieves icons categorized by window manager.

### Signature
`get_icons_by_window_manager()`

### Parameters
None
```

```APIDOC
## get_default_icon()

### Description
Retrieves the currently configured default icon.

### Signature
`get_default_icon()`

### Parameters
None
```

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

### Setup

Source: https://github.com/nvim-tree/nvim-web-devicons/blob/master/README.md

Initializes the nvim-web-devicons plugin. This function sets up all the necessary highlight groups for the devicons by calling `vim.api.nvim_set_hl` for each icon. It's recommended to re-call this function within your `Colorscheme` event to ensure highlights are reapplied if the color scheme changes.

```APIDOC
## setup

### Description
Initializes the nvim-web-devicons plugin, setting up highlight groups for all icons.
This might need to be re-called in a `Colorscheme` event if the color scheme changes.

### Method
`require'nvim-web-devicons'.setup(options)`

### Parameters
#### Options Table
- **override** (table) - Optional - Allows specifying custom icons to override default ones. Each entry can define `icon`, `color`, `cterm_color`, and `name`.
- **color_icons** (boolean) - Optional - Globally enables different highlight colors per icon. Defaults to `true`.
- **default** (boolean) - Optional - Globally enables default icons. Defaults to `false`.
- **strict** (boolean) - Optional - Enables strict icon selection, prioritizing filename then extension. Defaults to `false`.
- **variant** (string) - Optional - Manually sets the light or dark variant of icons. Defaults to `nil`.
- **blend** (number) - Optional - Overrides the blend value for all highlight groups. Setting to `0` makes icons opaque. Defaults to `nil`.
- **override_by_filename** (table) - Optional - Similar to `override`, but specifically for overrides by filename. Takes effect when `strict` is true.
- **override_by_extension** (table) - Optional - Similar to `override`, but specifically for overrides by extension. Takes effect when `strict` is true.
- **override_by_operating_system** (table) - Optional - Similar to `override`, but specifically for overrides by operating system. Takes effect when `strict` is true.

### Request Example
```lua
require'nvim-web-devicons'.setup {
  override = {
    zsh = {
      icon = "",
      color = "#428850",
      cterm_color = "65",
      name = "Zsh"
    }
  },
  color_icons = true,
  strict = true,
  override_by_filename = {
    [".gitignore"] = {
      icon = "",
      color = "#f1502f",
      name = "Gitignore"
    }
  },
  override_by_extension = {
    ["log"] = {
      icon = "",
      color = "#81e043",
      name = "Log"
    }
  },
  override_by_operating_system = {
    ["apple"] = {
      icon = "",
      color = "#A2AAAD",
      cterm_color = "248",
      name = "Apple"
    }
  }
}
```
```

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

### Get Icon by Filetype

Source: https://github.com/nvim-tree/nvim-web-devicons/blob/master/README.md

Retrieves the icon associated with a given filetype.

```APIDOC
## get_icon_by_filetype

### Description
Retrieves the icon associated with a given filetype.

### Method
`require("nvim-web-devicons").get_icon_by_filetype(filetype, opts)`

### Parameters
- **filetype** (string) - The filetype to get the icon for.
- **opts** (table, optional) - Options table.
```

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

### Configure nvim-web-devicons with Blend for Opacity

Source: https://github.com/nvim-tree/nvim-web-devicons/blob/master/_autodocs/api-setup.md

Initialize the plugin with custom icon overrides and set the blend option to 0 for opaque icons. This affects icon opacity and interaction with `pumblend`.

```lua
require('nvim-web-devicons').setup {
  color_icons = true,
  blend = 0
}
```

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

### Get Icon Name by Filetype

Source: https://github.com/nvim-tree/nvim-web-devicons/blob/master/README.md

Retrieves the icon name associated with a given filetype.

```APIDOC
## get_icon_name_by_filetype

### Description
Retrieves the icon name associated with a given filetype.

### Method
`require("nvim-web-devicons").get_icon_name_by_filetype(filetype)`

### Parameters
- **filetype** (string) - The filetype to get the icon name for.
```

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

### Get Icon Colors by Filetype

Source: https://github.com/nvim-tree/nvim-web-devicons/blob/master/README.md

Retrieves the icon colors associated with a given filetype.

```APIDOC
## get_icon_colors_by_filetype

### Description
Retrieves the icon colors associated with a given filetype.

### Method
`require("nvim-web-devicons").get_icon_colors_by_filetype(filetype, opts)`

### Parameters
- **filetype** (string) - The filetype to get the icon colors for.
- **opts** (table, optional) - Options table.
```

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

### Configure nvim-web-devicons with Light Variant

Source: https://github.com/nvim-tree/nvim-web-devicons/blob/master/_autodocs/api-setup.md

Set up the plugin to use the light color variant for icons. If not specified, the variant defaults to `vim.o.background`.

```lua
require('nvim-web-devicons').setup {
  variant = "light"
}
```

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

### Get Icon by Filename/Extension

Source: https://github.com/nvim-tree/nvim-web-devicons/blob/master/_autodocs/README.md

Functions to retrieve icon information based on filenames or file extensions.

```APIDOC
## get_icon(filename, options)

### Description
Retrieves the icon and its associated highlight group for a given filename.

### Signature
`get_icon(filename, options)`

### Parameters
- **filename** (string) - The name of the file.
- **options** (table, optional) - Additional options for icon retrieval.
```

```APIDOC
## get_icon_color(filename, options)

### Description
Retrieves the icon and its RGB color for a given filename.

### Signature
`get_icon_color(filename, options)`

### Parameters
- **filename** (string) - The name of the file.
- **options** (table, optional) - Additional options for icon retrieval.
```

```APIDOC
## get_icon_colors(filename, options)

### Description
Retrieves the icon, its RGB color, and its highlight group for a given filename.

### Signature
`get_icon_colors(filename, options)`

### Parameters
- **filename** (string) - The name of the file.
- **options** (table, optional) - Additional options for icon retrieval.
```

```APIDOC
## get_icon_cterm_color(filename, options)

### Description
Retrieves the icon and its terminal color (cterm) for a given filename.

### Signature
`get_icon_cterm_color(filename, options)`

### Parameters
- **filename** (string) - The name of the file.
- **options** (table, optional) - Additional options for icon retrieval.
```

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

### Get Icon Color by Filetype

Source: https://github.com/nvim-tree/nvim-web-devicons/blob/master/README.md

Retrieves the primary icon color associated with a given filetype.

```APIDOC
## get_icon_color_by_filetype

### Description
Retrieves the primary icon color associated with a given filetype.

### Method
`require("nvim-web-devicons").get_icon_color_by_filetype(filetype, opts)`

### Parameters
- **filetype** (string) - The filetype to get the icon color for.
- **opts** (table, optional) - Options table.
```

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

### Get Icon

Source: https://github.com/nvim-tree/nvim-web-devicons/blob/master/_autodocs/quick-reference.md

Retrieves an icon and its associated highlight group or color based on filename, extension, or filetype.

```APIDOC
## get_icon, get_icon_color, get_icon_colors, get_icon_by_filetype, get_icon_color_by_filetype

### Description
Functions to retrieve icons and their associated highlight groups or colors. Icons can be fetched by filename, extension, or filetype. Supports a default fallback icon.

### Methods
- `get_icon(filename, extension, options)`
- `get_icon_color(filename, extension, options)`
- `get_icon_colors(filename, extension, options)`
- `get_icon_by_filetype(filetype, options)`
- `get_icon_color_by_filetype(filetype, options)`

### Parameters
- **filename** (string) - The name of the file.
- **extension** (string) - The extension of the file.
- **filetype** (string) - The filetype of the file.
- **options** (table, optional) - Table of options. `default` (boolean) can be set to true to use a default fallback icon.

### Request Example
```lua
local devicons = require('nvim-web-devicons')

-- By filename/extension
local icon, hl = devicons.get_icon("init.lua", "lua")
local icon, color = devicons.get_icon_color("script.py", "py")
local icon, color, cterm = devicons.get_icon_colors("file.rs", "rs")

-- By filetype
local icon, hl = devicons.get_icon_by_filetype("lua")
local icon, color = devicons.get_icon_color_by_filetype("python")

-- With default fallback
local icon, hl = devicons.get_icon("unknown.xyz", "xyz", { default = true })
```
```

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

### nvim-web-devicons Setup with Overrides

Source: https://github.com/nvim-tree/nvim-web-devicons/blob/master/_autodocs/api-overview.md

Configure nvim-web-devicons with custom icon overrides and enable color icons and default icon fallback. Useful for defining specific icons for certain file types or names.

```lua
require('nvim-web-devicons').setup {
  override = {
    zsh = { icon = "", color = "#428850", cterm_color = "65", name = "Zsh" }
  },
  color_icons = true,
  default = true
}
```

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

### Get Icon Cterm Color by Filetype

Source: https://github.com/nvim-tree/nvim-web-devicons/blob/master/README.md

Retrieves the Cterm icon color associated with a given filetype.

```APIDOC
## get_icon_cterm_color_by_filetype

### Description
Retrieves the Cterm icon color associated with a given filetype.

### Method
`require("nvim-web-devicons").get_icon_cterm_color_by_filetype(filetype, opts)`

### Parameters
- **filetype** (string) - The filetype to get the Cterm icon color for.
- **opts** (table, optional) - Options table.
```

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

### Build Local Docker Image

Source: https://github.com/nvim-tree/nvim-web-devicons/blob/master/CONTRIBUTING.md

Build a Docker image for nvim-web-devicons locally.

```sh
docker build -t nvim-web-devicons:latest .
```

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

### Check Plugin Status

Source: https://github.com/nvim-tree/nvim-web-devicons/blob/master/_autodocs/quick-reference.md

Verify if the nvim-web-devicons plugin has been successfully loaded and initialized.

```lua
local devicons = require('nvim-web-devicons')

if devicons.has_loaded() then
  print("Plugin initialized")
end
```

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

### nvim-web-devicons Module Entry Point

Source: https://github.com/nvim-tree/nvim-web-devicons/blob/master/_autodocs/README.md

This is the primary module entry point for nvim-web-devicons. Ensure Neovim version 0.7.0 or higher and a Nerd Font version 3.3 or higher are installed.

```lua
require('nvim-web-devicons')
```

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

### Usage: Accessing Icons by Extension

Source: https://github.com/nvim-tree/nvim-web-devicons/blob/master/_autodocs/types.md

Demonstrates how to retrieve icon definitions based on file extensions and check for the existence of a specific extension's icon.

```lua
-- As a key in icon tables
local icons_by_ext = require('nvim-web-devicons').get_icons_by_extension()
if icons_by_ext["lua"] then
  print("Lua extension icon exists")
end
```

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

### Get Icon and Color for Lua File

Source: https://github.com/nvim-tree/nvim-web-devicons/blob/master/_autodocs/api-get-icon-color.md

Demonstrates how to retrieve the icon and its color for a Lua file. Asserts the expected empty icon and specific blue color.

```lua
local devicons = require('nvim-web-devicons')

-- Get icon and color for a Lua file
local icon, color = devicons.get_icon_color("init.lua", "lua")
assert(icon == "")
assert(color == "#51a0cf")  -- Blue
```