StylePeek.nvim

StylePeek is a Neovim plugin for inspecting, selecting, creating, editing, and deleting CSS rules in the context of an HTML buffer.

Project status: StylePeek contains stable and development picker implementations. Review the documentation and test a clean Lazy.nvim installation before publishing a public release.

Features

• Detects the HTML context and class or keyword under the cursor.
• Resolves external stylesheets and inline <style> blocks.
• Scans CSS and ranks candidate rules for the current context.
• Offers a small rule selector when multiple CSS matches are available.
• Provides a larger picker with list and preview panes.
• Supports three picker placements: float, fixed_bottom, and fixed_right.
• Includes commands and default mappings for viewing, editing, creating, and deleting rules.
• Includes a settings UI and configurable highlight colors.

The exact behavior of each action depends on the source-resolution and CSS-matching logic. See the workflow documentation for details.

Screenshots

Picker layouts

Stylepeek supports three picker placements:

Float

Mutliple rules

Fixed_bottom

fixed_right

Creating a new rule

Deleting a rule

Stylepeek custom setup window

Installation with lazy.nvim

Add this plugin specification to your Neovim configuration, for example in lua/plugins/stylepeek.lua:

return {
  {
    "mcp1766/stylepeek.nvim",
    config = function()
      require("stylepeek").setup({
        placement = "float",
      })
    end,
  },
}

Then run :Lazy sync (or use the Lazy.nvim interface) to install the plugin.

The lua/plugins/stylepeek.lua file belongs to your personal Neovim configuration; it is not part of the plugin's source tree.

Repository layout

The plugin's Lua modules must be located under lua/stylepeek/ in the repository so that calls such as require("stylepeek") and require("stylepeek.engine") resolve correctly.

stylepeek.nvim/
├── README.md
├── LICENSE
├── docs/
└── lua/
    └── stylepeek/
        ├── init.lua
        ├── config.lua
        ├── engine.lua
        ├── html.lua
        ├── css.lua
        ├── resolver.lua
        ├── selectors.lua
        ├── util.lua
        └── ui/

Commands

Command Action

---

:StylePeek Open the StylePeek configuration UI :StylePeekPeek View or peek at a CSS rule :StylePeekEdit Edit a CSS rule :StylePeekCreate Create a CSS rule :StylePeekDelete Delete a CSS rule

Default mappings

Mode Mapping Action

---

Normal <leader>sp Peek or view a CSS rule Insert <M-P> Peek or view a CSS rule Normal <leader>se Edit a CSS rule Insert <M-E> Edit a CSS rule Normal <leader>su Open StylePeek setup Normal <leader>sc Create a CSS rule Insert <M-C> Create a CSS rule Normal <leader>sd Delete a CSS rule Insert <M-D> Delete a CSS rule

These are the default mappings in the current source snapshot. Mapping customization may not be available through the setup options.

Configuration

The defaults declared in stylepeek/config.lua include:

---

Option Default Meaning

---

css_directory "css" Default CSS directory under the project root

default_stylesheet "style.css" Default stylesheet name

prefer_external true Prefer an external stylesheet when one is linked

create_missing_rule true Allow creation when no matching rule exists

placement "float" Picker placement: float, fixed_bottom, or fixed_right

border "rounded" Floating-window border style

float_width 0.95 Width factor used by floating UI

float_height 0.80 Height factor used by floating UI

debug false Debug option

colors table Highlight colors used by the UI

---

Options can be passed to require("stylepeek").setup({...}). The source also loads and saves a user configuration file at stdpath("config") .. "/stylepeek.lua".

Example:

require("stylepeek").setup({
  placement = "float",
})

Documentation

• Architecture and module map
• Function-by-function catalogue
• Workflow diagrams
• Require audit and Lazy.nvim packaging
• Source inventory

Compatibility and release notes

The source uses Neovim APIs such as vim.fs, vim.uv, and vim.keymap.set. Confirm and document the minimum supported Neovim version before publishing.

Before releasing, test installation from a clean Neovim configuration using Lazy.nvim and verify the commands, mappings, picker placements, and CSS editing workflows.

License

StylePeek.nvim is distributed under the MIT License. See LICENSE.