Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/Isrothy/neominimap.nvim
Yet another minimap plugin for Neovim
https://github.com/Isrothy/neominimap.nvim
lua neovim-plugin
Last synced: about 1 month ago
JSON representation
Yet another minimap plugin for Neovim
- Host: GitHub
- URL: https://github.com/Isrothy/neominimap.nvim
- Owner: Isrothy
- License: mit
- Created: 2024-06-24T13:52:02.000Z (7 months ago)
- Default Branch: main
- Last Pushed: 2024-11-22T07:06:49.000Z (about 2 months ago)
- Last Synced: 2024-11-22T08:18:27.976Z (about 2 months ago)
- Topics: lua, neovim-plugin
- Language: Lua
- Homepage:
- Size: 635 KB
- Stars: 174
- Watchers: 4
- Forks: 3
- Open Issues: 2
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- License: LICENSE
Awesome Lists containing this project
README
# 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
Show diagnostics:
Show git signs:
Show search results:
Show marks:
Show minimaps in float windows:
Show minimaps in a split window:
## 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
## 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 dispalys **Braille Patterns** Unicode block
- Optional: [nvim-treesitter](https://github.com/nvim-treesitter/nvim-treesitter) for highlighting
- Optional: [gitsigns.nvim](https://github.com/lewis6991/gitsigns.nvim) for Git integration
## Installation
With Lazy:
```lua
---@module "neominimap.config.meta"
{
"Isrothy/neominimap.nvim",
version = "v3.*.*",
enabled = true,
lazy = false, -- NOTE: NO NEED to Lazy load
-- Optional
keys = {
-- Global Minimap Controls
{ "nm", "Neominimap toggle", desc = "Toggle global minimap" },
{ "no", "Neominimap on", desc = "Enable global minimap" },
{ "nc", "Neominimap off", desc = "Disable global minimap" },
{ "nr", "Neominimap refresh", desc = "Refresh global minimap" },
-- Window-Specific Minimap Controls
{ "nwt", "Neominimap winToggle", desc = "Toggle minimap for current window" },
{ "nwr", "Neominimap winRefresh", desc = "Refresh minimap for current window" },
{ "nwo", "Neominimap winOn", desc = "Enable minimap for current window" },
{ "nwc", "Neominimap winOff", desc = "Disable minimap for current window" },
-- Tab-Specific Minimap Controls
{ "ntt", "Neominimap tabToggle", desc = "Toggle minimap for current tab" },
{ "ntr", "Neominimap tabRefresh", desc = "Refresh minimap for current tab" },
{ "nto", "Neominimap tabOn", desc = "Enable minimap for current tab" },
{ "ntc", "Neominimap tabOff", desc = "Disable minimap for current tab" },
-- Buffer-Specific Minimap Controls
{ "nbt", "Neominimap bufToggle", desc = "Toggle minimap for current buffer" },
{ "nbr", "Neominimap bufRefresh", desc = "Refresh minimap for current buffer" },
{ "nbo", "Neominimap bufOn", desc = "Enable minimap for current buffer" },
{ "nbc", "Neominimap bufOff", desc = "Disable minimap for current buffer" },
---Focus Controls
{ "nf", "Neominimap focus", desc = "Focus on minimap" },
{ "nu", "Neominimap unfocus", desc = "Unfocus minimap" },
{ "ns", "Neominimap toggleFocus", 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
Default configuration
```lua
---@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
-- Minimap will not be created for buffers of these types
---@type string[]
exclude_filetypes = {
"help",
"bigfile", -- For Snacks.nvim
},
-- Minimap will not be created for buffers of these types
---@type string[]
exclude_buftypes = {
"nofile",
"nowrite",
"quickfix",
"terminal",
"prompt",
},
-- When false is returned, the minimap will not be created for this buffer
---@type fun(bufnr: integer): boolean
buf_filter = function()
return true
end,
-- When false is returned, the minimap will not be created for this window
---@type fun(winid: integer): boolean
win_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.LayoutType "split" | "float"
--- Either `split` or `float`
--- When layout is set to `float`,
--- the minimap 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
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"
direction = "right", ---@type Neominimap.Config.SplitDirection
---Automatically close the split window when it is the last window
close_if_last_window = false, ---@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 = "single",
},
-- For performance issue, when text changed,
-- 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 minimap
enabled = false, ---@type boolean
-- Automatically switch focus to minimap when clicked
auto_switch_focus = true, ---@type boolean
},
diagnostic = {
enabled = true, ---@type boolean
severity = vim.diagnostic.severity.WARN, ---@type vim.diagnostic.SeverityInt
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
},
},
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
show_builtins = false, ---@type boolean -- shows the builtin marks like [ ] < >
},
fold = {
-- Considering fold when rendering minimap
enabled = true, ---@type boolean
},
---Overrite the default winopt
---@param opt vim.wo
---@param winid integer the window id of the source window, NOT minimap window
winopt = function(opt, winid) end,
---Overrite the default bufopt
---@param opt vim.bo
---@param bufnr integer the buffer id of the source buffer, NOT minimap buffer
bufopt = function(opt, bufnr) end,
---@type Neominimap.Map.Handler[]
handlers = {},
}
```
Default winopt
```lua
{
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 = 99999, -- To center minimap
sidescrolloff = 0,
winblend = 0,
cursorline = true,
spell = false,
list = false,
fillchars = "eob: ",
winfixwidth = true,
}
```
Default bufopt
```lua
{
buftype = "nofile",
filetype = "neominimap",
swapfile = false,
bufhidden = "hide",
undolevels = -1,
modifiable = false,
}
```
## Commands
Click to expand
| Command | Description | Arguments |
| ------------------------------------- | --------------------------------------------------------------------------------------------------------------- | -------------------------- |
| `Neominimap on` | Turn on minimaps globally. | None |
| `Neominimap off` | Turn off minimaps globally. | None |
| `Neominimap toggle` | Toggle minimaps globally. | None |
| `Neominimap refresh` | Refresh minimaps globally. | None |
| `Neominimap bufOn [buffer_list]` | Enable the minimap for specified buffers. If no buffers are specified, enable for the current buffer. | Optional: List of buffers |
| `Neominimap bufOff [buffer_list]` | Disable the minimap for specified buffers. If no buffers are specified, disable for the current buffer. | Optional: List of buffers |
| `Neominimap bufToggle [buffer_list]` | Toggle the minimap for specified buffers. If no buffers are specified, toggle for the current buffer. | Optional: List of buffers |
| `Neominimap bufRefresh [buffer_list]` | Refresh the minimap buffers for specified buffers. If no buffers are specified, refresh for the current buffer. | Optional: List of buffers |
| `Neominimap TabOn [tab_list]` | Enable the minimap for specified tabspage. If no tabpages are specified, enable for the current tab. | Optional: List of tabpages |
| `Neominimap TabOff [tab_list]` | Disable the minimap for specified tabpages. If no tabpages are specified, disable for the current tab. | Optional: List of tabpages |
| `Neominimap TabToggle [tab_list]` | Toggle the minimap for specified tabpages. If no tabpages are specified, toggle for the current tab. | Optional: List of tabpages |
| `Neominimap TabRefresh [tab_list]` | Refresh the minimap tabs for specified tabs. If no tabs are specified, refresh for the current tab. | Optional: List of tabpages |
| `Neominimap winOn [window_list]` | Enable the minimap for specified windows. If no windows are specified, enable for the current window. | Optional: List of windows |
| `Neominimap winOff [window_list]` | Disable the minimap for specified windows. If no windows are specified, disable for the current window. | Optional: List of windows |
| `Neominimap winToggle [window_list]` | Toggle the minimap for specified windows. If no windows are specified, toggle for the current window. | Optional: List of windows |
| `Neominimap winRefresh [window_list]` | Refresh the minimap windows for specified windows. If no windows are specified, refresh for the current window. | Optional: List of windows |
| `Neominimap focus` | Focus on the minimap. Set cursor to the minimap window. | None |
| `Neominimap unfocus` | Unfocus the minimap. Set cursor back. | None |
| `Neominimap toggleFocus` | Toggle minimap focus | None |
`Neominimap bufRefresh` does the following:
- Creating or wiping out buffers as needed.
- Rendering minimap text and applying highlights.
`Neominimap tabRefresh` does the following:
- Creating or wiping out windows in tabpages as needed.
`Neominimap winRefresh` does the following:
- Opening or closing windows as needed.
- Updating window configurations, such as positions and sizes.
- Attaching windows to the correct buffers.
### Usage Examples
To turn on the minimap globally:
```vim
:Neominimap on
```
To disable the minimap for the current buffer:
```vim
:Neominimap bufOff
```
To refresh the minimap for windows 3 and 4:
```vim
:Neominimap winRefresh 3 4
```
> [!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
These are the corresponding commands in the Lua API.
| Function | Description | Arguments |
| ------------------------------------------- | ------------------------------------------------------------ | -------------------------------------------------------------------- |
| `require('neominimap').on()` | Enable the minimap globally across all buffers and windows. | None |
| `require('neominimap').off()` | Disable the minimap globally. | None |
| `require('neominimap').toggle()` | Toggle the minimap on or off globally. | None |
| `require('neominimap').refresh()` | Refresh the minimap globally. | None |
| `require('neominimap').bufOn()` | Enable the minimap for specified buffers. | List of buffer numbers (defaults to current buffer if list is empty) |
| `require('neominimap').bufOff()` | Disable the minimap for specified buffers. | List of buffer numbers (defaults to current buffer if list is empty) |
| `require('neominimap').bufToggle()` | Toggle the minimap for specified buffers. | List of buffer numbers (defaults to current buffer if list is empty) |
| `require('neominimap').bufRefresh()` | Refresh the minimap buffers for specified buffers. | List of buffer numbers (defaults to current buffer if list is empty) |
| `require('neominimap').tabOn()` | Enable the minimap for specified tabpages. | List of tabage IDs (defaults to current tabage if list is empty) |
| `require('neominimap').tabOff()` | Disable the minimap for specified tabpages. | List of tabage IDs (defaults to current tabage if list is empty) |
| `require('neominimap').tabToggle()` | Toggle the minimap for specified tabpages. | List of tabage IDs (defaults to current tabage if list is empty) |
| `require('neominimap').tabRefresh()` | Refresh the minimap tabs for specified tabpages. | List of tabage IDs (defaults to current tabage if list is empty) |
| `require('neominimap').winOn()` | Enable the minimap for specified windows. | List of window IDs (defaults to current window if list is empty) |
| `require('neominimap').winOff()` | Disable the minimap for specified windows. | List of window IDs (defaults to current window if list is empty) |
| `require('neominimap').winToggle()` | Toggle the minimap for specified windows. | List of window IDs (defaults to current window if list is empty) |
| `require('neominimap').winRefresh()` | Refresh the minimap windows for specified windows. | List of window IDs (defaults to current window if list is empty) |
| `require('neominimap').focus()` | Focuse the minimap window, allowing interaction with it. | None |
| `require('neominimap').unfocus()` | Unfocus the minimap window, returning focus to the editor. | None |
| `require('neominimap').toggleFocus()` | Toggle focus between the minimap and the main editor window. | None |
## Customized Handlers
See the [wiki page](https://github.com/Isrothy/neominimap.nvim/wiki/Custimized-Handlers)
## Statusline
This plugin provides statusline components that integrate with various
statusline plugins like Lualine.
Click to expand
### 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:
```lua
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:
```lua
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:
```lua
{
sections = {
winbar = {},
lualine_a = {
M.plugin_name,
},
lualine_c = {
M.shortname,
},
lualine_z = {
M.position,
"progress",
},
},
filetypes = { "neominimap" },
}
```
## 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](https://github.com/Isrothy/neominimap.nvim/wiki/Tips)
## Highlights
Click to expand
### Highlight Groups of Neominimap Windows
| Highlight Group | Description |
| -------------------------- | ------------------------------------------ |
| `NeominimapBackground` | Background color for the minimap. |
| `NeominimapBorder` | Border highlight for the minimap window. |
| `NeominimapCursorLine` | Highlight for the cursor line in minimaps. |
| `NeominimapCursorLineNr` | To replace `CursorLineNr` in minimaps. |
| `NeominimapCursorLineSign` | To replace `CursorLineSign` in minimaps. |
| `NeominimapCursorLineFold` | To replace `CursorLineFold` in minimaps. |
### Highlight Groups of Diagnostic Annotations
| Highlight Group | Description |
| --------------------- | ----------- |
| `NeominimapHintLine` | |
| `NeominimapInfoLine` | |
| `NeominimapWarnLine` | |
| `NeominimapErrorLine` | |
| `NeominimapHintSign` | |
| `NeominimapInfoSign` | |
| `NeominimapWarnSign` | |
| `NeominimapErrorSign` | |
| `NeominimapHintIcon` | |
| `NeominimapInfoIcon` | |
| `NeominimapWarnIcon` | |
| `NeominimapErrorIcon` | |
### Highlight Groups of Git Annotations
| Highlight Group | Description |
| ------------------------- | ----------- |
| `NeominimapGitAddLine` | |
| `NeominimapGitChangeLine` | |
| `NeominimapGitDeleteLine` | |
| `NeominimapGitAddSign` | |
| `NeominimapGitChangeSign` | |
| `NeominimapGitDeleteSign` | |
| `NeominimapGitAddIcon` | |
| `NeominimapGitChangeIcon` | |
| `NeominimapGitDeleteIcon` | |
### Highlight Groups of Search Annotations
| Highlight Group | Description |
| ---------------------- | ----------- |
| `NeominimapSearchLine` | |
| `NeominimapSearchSign` | |
| `NeominimapSearchIcon` | |
### Highlight Groups of Mark Annotations
| Highlight Group | Description |
| -------------------- | ----------- |
| `NeominimapMarkLine` | |
| `NeominimapMarkSign` | |
| `NeominimapMarkIcon` | |
## Namespaces
Click to expand
| Namespace | Description |
| ----------------------- | -------------------------------- |
| `neominimap_git` | Git signs and highlights. |
| `neominimap_diagnostic` | Diagnostic signs and highlights. |
| `neominimap_search` | Search signs and highlights. |
| `neominimap_mark` | Mark signs and highlights. |
| `neominimap_treesitter` | Treesitter highlights. |
## 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](https://github.com/lewis6991/satellite.nvim),
[nvim-scrollview](https://github.com/dstein64/nvim-scrollview)
or other plugins.
- Display screen bounds like
[codewindow.nvim](https://github.com/gorbit99/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](https://github.com/gorbit99/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](https://github.com/echasnovski/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](https://github.com/wfxr/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](https://github.com/gorbit99) for
[codewindow.nvim](https://github.com/gorbit99/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](https://github.com/lewis6991) for creating the
excellent [gitsigns.nvim](https://github.com/lewis6991/gitsigns.nvim) and
[satellite.nvim](https://github.com/lewis6991/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.