### Minimal nvim-html-css Setup

Source: https://context7.com/jezda1337/nvim-html-css/llms.txt

Use this minimal setup for HTML files only, without configuring global stylesheets. Ensure the plugin is installed and `require("html-css").setup()` is called during Neovim startup.

```lua
-- Minimal setup — HTML only, no global stylesheets
require("html-css").setup({
  enable_on = { "html" },
})
```

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

### Full nvim-html-css Setup with Customizations

Source: https://context7.com/jezda1337/nvim-html-css/llms.txt

Configure the plugin for multiple file types, including remote CDN and local stylesheets, and enable all interactive handlers. This setup requires `require("html-css").setup()` to be called during Neovim startup.

```lua
-- Full setup — multiple file types, CDN + local stylesheets, all handlers enabled
require("html-css").setup({
  enable_on = {
    "html", "htmldjango",
    "tsx", "jsx",
    "erb", "svelte", "vue",
    "blade", "php", "templ", "astro",
  },
  handlers = {
    definition = { bind = "gd" },
    hover = {
      bind = "K",
      wrap = true,
      border = "none",      -- "none"|"single"|"double"|"rounded"|"shadow"
      position = "cursor",  -- "cursor" | "editor"
    },
  },
  documentation = { auto_show = true },
  peek = {
    enabled  = true,
    border   = "rounded",
    position = "center",   -- "center" | "cursor"
    width    = 0.5,        -- fraction of editor width
    height   = 0.5,        -- fraction of editor height
    focus    = true,
    style    = "minimal",
  },
  style_sheets = {
    -- Remote CDN stylesheet (fetched once and cached)
    "https://cdn.jsdelivr.net/npm/bootstrap@5.3.0/dist/css/bootstrap.min.css",
    "https://cdnjs.cloudflare.com/ajax/libs/bulma/1.0.3/css/bulma.min.css",
    -- Local path relative to cwd
    "./src/styles/main.css",
  },
  notify = false,  -- set true to log GET/PARSED events for debugging
})
```

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

### Install nvim-html-css with lazy.nvim

Source: https://github.com/jezda1337/nvim-html-css/blob/main/README.md

Configure lazy.nvim to install the nvim-html-css plugin and its dependencies. This snippet enables the plugin for various file types and customizes handlers, documentation, peek behavior, and stylesheets.

```lua
{
  "Jezda1337/nvim-html-css",
  dependencies = {
    "nvim-treesitter/nvim-treesitter",
  },
  opts = {
    enable_on = {
      "html",
      "htmldjango",
      "tsx",
      "jsx",
      "erb",
      "svelte",
      "vue",
      "blade",
      "php",
      "templ",
      "astro",
    },
    handlers = {
      definition = {
        bind = "gd"
      },
      hover = {
        bind = "K",
        wrap = true,
        border = "none",
        position = "cursor",
      },
    },
    documentation = {
      auto_show = true,
    },
    peek = {
      enabled = true,
      border = "rounded",
      position = "center",
      width = 0.5,
      height = 0.5,
      focus = true,
      style = "minimal",
    },
    style_sheets = {
      "https://cdn.jsdelivr.net/npm/bootstrap@5.3.0/dist/css/bootstrap.min.css",
      "https://cdnjs.cloudflare.com/ajax/libs/bulma/1.0.3/css/bulma.min.css",
      "./index.css", -- `./` refers to the current working directory.
    },
  },
}
```

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

### Setup Go to Definition Handler

Source: https://context7.com/jezda1337/nvim-html-css/llms.txt

Registers a keymap to jump to the CSS definition of a class or ID. Falls back to LSP definition if the cursor is not on a selector. Supports a picker for multiple definitions.

```lua
-- Configured via handlers.definition in setup():
require("html-css.definition").setup({ bind = "gd" })

-- Keymap behaviour:
-- Cursor on:  class="btn-primary"   → opens bootstrap.min.css at .btn-primary line
-- Cursor on:  class="my-custom"     → opens src/styles/main.css at .my-custom line
-- Multiple matches                  → vim.ui.select shows:
--                                      "main.css:14"
--                                      "tokens.css:3 [max-width: 768px]"
-- Not a CSS selector                → falls back to vim.lsp.buf.definition()
```

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

### Setup Neovim HTML & CSS Plugin

Source: https://github.com/jezda1337/nvim-html-css/blob/main/README.md

Configure the HTML & CSS support plugin for Neovim. Specify file types to enable support on, customize keybindings for definition and hover actions, enable auto-showing documentation, and configure peek window settings. Optionally, provide a list of external stylesheets for project-wide completions.

```lua
vim.pack.add({src="https://github.com/jezda1337/nvim-html-css"})
-- example
require("html-css").setup {
    enable_on = { "html" },
    -- if you want custom opt for handlers
    handlers = {
      definition = {
        bind = "gd"
      },
      hover = {
        bind = "K",
        wrap = true,
        border = "none",
        position = "cursor",
      },
    },
    documentation = {
        auto_show = true,
    },
    peek = {
        enabled = true,
        border = "rounded",
        position = "center",
        width = 0.5,
        height = 0.5,
        focus = true,
        style = "minimal",
    },
    style_sheets = {
        "https://cdn.jsdelivr.net/npm/bootstrap@5.3.0/dist/css/bootstrap.min.css",
        "https://cdnjs.cloudflare.com/ajax/libs/bulma/1.0.3/css/bulma.min.css",
    },
}
```

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

### Setup Hover Documentation Handler

Source: https://context7.com/jezda1337/nvim-html-css/llms.txt

Registers a keymap to display CSS definitions in a floating window. Appends hyphens to `iskeyword` for hyphenated class names. Falls back to LSP hover if no CSS definition is found.

```lua
-- Configured via handlers.hover in setup():
require("html-css.hover").setup({
  bind    = "K",
  wrap    = true,
  border  = "rounded",
  position = "cursor",   -- "cursor" uses relative="cursor"; anything else uses relative="editor"
})

-- Hovering over class="btn-primary" renders a float containing:
-- ```css
-- .btn-primary {
--   color: #fff;
--   background-color: #0d6efd;
--   border-color: #0d6efd;
-- }
-- ```
-- Media-wrapped classes are rendered as:
-- ```css
-- @media (max-width: 768px) {
--   .container {
--     padding: 0 1rem;
--   }
-- }
-- ```
```

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

### LSP.create_client

Source: https://context7.com/jezda1337/nvim-html-css/llms.txt

Creates or reuses the embedded html-css-lsp client and attaches it to a given buffer. The server handles completion, definition, hover, and more. It's typically started automatically.

```APIDOC
## LSP.create_client(opts, bufnr)

### Description
Creates (or reuses) the embedded `html-css-lsp` client and attaches it to the given buffer. The server is a pure-Lua in-process implementation that responds to `initialize`, `textDocument/completion`, `textDocument/definition`, `textDocument/hover`, `completionItem/resolve`, and `shutdown`. It is started automatically by the `BufEnter` autocmd; there is no need to call it manually.

### Parameters
* `opts` - Options for the LSP client.
* `bufnr` - The buffer number to attach the client to.

### Request Example
```lua
local LSP = require("html-css.lsp")
LSP.create_client(opts, vim.api.nvim_get_current_buf())
```
```

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

### Create Embedded HTML-CSS LSP Client

Source: https://context7.com/jezda1337/nvim-html-css/llms.txt

Creates or reuses the embedded html-css-lsp client and attaches it to a buffer. The server is started automatically by the BufEnter autocmd.

```lua
-- Manual client attachment (advanced — normally automatic)
local LSP = require("html-css.lsp")
LSP.create_client(opts, vim.api.nvim_get_current_buf())
```

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

### require("html-css").setup(opts)

Source: https://context7.com/jezda1337/nvim-html-css/llms.txt

The main entry point for configuring the nvim-html-css plugin. It merges user options with defaults, loads project-local configurations, and registers necessary Neovim autocmds to enable the embedded LSP and stylesheet discovery.

```APIDOC
## `require("html-css").setup(opts)`

### Description
The single entry point for the plugin. Merges user options with defaults, loads any project-local `.nvim.lua` configuration, registers `BufEnter`/`BufWritePre` autocmds that start the embedded LSP and trigger stylesheet discovery, and wires up all handlers. Must be called once during Neovim startup.

### Parameters
* `opts` (table) - Optional. A table containing configuration options for the plugin.
  * `enable_on` (table of strings) - Optional. List of file types to enable the plugin on.
  * `handlers` (table) - Optional. Configuration for interactive handlers.
    * `definition` (table) - Configuration for Go to Definition handler.
      * `bind` (string) - Keybinding for the handler.
    * `hover` (table) - Configuration for Hover documentation handler.
      * `bind` (string) - Keybinding for the handler.
      * `wrap` (boolean) - Whether to wrap text.
      * `border` (string) - Border style for the hover window.
      * `position` (string) - Position of the hover window.
  * `documentation` (table) - Optional. Configuration for documentation display.
    * `auto_show` (boolean) - Whether to automatically show documentation.
  * `peek` (table) - Optional. Configuration for the Peek floating CSS source viewer.
    * `enabled` (boolean) - Whether to enable the peek feature.
    * `border` (string) - Border style for the peek window.
    * `position` (string) - Position of the peek window.
    * `width` (number) - Width of the peek window as a fraction of editor width.
    * `height` (number) - Height of the peek window as a fraction of editor height.
    * `focus` (boolean) - Whether to focus the peek window.
    * `style` (string) - Style of the peek window.
  * `style_sheets` (table of strings) - Optional. List of global stylesheets (local paths or remote URLs) to index.
  * `notify` (boolean) - Optional. Enable notifications for GET/PARSED events for debugging.

### Request Example
```lua
-- Minimal setup — HTML only, no global stylesheets
require("html-css").setup({
  enable_on = { "html" },
})

-- Full setup — multiple file types, CDN + local stylesheets, all handlers enabled
require("html-css").setup({
  enable_on = {
    "html", "htmldjango",
    "tsx", "jsx",
    "erb", "svelte", "vue",
    "blade", "php", "templ", "astro",
  },
  handlers = {
    definition = { bind = "gd" },
    hover = {
      bind = "K",
      wrap = true,
      border = "none",      -- "none"|"single"|"double"|"rounded"|"shadow"
      position = "cursor",  -- "cursor" | "editor"
    },
  },
  documentation = { auto_show = true },
  peek = {
    enabled  = true,
    border   = "rounded",
    position = "center",   -- "center" | "cursor"
    width    = 0.5,        -- fraction of editor width
    height   = 0.5,        -- fraction of editor height
    focus    = true,
    style    = "minimal",
  },
  style_sheets = {
    -- Remote CDN stylesheet (fetched once and cached)
    "https://cdn.jsdelivr.net/npm/bootstrap@5.3.0/dist/css/bootstrap.min.css",
    "https://cdnjs.cloudflare.com/ajax/libs/bulma/1.0.3/css/bulma.min.css",
    -- Local path relative to cwd
    "./src/styles/main.css",
  },
  notify = false,  -- set true to log GET/PARSED events for debugging
})
```
```

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

### hover.setup

Source: https://context7.com/jezda1337/nvim-html-css/llms.txt

Registers a keymap to display hover documentation for CSS selectors.

```APIDOC
## `hover.setup(opts)` — Hover documentation handler

Registers a normal-mode keymap that displays the full formatted CSS block for the selector under the cursor in a floating markdown window. Appends `-` to `iskeyword` so hyphenated class names like `btn-primary` are treated as a single word. Falls back to `vim.lsp.buf.hover()` when no CSS definition is found.

### Parameters
- **opts** (table) - Configuration options.
  - **bind** (string) - The keymap to bind (e.g., `"K"`).
  - **wrap** (boolean) - Whether to wrap text in the hover window.
  - **border** (string) - The border style for the hover window (e.g., `"rounded"`).
  - **position** (string) - The position of the hover window (`"cursor"` or other). `"cursor"` uses `relative="cursor"`, anything else uses `relative="editor"`.

### Example
```lua
-- Configured via handlers.hover in setup():
require("html-css.hover").setup({
  bind    = "K",
  wrap    = true,
  border  = "rounded",
  position = "cursor",   -- "cursor" uses relative="cursor"; anything else uses relative="editor"
})

-- Hovering over class="btn-primary" renders a float containing:
-- ```css
-- .btn-primary {
--   color: #fff;
--   background-color: #0d6efd;
--   border-color: #0d6efd;
-- }
-- ```
-- Media-wrapped classes are rendered as:
-- ```css
-- @media (max-width: 768px) {
--   .container {
--     padding: 0 1rem;
--   }
-- }
-- ```
```

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

### definition.setup

Source: https://context7.com/jezda1337/nvim-html-css/llms.txt

Registers a keymap to jump to the definition of a CSS class or ID under the cursor.

```APIDOC
## `definition.setup(opts)` — Go to Definition handler

Registers a normal-mode keymap that jumps to the CSS file and line where the class or ID under the cursor is defined. If multiple definitions exist (e.g. the same class overridden in multiple files), a `vim.ui.select` picker is shown. Falls back to `vim.lsp.buf.definition()` when the word is not an HTML/CSS selector.

### Parameters
- **opts** (table) - Configuration options.
  - **bind** (string) - The keymap to bind (e.g., `"gd"`).

### Example
```lua
-- Configured via handlers.definition in setup():
require("html-css.definition").setup({ bind = "gd" })

-- Keymap behaviour:
-- Cursor on:  class="btn-primary"   → opens bootstrap.min.css at .btn-primary line
-- Cursor on:  class="my-custom"     → opens src/styles/main.css at .my-custom line
-- Multiple matches                  → vim.ui.select shows:
--                                      "main.css:14"
--                                      "tokens.css:3 [max-width: 768px]"
-- Not a CSS selector                → falls back to vim.lsp.buf.definition()
```
```

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

### Project-local configuration via `.nvim.lua`

Source: https://context7.com/jezda1337/nvim-html-css/llms.txt

Allows per-project configuration by placing a `.nvim.lua` file in the project root. This file's `vim.g.html_css` table is deep-merged with the global configuration, enabling project-specific stylesheets and file-type lists.

```APIDOC
## Project-local configuration via `.nvim.lua`

### Description
When a `.nvim.lua` file exists in the project root, `setup()` automatically `dofile()`s it and deep-merges the table stored in `vim.g.html_css` on top of the global config. This lets per-project stylesheets or file-type lists override the global Neovim configuration without changing it.

### Example Configuration (`.nvim.lua`)
```lua
-- .nvim.lua  (place in project root, e.g. ~/projects/my-app/.nvim.lua)
vim.g.html_css = {
  enable_on = { "html", "jsx", "tsx" },
  handlers = {
    definition = { bind = "gd" },
    hover = { bind = "K", wrap = true, border = "rounded", position = "cursor" },
  },
  documentation = { auto_show = true },
  peek = { enabled = true, position = "cursor" },
  style_sheets = {
    "./src/styles/global.css",
    "./src/styles/tokens.css",
    "https://cdn.jsdelivr.net/npm/tailwindcss@3/dist/tailwind.min.css",
  },
}
-- Expected effect: when Neovim opens any .html/.jsx/.tsx file inside this project,
-- the above stylesheets are indexed and completions become available immediately.
```
```

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

### parsers.css.setup

Source: https://context7.com/jezda1337/nvim-html-css/llms.txt

Parses a raw CSS string using Tree-sitter and returns structured CSS data. Optionally includes location information for selectors.

```APIDOC
## `parsers.css.setup(source_text, withLocation)` — CSS Tree-sitter parser

Parses a raw CSS string using Tree-sitter and returns a structured `CSS_Data` table containing all `.class` selectors, `#id` selectors, and `@import` paths. When `withLocation` is `true`, each selector carries an LSP `Range` used for Go to Definition.

### Parameters
- **source_text** (string) - The raw CSS string to parse.
- **withLocation** (boolean) - If true, includes LSP `Range` information for each selector.

### Returns
- `CSS_Data` table: A table containing `class`, `id`, and `imports`.
  - `class`: Table of class selectors.
  - `id`: Table of ID selectors.
  - `imports`: Table of `@import` paths.

### Example
```lua
local css_parser = require("html-css.parsers.css")

local css_source = [[ 
  .container { max-width: 1200px; margin: 0 auto; } 
  .btn-primary { color: #fff; background-color: #0d6efd; } 
  #main-header { font-size: 2rem; font-weight: bold; } 
  @media (max-width: 768px) { 
    .container { padding: 0 1rem; } 
  } 
]]

local data = css_parser.setup(css_source, true)
-- data.class[1] → { type="class", label="container", 
--                    block="{ max-width: 1200px; margin: 0 auto; }", 
--                    media=nil, kind=13, 
--                    range={ start={line=1,character=3}, ["end"]={line=1,character=12} } }
-- data.class[2] → { label="btn-primary", ... } 
-- data.class[3] → { label="container", media="(max-width: 768px)", ... } 
-- data.id[1]    → { type="id", label="main-header", block="{ font-size: 2rem; ... }", ... } 
-- data.imports  → {}   (populated when @import "file.css" rules are present) 
```
```

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

### Open CSS Source Peek Window

Source: https://context7.com/jezda1337/nvim-html-css/llms.txt

Trigger the CSS source peek functionality via a Neovim command or bind it to a keymap. The direct API allows for custom configuration of the peek window's appearance and behavior.

```lua
vim.cmd("HtmlCssPeek")
```

```lua
vim.keymap.set("n", "<leader>cp", "<cmd>HtmlCssPeek<CR>", { desc = "Peek CSS source" })
```

```lua
local peek = require("html-css.peek")
peek.open(
  {
    border   = "rounded",
    position = "center",   -- "center" | "cursor"
    width    = 0.6,        -- fraction of vim.o.columns
    height   = 0.4,        -- fraction of vim.o.lines
    style    = "minimal",
    focus    = true,
  },
  "/home/user/project/src/styles/main.css",
  { start = { line = 41, character = 0 }, ["end"] = { line = 41, character = 12 } }
)
```

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

### Configure blink.cmp for LSP

Source: https://github.com/jezda1337/nvim-html-css/blob/main/README.md

Ensure blink.cmp is configured to use the lsp source for LSP integration. This is necessary for the nvim-html-css plugin to function as an LSP server.

```lua
sources = {
  default = { "lsp", "path", "snippets", "buffer" },
}
```

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

### Project-local nvim-html-css Configuration

Source: https://context7.com/jezda1337/nvim-html-css/llms.txt

Override global Neovim configuration for specific projects by creating a `.nvim.lua` file in the project root. This allows per-project stylesheets and file-type lists to be applied automatically when Neovim opens files within that project.

```lua
-- .nvim.lua  (place in project root, e.g. ~/projects/my-app/.nvim.lua)
vim.g.html_css = {
  enable_on = { "html", "jsx", "tsx" },
  handlers = {
    definition = { bind = "gd" },
    hover = { bind = "K", wrap = true, border = "rounded", position = "cursor" },
  },
  documentation = { auto_show = true },
  peek = { enabled = true, position = "cursor" },
  style_sheets = {
    "./src/styles/global.css",
    "./src/styles/tokens.css",
    "https://cdn.jsdelivr.net/npm/tailwindcss@3/dist/tailwind.min.css",
  },
}
-- Expected effect: when Neovim opens any .html/.jsx/.tsx file inside this project,
-- the above stylesheets are indexed and completions become available immediately.
```

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

### Project-Specific nvim-html-css Configuration

Source: https://github.com/jezda1337/nvim-html-css/blob/main/README.md

Configure nvim-html-css settings on a per-project basis using a .nvim.lua file. This allows for customized settings for specific projects, overriding global configurations.

```lua
-- Project-specific HTML/CSS configuration
vim.g.html_css = {
  enable_on = { "html", "jsx" },  -- File types for this project only
  handlers = {
    definition = {
      bind = "gd"
    },
    hover = {
      bind = "K",
      wrap = true,
      border = "none",
      position = "cursor",
    }
  },
  documentation = {
    auto_show = true,
  },
  peek = {
    enabled = true,
    position = "cursor",
  },
  style_sheets = {
    -- Project-specific stylesheets
    "./src/styles/main.css",
    "./src/styles/components.css",
    "https://cdn.jsdelivr.net/npm/tailwindcss@2.2.19/dist/tailwind.min.css",
  }
}
```

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

### Fetch Stylesheets with Fetcher Module

Source: https://context7.com/jezda1337/nvim-html-css/llms.txt

Dispatches a stylesheet fetch to either a remote URL or a local file. It recursively resolves and fetches CSS @import chains.

```lua
local fetcher = require("html-css.fetcher")

-- Fetch a remote CDN stylesheet (non-blocking, result stored in cache)
fetcher:fetch(
  "https://cdn.jsdelivr.net/npm/bootstrap@5.3.0/dist/css/bootstrap.min.css",
  vim.api.nvim_get_current_buf(),
  true   -- notify = true → vim.notify("GET: <url>", INFO) on success
)

-- Fetch a local stylesheet; @import chains are followed automatically
fetcher:fetch(
  "/home/user/project/src/styles/main.css",
  vim.api.nvim_get_current_buf(),
  false
)

-- Resolve and fetch a list of @import paths relative to a parent file
fetcher:fetch_imports(
  { "./tokens.css", "../base/reset.css" },
  "/home/user/project/src/styles/main.css"
)
```

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

### Configure nvim-cmp for LSP

Source: https://github.com/jezda1337/nvim-html-css/blob/main/README.md

Ensure nvim-cmp is configured to use the nvim_lsp source for LSP integration. This is necessary for the nvim-html-css plugin to function as an LSP server.

```lua
sources = {
  { name = "nvim_lsp" },
  -- other sources...
}
```

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

### parsers.html.setup

Source: https://context7.com/jezda1337/nvim-html-css/llms.txt

Parses the active buffer for HTML/JSX content to extract stylesheet links and inline style blocks.

```APIDOC
## `parsers.html.setup(bufnr)` — HTML/JSX stylesheet extractor

Parses the active buffer with Tree-sitter (using the `html` parser for HTML/Vue/Svelte/Astro/ERB, or the `tsx` parser for JSX/TSX) and extracts: all `<link rel="stylesheet" href="...">` hrefs (local or remote), all inline `<style>` raw text blocks. The result feeds both the fetcher and the inline CSS parser.

### Parameters
- **bufnr** (integer) - The buffer number to parse.

### Returns
- A table containing `cdn` and `raw_text`.
  - `cdn`: Table of extracted stylesheet hrefs.
  - `raw_text`: String containing raw text from inline `<style>` blocks.

### Example
```lua
local html_parser = require("html-css.parsers.html")

-- Called automatically on BufEnter for enabled file types.
-- Manual usage (e.g. in a custom autocmd):
local data = html_parser.setup(vim.api.nvim_get_current_buf())

-- For an HTML file containing:
--   <link rel="stylesheet" href="./styles/main.css">
--   <link rel="stylesheet" href="https://cdn.example.com/lib.css">
--   <style>.hero { color: red; }</style>

-- data.cdn      → { "./styles/main.css", "https://cdn.example.com/lib.css" }
-- data.raw_text → ".hero { color: red; }"

-- For a JSX/TSX file containing:
--   import "./App.css"
--   import styles from "../shared/tokens.module.css"
-- data.cdn      → { "./App.css", "../shared/tokens.module.css" }
-- data.raw_text → ""
```
```

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

### Utility Functions for Path Resolution and CSS Formatting

Source: https://context7.com/jezda1337/nvim-html-css/llms.txt

The `utils` module provides functions for detecting remote/local paths, resolving paths relative to a base directory, extracting source names, and formatting CSS blocks into markdown. It also includes an asynchronous file reading function.

```lua
local utils = require("html-css.utils")

-- Detect source type
utils.is_remote("https://cdn.example.com/lib.css")  -- → true
utils.is_local("./src/styles/main.css")              -- → true
```

```lua
-- Resolve a path relative to a base directory, with public/static fallback
local abs = utils.resolve_path("./tokens.css", "/home/user/project/src/styles")
-- → "/home/user/project/src/styles/tokens.css"

local abs2 = utils.resolve_path("/assets/theme.css")
-- Tries: cwd/assets/theme.css, cwd/public/assets/theme.css, cwd/static/assets/theme.css
```

```lua
-- Extract a human-readable source name for completion item detail
utils.get_source_name("https://cdn.jsdelivr.net/npm/bootstrap@5.3.0/dist/css/bootstrap.min.css")
-- → "bootstrap.min"
utils.get_source_name("/home/user/project/src/styles/main.css")
-- → "main"
```

```lua
-- Format a Selector into a fenced markdown CSS block (used in hover/completion docs)
utils.format_css({
  label = "btn-primary",
  type  = "class",
  block = "{ color: #fff; background-color: #0d6efd; }",
  media = nil,
})
-- Returns:
-- "```css\n.btn-primary {\n  color: #fff;\n  background-color: #0d6efd;\n}\n```"
```

```lua
-- With media query:
utils.format_css({
  label  = "container",
  type   = "class",
  block  = "{ padding: 0 1rem; }",
  media  = "(max-width: 768px)",
})
-- Returns:
-- "```css\n@media (max-width: 768px) {\n  .container {\n    padding: 0 1rem;\n  }\n}\n```"
```

```lua
-- Async file read (libuv-based, callback receives full file content as string)
utils.read_file("/path/to/style.css", function(content)
  print(content)
end)
```

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

### Default nvim-html-css Configuration

Source: https://github.com/jezda1337/nvim-html-css/blob/main/README.md

The default configuration for the nvim-html-css plugin. This can be overridden by project-specific configurations.

```lua
{
  enable_on = { "html" },
  handlers = {
    definition = {
      bind = "gd"
    },
    hover = {
      bind = "K",
      wrap = true,
      border = "none",
      position = "cursor",
    }
  },
  documentation = {
    auto_show = true,
  },
  peek = {
    enabled = true,
    border = "rounded",
    position = "center", -- "center" | "cursor"
    width = 0.5,         -- fraction of editor width (0.0–1.0)
    height = 0.5,        -- fraction of editor height (0.0–1.0)
    focus = true,        -- whether the float steals focus on open
    style = "minimal",
  },
  style_sheets = {}
}
```

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

### utils module

Source: https://context7.com/jezda1337/nvim-html-css/llms.txt

Provides utility functions for path resolution, remote/local file detection, asynchronous file reading, and CSS block formatting, used internally by other plugin features.

```APIDOC
## `utils` — path resolution and CSS formatting helpers

Internal utility module exposing path resolution, remote/local detection, async file reading, and the CSS block formatter used by both hover and completion documentation.

```lua
local utils = require("html-css.utils")

-- Detect source type
utils.is_remote("https://cdn.example.com/lib.css")  -- → true
utils.is_local("./src/styles/main.css")              -- → true

-- Resolve a path relative to a base directory, with public/static fallback
local abs = utils.resolve_path("./tokens.css", "/home/user/project/src/styles")
-- → "/home/user/project/src/styles/tokens.css"

local abs2 = utils.resolve_path("/assets/theme.css")
-- Tries: cwd/assets/theme.css, cwd/public/assets/theme.css, cwd/static/assets/theme.css

-- Extract a human-readable source name for completion item detail
utils.get_source_name("https://cdn.jsdelivr.net/npm/bootstrap@5.3.0/dist/css/bootstrap.min.css")
-- → "bootstrap.min"
utils.get_source_name("/home/user/project/src/styles/main.css")
-- → "main"

-- Format a Selector into a fenced markdown CSS block (used in hover/completion docs)
utils.format_css({
  label = "btn-primary",
  type  = "class",
  block = "{ color: #fff; background-color: #0d6efd; }",
  media = nil,
})
-- Returns:
-- "```css\n.btn-primary {\n  color: #fff;\n  background-color: #0d6efd;\n}\n```"

-- With media query:
utils.format_css({
  label  = "container",
  type   = "class",
  block  = "{ padding: 0 1rem; }",
  media  = "(max-width: 768px)",
})
-- Returns:
-- "```css\n@media (max-width: 768px) {\n  .container {\n    padding: 0 1rem;\n  }\n}\n```"

-- Async file read (libuv-based, callback receives full file content as string)
utils.read_file("/path/to/style.css", function(content)
  print(content)
end)
```
```

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

### health.check()

Source: https://context7.com/jezda1337/nvim-html-css/llms.txt

Implements Neovim's `:checkhealth html-css` interface to verify plugin health, including the presence and version of `curl` and internet reachability.

```APIDOC
## `health.check()` — plugin health report

Implements Neovim's `:checkhealth html-css` interface. Verifies that `curl` is present on `$PATH`, that its major version is 8, and that the internet is reachable.

```lua
-- Run from Neovim command line:
-- :checkhealth html-css

-- Produces output like:
-- nvim-html-css report
--   OK  curl found on path
--   OK  curl version is good          (curl 8.7.1 ...)
--   OK  site is accessible

-- On failure:
--   ERROR  curl not found on path
--   ERROR  curl must be 8.x.x, but got 7.88.0
--   ERROR  site is not accessible
```
```

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

### Bind :HtmlCssPeek command

Source: https://github.com/jezda1337/nvim-html-css/blob/main/README.md

Set a custom keybinding for the :HtmlCssPeek command to quickly open CSS source files in a floating window.

```lua
vim.keymap.set("n", "<leader>cp", "<cmd>HtmlCssPeek<CR>", { desc = "Peek CSS source" })
```

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

### Manage Cache Sources and Cleanup

Source: https://context7.com/jezda1337/nvim-html-css/llms.txt

Checks if a remote source has already been fetched and links sources to a buffer. Also provides a function to clean up cache entries for a closed buffer.

```lua
local cache = require("html-css.cache")

-- Check if a remote source has already been fetched (prevents duplicate curl calls)
local already_fetched = cache:has_source(
  "https://cdn.jsdelivr.net/npm/bootstrap@5.3.0/dist/css/bootstrap.min.css"
)  -- → true / false

-- Register which sources belong to a buffer (called automatically after fetch)
cache:link_sources(bufnr, {
  "/home/user/project/src/styles/global.css",
  "https://cdn.jsdelivr.net/npm/bootstrap@5.3.0/dist/css/bootstrap.min.css",
})

-- Free all cache entries for a closed buffer
cache:cleanup(bufnr)  -- called automatically via BufDelete autocmd
```

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

### fetcher:fetch

Source: https://context7.com/jezda1337/nvim-html-css/llms.txt

Dispatches a stylesheet fetch to either `_fetch_remote` or `_fetch_local`. It parses the CSS content, stores it in the cache, and recursively resolves `@import` chains.

```APIDOC
## fetcher:fetch(source, bufnr, notify)

### Description
Dispatches a stylesheet fetch to either `_fetch_remote` (via async `curl`) or `_fetch_local` (via async `uv.fs_open`). After parsing the CSS content with the Tree-sitter CSS parser, it stores the result in the shared cache. CSS `@import` chains are resolved and fetched recursively through `_process_imports`.

### Parameters
* `source` - The URL or path of the stylesheet to fetch.
* `bufnr` - The buffer number associated with the stylesheet.
* `notify` - A boolean indicating whether to notify the user on success.

### Request Example
```lua
local fetcher = require("html-css.fetcher")

-- Fetch a remote CDN stylesheet
fetcher:fetch("https://cdn.jsdelivr.net/npm/bootstrap@5.3.0/dist/css/bootstrap.min.css", vim.api.nvim_get_current_buf(), true)

-- Fetch a local stylesheet
fetcher:fetch("/home/user/project/src/styles/main.css", vim.api.nvim_get_current_buf(), false)
```
```

```APIDOC
## fetcher:fetch_imports(paths, parent_path)

### Description
Resolves and fetches a list of `@import` paths relative to a parent file.

### Parameters
* `paths` - A list of import paths.
* `parent_path` - The path of the parent file from which the imports are relative.

### Request Example
```lua
local fetcher = require("html-css.fetcher")
fetcher:fetch_imports({ "./tokens.css", "../base/reset.css" }, "/home/user/project/src/styles/main.css")
```
```

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

### :HtmlCssPeek user command / peek.open(cfg, filepath, range)

Source: https://context7.com/jezda1337/nvim-html-css/llms.txt

Registers the :HtmlCssPeek command to resolve LSP definitions for selectors and open the CSS source file in an editable floating window. The window closes on 'q'/'Esc' or 'WinLeave', but not if the buffer has unsaved changes.

```APIDOC
## :HtmlCssPeek user command / peek.open(cfg, filepath, range) — CSS source peek

Registers the `:HtmlCssPeek` command (when `peek.enabled = true`). Executing it resolves the LSP definition for the selector under the cursor, then opens the CSS source file in an editable floating window positioned at the exact definition line. The window closes on `q`/`<Esc>` or `WinLeave`, but refuses to close if the buffer has unsaved changes.

```lua
-- Trigger via command:
vim.cmd("HtmlCssPeek")

-- Or bind in your own config:
vim.keymap.set("n", "<leader>cp", "<cmd>HtmlCssPeek<CR>", { desc = "Peek CSS source" })

-- Direct API (advanced):
local peek = require("html-css.peek")
peek.open(
  {
    border   = "rounded",
    position = "center",   -- "center" | "cursor"
    width    = 0.6,        -- fraction of vim.o.columns
    height   = 0.4,        -- fraction of vim.o.lines
    style    = "minimal",
    focus    = true,
  },
  "/home/user/project/src/styles/main.css",
  { start = { line = 41, character = 0 }, ["end"] = { line = 41, character = 12 } }
)
-- Opens a float displaying main.css, cursor centred on line 42.
-- Keys inside float: q / <Esc> → close (only if no unsaved changes)
```
```

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

### Parse CSS with Tree-sitter

Source: https://context7.com/jezda1337/nvim-html-css/llms.txt

Parses raw CSS strings to extract class selectors, ID selectors, and @import paths. Set `withLocation` to true to include LSP `Range` for Go to Definition.

```lua
local css_parser = require("html-css.parsers.css")

local css_source = [[
  .container { max-width: 1200px; margin: 0 auto; }
  .btn-primary { color: #fff; background-color: #0d6efd; }
  #main-header { font-size: 2rem; font-weight: bold; }
  @media (max-width: 768px) {
    .container { padding: 0 1rem; }
  }
]]

local data = css_parser.setup(css_source, true)
-- data.class[1] → { type="class", label="container",
--                    block="{ max-width: 1200px; margin: 0 auto; }",
--                    media=nil, kind=13,
--                    range={ start={line=1,character=3}, ["end"]={line=1,character=12} } }
-- data.class[2] → { label="btn-primary", ... }
-- data.class[3] → { label="container", media="(max-width: 768px)", ... }
-- data.id[1]    → { type="id", label="main-header", block="{ font-size: 2rem; ... }", ... }
-- data.imports  → {}   (populated when @import "file.css" rules are present)
```

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

### Check Plugin Health

Source: https://context7.com/jezda1337/nvim-html-css/llms.txt

Run the `:checkhealth html-css` command to verify the plugin's dependencies and connectivity. This command checks for the presence and version of `curl` and network accessibility.

```lua
-- Run from Neovim command line:
-- :checkhealth html-css
```

```text
-- Produces output like:
-- nvim-html-css report
--   OK  curl found on path
--   OK  curl version is good          (curl 8.7.1 ...)
--   OK  site is accessible

-- On failure:
--   ERROR  curl not found on path
--   ERROR  curl must be 8.x.x, but got 7.88.0
--   ERROR  site is not accessible
```

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

### Query CSS Selectors from Cache

Source: https://context7.com/jezda1337/nvim-html-css/llms.txt

Queries the in-memory cache for CSS selectors (classes or IDs) associated with a given buffer. Local files are watched for automatic cache updates.

```lua
local cache = require("html-css.cache")

-- After a stylesheet has been fetched/parsed, query its selectors for a buffer:
local bufnr = vim.api.nvim_get_current_buf()

local classes = cache:get_classes(bufnr)
-- Returns: Selector[]
-- Each Selector: { label="btn-primary", block="{ color:#fff; ... }", type="class",
--                  source_name="/path/to/bootstrap.min.css", source_type="remote",
--                  range={ start={line=42,character=1}, ["end"]={line=42,character=12} } }

local ids = cache:get_ids(bufnr)
-- Returns: Selector[] — same shape but type="id"
```

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

### cache

Source: https://context7.com/jezda1337/nvim-html-css/llms.txt

An in-memory data store for parsed CSS. It holds parsed data keyed by file path and a per-buffer map of active sources. Local files are watched for changes.

```APIDOC
## cache:get_classes(bufnr)

### Description
Queries the cache for CSS selectors of type 'class' associated with a given buffer.

### Parameters
* `bufnr` - The buffer number to query.

### Response
* Returns: `Selector[]` - An array of selector objects, each containing `label`, `block`, `type`, `source_name`, `source_type`, and `range`.

### Request Example
```lua
local cache = require("html-css.cache")
local bufnr = vim.api.nvim_get_current_buf()
local classes = cache:get_classes(bufnr)
```
```

```APIDOC
## cache:get_ids(bufnr)

### Description
Queries the cache for CSS selectors of type 'id' associated with a given buffer.

### Parameters
* `bufnr` - The buffer number to query.

### Response
* Returns: `Selector[]` - An array of selector objects, similar to `get_classes`.

### Request Example
```lua
local cache = require("html-css.cache")
local bufnr = vim.api.nvim_get_current_buf()
local ids = cache:get_ids(bufnr)
```
```

```APIDOC
## cache:has_source(source)

### Description
Checks if a given remote source has already been fetched and cached.

### Parameters
* `source` - The URL of the remote source to check.

### Response
* Returns: `boolean` - `true` if the source is in the cache, `false` otherwise.

### Request Example
```lua
local cache = require("html-css.cache")
local already_fetched = cache:has_source("https://cdn.jsdelivr.net/npm/bootstrap@5.3.0/dist/css/bootstrap.min.css")
```
```

```APIDOC
## cache:link_sources(bufnr, sources)

### Description
Registers which sources are associated with a given buffer. This is typically called automatically after a stylesheet is fetched.

### Parameters
* `bufnr` - The buffer number.
* `sources` - A list of source paths or URLs.

### Request Example
```lua
local cache = require("html-css.cache")
cache:link_sources(vim.api.nvim_get_current_buf(), {
  "/home/user/project/src/styles/global.css",
  "https://cdn.jsdelivr.net/npm/bootstrap@5.3.0/dist/css/bootstrap.min.css",
})
```
```

```APIDOC
## cache:cleanup(bufnr)

### Description
Frees all cache entries associated with a closed buffer. This is typically called automatically via the `BufDelete` autocmd.

### Parameters
* `bufnr` - The buffer number to clean up.

### Request Example
```lua
local cache = require("html-css.cache")
cache:cleanup(vim.api.nvim_get_current_buf())
```
```

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

### Extract Stylesheets from HTML/JSX Buffers

Source: https://context7.com/jezda1337/nvim-html-css/llms.txt

Parses the active buffer to extract CSS stylesheets from `<link rel="stylesheet">` tags and inline `<style>` blocks. Supports HTML, Vue, Svelte, Astro, ERB, JSX, and TSX files.

```lua
local html_parser = require("html-css.parsers.html")

-- Called automatically on BufEnter for enabled file types.
-- Manual usage (e.g. in a custom autocmd):
local data = html_parser.setup(vim.api.nvim_get_current_buf())

-- For an HTML file containing:
--   <link rel="stylesheet" href="./styles/main.css">
--   <link rel="stylesheet" href="https://cdn.example.com/lib.css">
--   <style>.hero { color: red; }</style>

-- data.cdn      → { "./styles/main.css", "https://cdn.example.com/lib.css" }
-- data.raw_text → ".hero { color: red; }"

-- For a JSX/TSX file containing:
--   import "./App.css"
--   import styles from "../shared/tokens.module.css"
-- data.cdn      → { "./App.css", "../shared/tokens.module.css" }
-- data.raw_text → ""
```

=== COMPLETE CONTENT === This response contains all available snippets from this library. No additional content exists. Do not make further requests.