🎺 herald.nvim

A context-aware floating buffer label for Neovim.

herald.nvim provides a highly customizable floating window that displays buffer information (filename, git branch, diagnostics, and status) in a fixed corner or center of your window. It is designed for performance, stability, and zero visual jitter.

✨ Features

• 📍 Flexible Positioning: Anchor labels to any corner or center of the window (top_right, top_center, top_left, bottom_right, bottom_center, bottom_left).
• 🛡️ Robust Rendering: Uses floating windows relative to the parent window to maintain a fixed position regardless of buffer scrolling.
• 🛣️ Smart Path Formatting: Choose between filename only, relative paths, absolute paths, or shortened paths (e.g., l/h/init.lua).
• 🔌 Integrations:
  • Git: Displays current branch name (supports gitsigns.nvim and vim-fugitive).
  • LSP Diagnostics: Real-time display of error and warning counts.
  • Icons: Optional integration with nvim-web-devicons.
• 🌈 Dynamic Highlighting: Automatically colors the filename based on its filetype or modification status.
• ⚡ Optimized Performance: Features debounced updates, targeted buffer-specific refreshes, and result caching to minimize CPU impact.
• 🛠️ Advanced Customization: Programmatically modify or extend label content using a custom formatter callback.

📦 Installation

lazy.nvim

{
  "lesnik2u/herald.nvim",
  event = "VeryLazy",
}

packer.nvim

use {
  'lesnik2u/herald.nvim',
  config = function()
    require('herald').setup()
  end
}

⚙️ Configuration

Herald comes with sensible defaults. To customize it, pass a configuration table to the setup function.

require("herald").setup({
  -- Presets
  preset = nil,               -- Options: "minimal", "modern", "informative", "badge", "ghost"
                              -- Note: Presets override defaults, but can be overridden by other keys.

  -- Positioning and Layout
  position = "top_right",     -- Options: "top_left", "top_center", "top_right", 
                              --          "bottom_left", "bottom_center", "bottom_right"
  margin = 1,                 -- Distance from the window edge
  min_width = 15,             -- Hide overlay if window is narrower than this
  zindex = 50,                -- Stacking order relative to other floating windows

  -- Visuals
  border = "none",            -- Options: "none", "single", "double", "rounded", "solid", "shadow"
  winblend = 0,               -- Transparency (0-100)
  highlight_group = "Normal", -- Primary highlight group for text and background
  border_highlight = "Normal",-- Highlight group for the border

  -- Content Formatting
  filename_mode = "name",     -- Options: "name", "relative", "absolute", "short_path"
  max_filename_length = 25,   -- Maximum length before truncation
  truncate_start = false,     -- If true, truncate from the beginning of the path
  show_extension = true,      -- Ensure the file extension is always visible

  -- Integrations
  show_icons = true,          -- Requires nvim-web-devicons
  icon_padding = " ",         -- Space between the icon and filename
  
  show_git_branch = false,    -- Requires gitsigns.nvim or vim-fugitive
  branch_padding = " ",       -- Space before the branch name
  
  show_diagnostics = false,   -- Display LSP diagnostic counts
  diagnostic_signs = {
    error = " E:",
    warn = " W:",
    info = " I:",
    hint = " H:",
  },

  -- Status Indicators
  show_modified = true,       -- Show indicator when buffer has unsaved changes
  modified_sign = " [+]",     
  show_readonly = true,       -- Show indicator when buffer is read-only
  readonly_sign = " [RO]",    

  -- Colors
  use_filetype_color = true,  -- Match filename color to filetype icon color
  modified_hl = "MatchParen", -- Highlight group used when the buffer is modified

  -- Advanced Customization
  -- custom_formatter: function(chunks, buf_id) -> chunks
  -- 'chunks' is a table of { text = string, hl = string|nil }
  custom_formatter = nil,     

  -- Performance
  update_delay = 10,          -- Debounce delay in milliseconds

  -- Exclusions
  excluded_filetypes = {
    "NvimTree", "neo-tree", "packer", "qf", "help", "man", "lspinfo", 
    "spectre_panel", "tsplayground", "DressingSelect", "TelescopePrompt"
  },
  excluded_buftypes = {
    "nofile", "prompt", "popup", "quickfix", "terminal"
  }
})

🚀 Commands

Command	Description
:Herald show	Enable the overlay.
:Herald hide	Disable the overlay.
:Herald toggle	Toggle the overlay.
:Herald refresh	Force a refresh of all active overlays.

Legacy individual commands are also supported: :HeraldShow, :HeraldHide, :HeraldToggle, and :HeraldRefresh.

📜 License

MIT