• 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

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.

• 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

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.

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.

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.

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 } })

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" },
}