---@enum Neominimap.Handler.Annotation
local AnnotationMode = {
    Sign = "sign", -- Show braille signs in the sign column
    Icon = "icon", -- Show icons in the sign column
    Line = "line", -- Highlight the background of the line on the minimap
}

vim.g.neominimap = {
    -- Enable the plugin by default
    auto_enable = true, ---@type boolean

    -- Log level
    log_level = vim.log.levels.OFF, ---@type Neominimap.Log.Levels

    -- Notification level
    notification_level = vim.log.levels.INFO, ---@type Neominimap.Log.Levels

    -- Path to the log file
    log_path = vim.fn.stdpath("data") .. "/neominimap.log", ---@type string

    -- Minimaps will not be created for buffers of these filetypes
    ---@type string[]
    exclude_filetypes = {
        "help",
        "bigfile", -- For Snacks.nvim
    },

    -- Minimaps will not be created for buffers of these buftypes
    ---@type string[]
    exclude_buftypes = {
        "nofile",
        "nowrite",
        "quickfix",
        "terminal",
        "prompt",
    },

    -- When this function returns false, the minimap will not be created for this buffer.
    ---@type fun(bufnr: integer): boolean
    buf_filter = function()
        return true
    end,

    -- When this function returns false, the minimap will not be created for this window.
    ---@type fun(winid: integer): boolean
    win_filter = function()
        return true
    end,

    -- When this function returns false, the minimap will not be created for this tab.
    ---@type fun(tabid: integer): boolean
    tab_filter = function()
        return true
    end,

    -- How many columns a dot should span
    x_multiplier = 4, ---@type integer

    -- How many rows a dot should span
    y_multiplier = 1, ---@type integer

    ---@alias Neominimap.Config.CurrentLinePosition "center" | "percent"

    -- How the minimap places the current line vertically.
    -- `"center"`  -> pins the line to the viewport middle (window-relative).
    -- `"percent"` -> maps line index / total lines to minimap height (file-relative).
    -- Note: here "center" means the middle of the **minimap window**, not "center of the file".
    current_line_position = "center", ---@type Neominimap.Config.CurrentLinePosition

    buffer = {
        -- When true, the minimap will be recreated when you delete the buffer.
        -- When false, the minimap will be disabled for the current buffer when you delete the minimap buffer.
        persist = true, ---@type boolean
    },

    ---@alias Neominimap.Config.LayoutType "split" | "float"

    --- Either `split` or `float`
    --- When layout is set to `float`, minimaps will be created in floating windows attached to all suitable windows.
    --- When layout is set to `split`, the minimap will be created in one split window per tab.
    layout = "float", ---@type Neominimap.Config.LayoutType

    --- Used when `layout` is set to `split`
    split = {
        minimap_width = 20, ---@type integer

        -- Always fix the width of the split window
        fix_width = false, ---@type boolean

        ---@alias Neominimap.Config.SplitDirection "left" | "right" | "topleft" | "botright" | "aboveleft" | "rightbelow"
        direction = "right", ---@type Neominimap.Config.SplitDirection

        --- Automatically close the split window when it is the last window.
        close_if_last_window = false, ---@type boolean

        --- When true, the split window will be recreated when you close it.
        --- When false, the minimap will be disabled for the current tab when you close the minimap window.
        persist = true, ---@type boolean
    },

    --- Used when `layout` is set to `float`
    float = {
        minimap_width = 20, ---@type integer

        --- If set to nil, there is no maximum height restriction
        --- @type integer
        max_minimap_height = nil,

        margin = {
            right = 0, ---@type integer
            top = 0, ---@type integer
            bottom = 0, ---@type integer
        },
        z_index = 1, ---@type integer

        --- Border style of the floating window.
        --- Accepts all usual border style options (e.g., "single", "double")
        --- @type string | string[] | [string, string][]
        window_border = vim.fn.has("nvim-0.11") == 1 and vim.o.winborder or "single",

        -- When true, the floating window will be recreated when you close it.
        -- When false, the minimap will be disabled for the current tab when you close the minimap window.
        persist = true, ---@type boolean
    },

    -- For performance, when text changes, the minimap is refreshed after a certain delay.
    -- Set the delay in milliseconds
    delay = 200, ---@type integer

    -- Sync the cursor position with the minimap
    sync_cursor = true, ---@type boolean

    click = {
        -- Enable mouse click on the minimap
        enabled = false, ---@type boolean
        -- Automatically switch focus to the minimap when clicked
        auto_switch_focus = true, ---@type boolean
    },

    diagnostic = {
        enabled = true, ---@type boolean

        -- Allowed formats for the `severity` filter:
        -- 1. A single severity level:
        --      eg: severity = vim.diagnostic.severity.WARN
        -- 2. A table with a "min" and/or "max" key:
        --      eg: severity = { min = vim.diagnostic.severity.WARN, max = vim.diagnostic.severity.ERROR }
        -- 3. A list-like table of severity values:
        --      eg: severity = { vim.diagnostic.severity.WARN, vim.diagnostic.severity.ERROR }
        ---@see vim.diagnostic.severity
        severity = nil, ---@type vim.diagnostic.SeverityFilter?
        mode = "line", ---@type Neominimap.Handler.Annotation.Mode
        priority = {
            ERROR = 100, ---@type integer
            WARN = 90, ---@type integer
            INFO = 80, ---@type integer
            HINT = 70, ---@type integer
        },
        icon = {
            ERROR = "󰅚 ", ---@type string
            WARN = "󰀪 ", ---@type string
            INFO = "󰌶 ", ---@type string
            HINT = " ", ---@type string
        },
    },

    git = {
        enabled = true, ---@type boolean
        mode = "sign", ---@type Neominimap.Handler.Annotation.Mode
        priority = 6, ---@type integer
        icon = {
            add = "+ ", ---@type string
            change = "~ ", ---@type string
            delete = "- ", ---@type string
        },
    },

    mini_diff = {
        enabled = false, ---@type boolean
        mode = "sign", ---@type Neominimap.Handler.Annotation.Mode
        priority = 6, ---@type integer
        icon = {
            add = "+ ", ---@type string
            change = "~ ", ---@type string
            delete = "- ", ---@type string
        },
    },

    search = {
        enabled = false, ---@type boolean
        mode = "line", ---@type Neominimap.Handler.Annotation.Mode
        priority = 20, ---@type integer
        icon = "󰱽 ", ---@type string
    },

    treesitter = {
        enabled = true, ---@type boolean
        priority = 200, ---@type integer
    },

    mark = {
        enabled = false, ---@type boolean
        mode = "icon", ---@type Neominimap.Handler.Annotation.Mode
        priority = 10, ---@type integer
        key = "m", ---@type string -- Useless for neovim >= 0.12
        show_builtins = false, ---@type boolean -- shows the builtin marks like [ ] < >
    },

    fold = {
        -- Consider folds when rendering the minimap
        enabled = true, ---@type boolean
    },

    --- Override the default window options
    ---@param opt vim.wo
    ---@param winid integer the window id of the source window, NOT the minimap window
    winopt = function(opt, winid) end,

    --- Override the default buffer options
    ---@param opt vim.bo
    ---@param bufnr integer the buffer id of the source buffer, NOT the minimap buffer
    bufopt = function(opt, bufnr) end,

    ---@type Neominimap.Map.Handler[]
    handlers = {},
}

{
  winhighlight = table.concat({
    "Normal:NeominimapBackground",
    "FloatBorder:NeominimapBorder",
    "CursorLine:NeominimapCursorLine",
    "CursorLineNr:NeominimapCursorLineNr",
    "CursorLineSign:NeominimapCursorLineSign",
    "CursorLineFold:NeominimapCursorLineFold",
  }, ","),
  wrap = false,
  foldcolumn = "0",
  signcolumn = "auto",
  number = false,
  relativenumber = false,
  scrolloff = config.current_line_position == "center" and 99999 or 0,
  sidescrolloff = 0,
  winblend = 0,
  cursorline = true,
  spell = false,
  list = false,
  fillchars = "eob: ",
  winfixwidth = true,
}

{
  buftype = "nofile",
  filetype = "neominimap",
  swapfile = false,
  bufhidden = "hide",
  undolevels = -1,
  modifiable = false,
}

• Global Commands:

  • Neominimap Enable

    • Description: Enable minimaps globally.
    • Arguments: None

  • Neominimap Disable

    • Description: Disable minimaps globally.
    • Arguments: None

  • Neominimap Toggle

    • Description: Toggle minimaps globally.
    • Arguments: None

  • Neominimap Refresh

    • Description: Refresh minimaps globally.
    • Arguments: None

• Buffer Commands:

  • Neominimap BufEnable [buffer_list]

    • Description: Enable the minimap for specified buffers. If no buffers are specified, enable for the current buffer.
    • Arguments: Optional: List of buffers

  • Neominimap BufDisable [buffer_list]

    • Description: Disable the minimap for specified buffers. If no buffers are specified, disable for the current buffer.
    • Arguments: Optional: List of buffers

  • Neominimap BufToggle [buffer_list]

    • Description: Toggle the minimap for specified buffers. If no buffers are specified, toggle for the current buffer.
    • Arguments: Optional: List of buffers

  • Neominimap BufRefresh [buffer_list]

    • Description: Refresh the minimap buffers for specified buffers. If no buffers are specified, refresh for the current buffer. It does the following:
      1. Creating or wiping out buffers as needed.
      2. Rendering minimap text and applying highlights.
    • Arguments: Optional: List of buffers

• Tab Commands:

  • Neominimap TabEnable [tab_list]

    • Description: Enable the minimap for specified tabpage. If no tabpages are specified, enable for the current tab.
    • Arguments: Optional: List of tabpages

  • Neominimap TabDisable [tab_list]

    • Description: Disable the minimap for specified tabpages. If no tabpages are specified, disable for the current tab.
    • Arguments: Optional: List of tabpages

  • Neominimap TabToggle [tab_list]

    • Description: Toggle the minimap for specified tabpages. If no tabpages are specified, toggle for the current tab.
    • Arguments: Optional: List of tabpages

  • Neominimap TabRefresh [tab_list]

    • Description: Refresh the minimap tabs for specified tabs. If no tabs are specified, refresh for the current tab. It does the following:
      1. Creating or wiping out windows in tabpages as needed.
    • Arguments: Optional: List of tabpages

• Window Commands:

  • Neominimap WinEnable [window_list]

    • Description: Enable the minimap for specified windows. If no windows are specified, enable for the current window.
    • Arguments: Optional: List of windows

  • Neominimap WinDisable [window_list]

    • Description: Disable the minimap for specified windows. If no windows are specified, disable for the current window.
    • Arguments: Optional: List of windows

  • Neominimap WinToggle [window_list]

    • Description: Toggle the minimap for specified windows. If no windows are specified, toggle for the current window.
    • Arguments: Optional: List of windows

  • Neominimap WinRefresh [window_list]

    • Description: Refresh the minimap windows for specified windows. If no windows are specified, refresh for the current window. It does the following:
      1. Opening or closing windows as needed.
      2. Updating window configurations, such as positions and sizes.
      3. Attaching windows to the correct buffers.
    • Arguments: Optional: List of windows

• Focus Commands:

  • Neominimap Focus

    • Description: Focus on the minimap. Set cursor to the minimap window.
    • Arguments: None

  • Neominimap Unfocus

    • Description: Unfocus the minimap. Set cursor back.
    • Arguments: None

  • Neominimap ToggleFocus

    • Description: Toggle minimap focus.
    • Arguments: None

Usage Examples

To turn on the minimap globally:

:Neominimap on

To disable the minimap for the current buffer:

:Neominimap BufOff

To refresh the minimap for windows 3 and 4:

:Neominimap WinRefresh 3 4

• Global API

  • require('neominimap.api').enable()

    • Description: Enable the minimap globally across all buffers and windows.
    • Arguments: None

  • require('neominimap.api').disable()

    • Description: Disable the minimap globally.
    • Arguments: None

  • require('neominimap.api').toggle()

    • Description: Toggle the minimap on or off globally.
    • Arguments: None

  • require('neominimap.api').refresh()

    • Description: Refresh the minimap globally.
    • Arguments: None

  • require('neominimap.api').enabled()

    • Description: Check if the minimap is enabled globally.
    • Arguments: None
    • Returns: true if the minimap is enabled, false otherwise

• Buffer API

  • require('neominimap.api').buf.enable(<bufnr>)

    • Description: Enable the minimap for specified buffers.
    • Arguments: None (defaults to current buffer), or an integer or a list of buffer numbers

  • require('neominimap.api').buf.disable(<bufnr>)

    • Description: Disable the minimap for specified buffers.
    • Arguments: None (defaults to current buffer), or an integer or a list of buffer numbers

  • require('neominimap.api').buf.toggle(<bufnr>)

    • Description: Toggle the minimap for specified buffers.
    • Arguments: None (defaults to current buffer), or an integer or a list of buffer numbers

  • require('neominimap.api').buf.refresh(<bufnr>)

    • Description: Refresh the minimap buffers for specified buffers.
    • Arguments: None (defaults to current buffer), or an integer or a list of buffer numbers

  • require('neominimap').buf.enabled(bufnr)

    • Description: Check if the minimap is enabled for specified buffers.
    • Arguments: A buffer number (optional). If no buffer is specified, check for the current buffer.
    • Returns: true if the minimap is enabled, false otherwise

• Tab API

  • require('neominimap.api').tab.enable(<tabid>)

    • Description: Enable the minimap for specified tabpages.
    • Arguments: None (defaults to current tabage), or an integer or a list of tabpage IDs

  • require('neominimap.api').tab.disable(<tabid>)

    • Description: Disable the minimap for specified tabpages.
    • Arguments: None (defaults to current tabage), or an integer or a list of tabpage IDs

  • require('neominimap.api').tab.toggle(<tabid>)

    • Description: Toggle the minimap for specified tabpages.
    • Arguments: None (defaults to current tabage), or an integer or a list of tabpage IDs

  • require('neominimap.api').tab.refresh(<tabid>)

    • Description: Refresh the minimap tabs for specified tabpages.
    • Arguments: None (defaults to current tabage), or an integer or a list of tabpage IDs

  • require('neominimap').tab.enabled(tabid)

    • Description: Check if the minimap is enabled for specified tabpages.
    • Arguments: A tabpage ID (optional). If no tabpage is specified, check for the current tabpage.
    • Returns: true if the minimap is enabled, false otherwise

• Window API

  • require('neominimap.api').win.enable(<winid>)

    • Description: Enable the minimap for specified windows.
    • Arguments: None (defaults to current window), or an integer or a list of window IDs

  • require('neominimap.api').win.disable(<winid>)

    • Description: Disable the minimap for specified windows.
    • Arguments: None (defaults to current window), or an integer or a list of window IDs

  • require('neominimap.api').win.toggle(<winid>)

    • Description: Toggle the minimap for specified windows.
    • Arguments: None (defaults to current window), or an integer or a list of window IDs

  • require('neominimap.api').win.refresh(<winid>)

    • Description: Refresh the minimap windows for specified windows.
    • Arguments: None (defaults to current window), or an integer or a list of window IDs

  • require('neominimap').win.enabled(winid)

    • Description: Check if the minimap is enabled for specified windows.
    • Arguments: A window ID (optional). If no window is specified, check for the current window.
    • Returns: true if the minimap is enabled, false otherwise

• Focus Control

  • require('neominimap.api').focus.enable()

    • Description: Focus the minimap window, allowing interaction with it.
    • Arguments: None

  • require('neominimap.api').focus.disable()

    • Description: Unfocus the minimap window, returning focus to the editor.
    • Arguments: None

  • require('neominimap.api').focus.toggle()

    • Description: Toggle focus between the minimap and the main editor window.
    • Arguments: None

The neominimap API has been updated to provide a more intuitive and flexible interface. The old API is now deprecated and will eventually be removed. This guide will help you transition to the new neominimap.api.

Key Differences Between the Old and New API

Handle Input Changes

• Old Behavior: Passing an empty list ({}) defaulted to the current buffer, tab, or window.
• New Behavior: Passing an empty list does nothing. To default to the current context, pass nil or omit the argument.

Here is an example:

-- Old API
require("neominimap").bufOn({}) -- Defaults to current buffer
-- New API
require("neominimap.api").buf.enable() -- Explicitly defaults to current buffer
require("neominimap.api").buf.enable({}) -- Does nothing

Handler Structure

A handler is defined as a Lua table with the following fields:

• name (string): A unique identifier for your handler (e.g., "my_todo_handler").
• mode ("sign" | "icon" | "line"): Determines how annotations are displayed on the minimap:
  • "sign": Shows small braille characters in the sign column.
  • "icon": Shows a single character/icon (potentially from an icon font) in the sign column.
  • "line": Highlights the background of the corresponding line(s) on the minimap.
• namespace (integer): A Neovim namespace ID used internally by Neovim to manage virtual text or signs. This should be created using vim.api.nvim_create_namespace.
• autocmds ({event: string|string[], opts?: table}[]): A list of autocommand specifications. Whenever one of these autocommands fires, the handler will be triggered to update the minimap for the relevant buffer(s). The opts table can contain standard autocommand options like pattern, desc, and importantly, either callback or get_buffers.
  • If opts.callback is defined (fun(apply: fun(bufnr:integer), args: any)), it receives a function apply(bufnr) to manually trigger the handler for a specific buffer and the autocommand arguments. You are responsible for calling apply(bufnr) for the buffer(s) you want to update.
  • If opts.callback is not defined, you must provide opts.get_buffers (fun(data: vim.api.keyset.create_autocmd.callback_args): integer[] | integer). This function receives the autocommand arguments and must return the buffer number(s) that the handler should be applied to.
• init (fun()): A function called once when the handler is registered.
• get_annotations (fun(bufnr: integer): Neominimap.Map.Handler.Annotation[]): This is the core logic of your handler. It takes a buffer number (bufnr) as input, and returns an array of Neominimap.Map.Handler.Annotation objects.

Annotation Structure

Each object returned by get_annotations must conform to the Neominimap.Map.Handler.Annotation structure:

• lnum (integer): The starting line number (1-based) in the main buffer that this annotation refers to.
• end_lnum (integer): The ending line number (1-based). For single-line annotations, this is the same as lnum.
• id (integer): An id for a specific kind of annotation. For example, all git add should have the same id but git add and git change have different ids. This is used to group annotations together like vertical braille dots.
• priority (integer): Determines display order when annotations overlap.
• icon? (string, optional): A single character or icon string to display if the handler's mode is "icon".
• highlight (string): The name of a Neovim highlight group.

See the wiki page for examples.

Customizable Statusline Components

The plugin offers the following customizable components for your statusline:

• plugin_name - Displays the plugin name, "Neominimap".
• fullname - Shows the full path of the current file.
• shortname - Displays only the filename (without the path).
• position - Indicates the current cursor position within the file.

Example: Customizing Lualine

Here's an example of how you can customize the Lualine statusline using neominimap components:

local neominimap = require("neominimap.statusline")
local minimap_extension = {
    sections = {
        lualine_c = {
            neominimap.fullname,
        },
        lualine_z = {
            neominimap.position,
            "progress",
        },
    },
    filetypes = { "neominimap" },
}
require("lualine").setup({ extensions = { minimap_extension } })

Using the Default Lualine Extension

Alternatively, you can use the default settings provided by the plugin:

local minimap_extension = require("neominimap.statusline").lualine_default
require("lualine").setup({ extensions = { minimap_extension } })

The default Lualine extension provided by the plugin is structured as follows:

{
  sections = {
    winbar = {},
    lualine_a = {
      M.plugin_name,
    },
    lualine_c = {
      M.shortname,
    },
    lualine_z = {
      M.position,
      "progress",
    },
  },
  filetypes = { "neominimap" },
}

Highlight Groups of Neominimap Windows

Highlight Groups of Diagnostic Annotations

Highlight Groups of Git Annotations

Highlight Groups of Mini Diff Annotations

Highlight Groups of Search Annotations

Highlight Groups of Mark Annotations