Neominimap

<a href="https://dotfyle.com/plugins/Isrothy/neominimap.nvim"> <img src="https://dotfyle.com/plugins/Isrothy/neominimap.nvim/shield" /> </a>

Overview

This plugin provides a visual representation of your code structure on the side of your windows, similar to the minimap found in many modern editors.

Criticisms are welcome.

Screenshots

The color scheme used for these screenshots is nord

<details> <summary>Show diagnostics:</summary>

</details> <details> <summary>Show git signs:</summary>

</details> <details> <summary>Show search results:</summary>

</details> <details> <summary>Show marks:</summary>

</details> <details> <summary>Show minimaps in float windows:</summary>

</details> <details> <summary>Show minimaps in a split window:</summary>

</details>

Features

• 🖥️ LSP integration
• 🌳 TreeSitter integration
• ➖ Fold integration
• 🔀 Git integration
• 🔎 Search integration
• 🏷️ Support for marks
• 🖱️ Mouse click support
• 🖍️ Support for map annotations in the sign column and line highlight
• 📐 Support both split window and float window layouts
• 🌐 Respects UTF-8 encoding and tab width
• 🎯 Focus on the minimap, allowing interaction with it
• 🔧 Support for customized handlers
• 🔣 Statusline Components
• ⏳ Cooperative Scheduling

Requirements and Dependencies

• Neovim version 0.10.0 or higher is required. Nightly versions might work, but NOT guaranteed or maintained.
• A font that supports displaying Braille Patterns Unicode block
• Optional: nvim-treesitter for highlighting
• Optional: gitsigns.nvim for Git integration
• Optional: mini.diff for mini diff integration

Installation

With Lazy:

---@module "neominimap.config.meta"
{
  "Isrothy/neominimap.nvim",
  version = "v3.x.x",
  lazy = false, -- NOTE: NO NEED to Lazy load
  -- Optional. You can also set your own keybindings
  keys = {
    -- Global Minimap Controls
    { "<leader>nm", "<cmd>Neominimap Toggle<cr>", desc = "Toggle global minimap" },
    { "<leader>no", "<cmd>Neominimap Enable<cr>", desc = "Enable global minimap" },
    { "<leader>nc", "<cmd>Neominimap Disable<cr>", desc = "Disable global minimap" },
    { "<leader>nr", "<cmd>Neominimap Refresh<cr>", desc = "Refresh global minimap" },

    -- Window-Specific Minimap Controls
    { "<leader>nwt", "<cmd>Neominimap WinToggle<cr>", desc = "Toggle minimap for current window" },
    { "<leader>nwr", "<cmd>Neominimap WinRefresh<cr>", desc = "Refresh minimap for current window" },
    { "<leader>nwo", "<cmd>Neominimap WinEnable<cr>", desc = "Enable minimap for current window" },
    { "<leader>nwc", "<cmd>Neominimap WinDisable<cr>", desc = "Disable minimap for current window" },

    -- Tab-Specific Minimap Controls
    { "<leader>ntt", "<cmd>Neominimap TabToggle<cr>", desc = "Toggle minimap for current tab" },
    { "<leader>ntr", "<cmd>Neominimap TabRefresh<cr>", desc = "Refresh minimap for current tab" },
    { "<leader>nto", "<cmd>Neominimap TabEnable<cr>", desc = "Enable minimap for current tab" },
    { "<leader>ntc", "<cmd>Neominimap TabDisable<cr>", desc = "Disable minimap for current tab" },

    -- Buffer-Specific Minimap Controls
    { "<leader>nbt", "<cmd>Neominimap BufToggle<cr>", desc = "Toggle minimap for current buffer" },
    { "<leader>nbr", "<cmd>Neominimap BufRefresh<cr>", desc = "Refresh minimap for current buffer" },
    { "<leader>nbo", "<cmd>Neominimap BufEnable<cr>", desc = "Enable minimap for current buffer" },
    { "<leader>nbc", "<cmd>Neominimap BufDisable<cr>", desc = "Disable minimap for current buffer" },

    ---Focus Controls
    { "<leader>nf", "<cmd>Neominimap Focus<cr>", desc = "Focus on minimap" },
    { "<leader>nu", "<cmd>Neominimap Unfocus<cr>", desc = "Unfocus minimap" },
    { "<leader>ns", "<cmd>Neominimap ToggleFocus<cr>", desc = "Switch focus on minimap" },
  },
  init = function()
    -- The following options are recommended when layout == "float"
    vim.opt.wrap = false
    vim.opt.sidescrolloff = 36 -- Set a large value

    --- Put your configuration here
    ---@type Neominimap.UserConfig
    vim.g.neominimap = {
      auto_enable = true,
    }
  end,
}

Configuration

<details> <summary>Default configuration</summary>

---@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,

    ma