Neominimap

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

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

Dependencies

• Neovim version 0.10+
• A font that supports dispalys Braille Patterns Unicode block
• Optional: nvim-treesitter for highlighting
• Optional: gitsigns.nvim for Git integration

Installation

With Lazy:

---@module "neominimap.config.meta"
{
    "Isrothy/neominimap.nvim",
    version = "v3.*.*",
    enabled = true,
    lazy = false, -- NOTE: NO NEED to Lazy load
    -- Optional
    keys = {
        -- Global Minimap Controls
        { "<leader>nm", "<cmd>Neominimap toggle<cr>", desc = "Toggle global minimap" },
        { "<leader>no", "<cmd>Neominimap on<cr>", desc = "Enable global minimap" },
        { "<leader>nc", "<cmd>Neominimap off<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 winOn<cr>", desc = "Enable minimap for current window" },
        { "<leader>nwc", "<cmd>Neominimap winOff<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 tabOn<cr>", desc = "Enable minimap for current tab" },
        { "<leader>ntc", "<cmd>Neominimap tabOff<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 bufOn<cr>", desc = "Enable minimap for current buffer" },
        { "<leader>nbc", "<cmd>Neominimap bufOff<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

Commands

[!NOTE] A minimap is shown if and only if

• Neominimap is enabled globally,
• Neominimap is enabled for the current buffer,
• Neominimap is enabled for the current tabage, and
• Neominimap is enabled for the current window.

Lua API

Customized Handlers

See the wiki page

How it works

Caching Minimap Buffers

For every file opened, the plugin generates a corresponding minimap buffer.

When a buffer is displayed in a window, the minimap buffer is automatically opened side by side with the main window.

This approach minimizes unnecessary rendering when

• Multiple windows are open for same file
• Switching between buffers within a window

TreeSitter Integration

First, the plugin retrieves all Treesitter nodes in the buffer.

For each codepoint in the minimap, the plugin calculates which highlight occurs most frequently and displays it. If multiple highlights occur the same number of times, all of them are displayed.

Note that the plugin considers which highlights are applied, rather than which highlights are shown. Specifically, when many highlights are applied to a codepoint, it is possible that only some of them are visible. However, all applied highlights are considered in the calculation. As a result, unshown highlights may be displayed in the minimap, leading to potential inconsistencies between the highlights in the minimap and those in the buffer.

Tips

Checkout the wiki page for more details. wiki

Highlights

Namespaces

TODO

• [x] LSP integration
• [x] TreeSitter integration
• [x] Git integration
• [x] Search integration
• [x] Support for window relative to editor
• [x] Validate user configuration
• [x] Documentation
• [ ] Performance improvements
• [ ] More test cases

Non-Goals

• Scrollbar. Use satellite.nvim, nvim-scrollview or other plugins.
• Display screen bounds like codewindow.nvim. For performance, this plugin creates a minimap buffer for each buffer. Since a screen bound is a windowwise thing, it's not impossible to display them by highlights.

Limitations

• Updating Folds Immediately. Neovim does not provide a fold event. Therefore, this plugin cannot update immediately whenever fold changes in a buffer.

Similar projects

• codewindow.nvim

  • Codewindow.nvim renders the minimap whenever focus is switched to a different window or the buffer is switched. In contrast, this plugin caches the minimap, so it only renders when the text is changed. Therefore, this plugin should offer better performance when frequently switching windows or buffers.
  • Codewindow.nvim renders the minimap based on bytes, while this plugin renders based on codepoints, respecting UTF-8 encoding and tab width.
  • Codewindow.nvim does not consider folds, whereas this plugin does.
  • Codewindow.nvim shows the minimap in a floating window but does not support a split window. This plugin supports both.
  • Codewindow.nvim does not support customized handlers, which this plugin does.

• mini.map

  • Mini.map allows for encoded symbol customization, while this plugin does not.
  • Mini.map includes a scrollbar, which this plugin does not.
  • Mini.map does not have Treesitter integration, whereas this plugin does.
  • Mini.map rescales the minimap so that its height matches the window height, while this plugin generates the minimap using a fixed compression rate.
  • Mini.map does not cache the minimap, but it is still performant.
  • Mini.map shows the minimap in a floating window but does not support a split window. This plugin supports both.
  • Mini.map does not support customized handlers, which this plugin does.

• minimap.vim

  • Like Mini.map, Minimap.vim scales the minimap.
  • Minimap.vim uses a Rust program to generate minimaps efficiently, while this plugin is written in Lua.
  • Minimap.vim does not have Treesitter or LSP integration, which this plugin does.
  • Minimap.vim shows the minimap in a split window but does not support a floating window. This plugin supports both.
  • Minimap.vim does not support customized handlers, which this plugin does.

Acknowledgements

Thanks to gorbit99 for codewindow.nvim, by which this plugin was inspired. The map generation algorithm and TreeSitter integration algorithm are also learned from that project.

Special thanks to lewis6991 for creating the excellent gitsigns.nvim and satellite.nvim plugins. The Git integration in Neominimap was made possible by gitsigns.nvim, and the search and mark integrations are based on satellite.nvim's code.