mini.nvim documentation

Generated from the main branch of ‘mini.nvim’

mini.nvim Collection of minimal, independent and fast Lua modules

mini.nvim is a collection of minimal, independent, and fast Lua modules dedicated to improve Neovim (version 0.9 and higher) experience. Each module can be considered as a separate sub-plugin.

Table of contents:

General principles	mini.nvim-general-principles
Module list	mini.nvim-module-list
Disabling recipes	mini.nvim-disabling-recipes
Buffer-local config	mini.nvim-buffer-local-config
Plugin color schemes	mini.nvim-color-schemes
Extend and create a/i textobjects	mini.ai
Align text interactively	mini.align
Animate common Neovim actions	mini.animate
Base16 colorscheme creation	mini.base16
Common configuration presets	mini.basics
Go forward/backward with square brackets	mini.bracketed
Remove buffers	mini.bufremove
Show next key clues	mini.clue
Tweak and save any color scheme	mini.colors
Comment lines	mini.comment
Completion and signature help	mini.completion
Autohighlight word under cursor	mini.cursorword
Plugin manager	mini.deps
Work with diff hunks	mini.diff
Generate Neovim help files	mini.doc
Extra ‘mini.nvim’ functionality	mini.extra
Navigate and manipulate file system	mini.files
Fuzzy matching	mini.fuzzy
Git integration	mini.git
Highlight patterns in text	mini.hipatterns
Generate configurable color scheme	mini.hues
Icon provider	mini.icons
Visualize and work with indent scope	mini.indentscope
Jump to next/previous single character	mini.jump
Jump within visible lines	mini.jump2d
Special key mappings	mini.keymap
Window with buffer text overview	mini.map
Miscellaneous functions	mini.misc
Move any selection in any direction	mini.move
Show notifications	mini.notify
Text edit operators	mini.operators
Autopairs	mini.pairs
Pick anything	mini.pick
Session management	mini.sessions
Manage and expand snippets	mini.snippets
Split and join arguments	mini.splitjoin
Start screen	mini.starter
Statusline	mini.statusline
Surround actions	mini.surround
Tabline	mini.tabline
Test Neovim plugins	mini.test
Trailspace (highlight and remove)	mini.trailspace
Track and reuse file system visits	mini.visits

General principles

Design

Each module is designed to solve a particular problem targeting balance between feature-richness (handling as many edge-cases as possible) and simplicity of implementation/support. Granted, not all of them ended up with the same balance, but it is the goal nevertheless.

Independence

Modules are independent of each other and can be run without external dependencies. Although some of them may need dependencies for full experience.

Structure

Each module is a submodule for a placeholder “mini” module. For example, “surround” module should be referred to as “mini.surround”. As later will be explained, this plugin can also be referred to as “MiniSurround”.

Setup

Each module you want to use should be enabled separately with require(<name of module>).setup({}). Possibly replace {} with your config table or omit altogether to use defaults. You can supply only parts of config, the rest will be inferred from defaults.
Call to module’s setup() always creates a global Lua object with coherent camel-case name: require('mini.surround').setup() creates _G.MiniSurround. This allows for a simpler usage of plugin available from v:lua like v:lua.MiniSurround. Considering this, “module” and “Lua object” names can be used interchangeably: ‘mini.surround’ and ‘MiniSurround’ will mean the same thing.
Each supplied config table (after extending with default values) is stored in config field of global object. Like MiniSurround.config.
Values of config, which affect runtime activity, can be changed on the fly to have effect. For example, MiniSurround.config.n_lines can be changed during runtime; but changing MiniSurround.config.mappings won’t have any effect (as mappings are created once during setup()).
If module works best with some specific non-default option value, it is set during setup(). If the value is not essential to module’s functionality, it is done only if user or another plugin hasn’t set it beforehand (no matter the value).

Buffer local configuration

Each module can be additionally configured to use certain runtime config settings locally to buffer. See mini.nvim-buffer-local-config for more information.

Buffer names

All module-related buffers are named according to the following format: mini<module-name>://<buffer-number>/<useful-info> (forward slashes are used on any platform; <useful-info> may be empty). This structure allows creating identifiable, reasonably unique, and useful buffer names. For example, mini.files buffers are created per displayed directory/file with names like minifiles://10/path/to/displayed/directory.

Disabling

Each module’s core functionality can be disabled globally or locally to buffer. See “Disabling” section in module’s help page for more details. See mini.nvim-disabling-recipes for common recipes.

Silencing

Each module can be configured to not show non-error feedback globally or locally to buffer. See “Silencing” section in module’s help for more details.

Highlighting

Appearance of module’s output is controlled by certain set of highlight groups (see highlight-groups). By default they usually link to some semantically close built-in highlight group. Use :highlight command or nvim_set_hl() Lua function to customize highlighting. To see a more calibrated look, use mini.hues, MiniBase16, or plugin’s colorschemes.

Stability

Each module upon release is considered to be relatively stable: both in terms of setup and functionality. Any non-bugfix backward-incompatible change will be released gradually as much as possible.

Not filetype and language specific

Including functionality which needs several filetype/language specific implementations is an explicit no-goal of this project. This is mostly due to the potential increase in maintenance to keep implementation up to date. However, any part which might need filetype/language specific tuning should be designed to allow it by letting user set proper buffer options and/or local configuration.

Module list

mini.ai - extend and create a/i textobjects (like in di( or va"). It enhances some builtin text-objects (like a(, a), a’, and more), creates new ones (like a*, a<Space>, af, a?, and more), and allows user to create their own (like based on treesitter, and more). Supports dot-repeat, v:count, different search methods, consecutive application, and customization via Lua patterns or functions. Has builtins for brackets, quotes, function call, argument, tag, user prompt, and any punctuation/digit/whitespace character.
mini.align - align text interactively (with or without instant preview). Allows rich and flexible customization of both alignment rules and user interaction. Works with charwise, linewise, and blockwise selections in both Normal mode (on textobject/motion; with dot-repeat) and Visual mode.
mini.animate - animate common Neovim actions. Has “works out of the box” builtin animations for cursor movement, scroll, resize, window open and close. All of them can be customized and enabled/disabled independently.
MiniBase16 - fast implementation of base16 theme for manually supplied palette. Supports 30+ plugin integrations. Has unique palette generator which needs only background and foreground colors.
mini.basics - common configuration presets. Has configurable presets for options, mappings, and autocommands. It doesn’t change option or mapping if it was manually created.
mini.bracketed - go forward/backward with square brackets. Among others, supports variety of non-trivial targets: comments, files on disk, indent changes, tree-sitter nodes, linear undo states, yank history entries.
mini.bufremove - buffer removing (unshow, delete, wipeout) while saving window layout.
mini.clue - show next key clues. Implements custom key query process with customizable opt-in triggers, next key descriptions (clues), hydra-like submodes, window delay/config. Provides clue sets for some built-in concepts: g/z keys, window commands, etc.
mini.colors - tweak and save any color scheme. Can create colorscheme object with methods to invert/set/modify/etc. lightness/saturation/hue/temperature/etc. of foreground/background/all colors, infer cterm attributes, add transparency, save to a file and more. Has functionality for interactive experiments and animation of transition between color schemes.
mini.comment - fast and familiar per-line code commenting.
mini.completion - async (with customizable ‘debounce’ delay) ‘two-stage chain completion’: first builtin LSP, then configurable fallback. Also has functionality for completion item info and function signature (both in floating window appearing after customizable delay).
mini.cursorword - automatic highlighting of word under cursor (displayed after customizable delay). Current word under cursor can be highlighted differently.
mini.deps - plugin manager for plugins outside of ‘mini.nvim’. Uses Git and built-in packages to install, update, clean, and snapshot plugins.
mini.diff - visualize difference between buffer text and its reference interactively (with colored signs or line numbers). Uses Git index as default reference. Provides toggleable overview in text area, built-in apply/reset/textobject/goto mappings.
mini.doc - generation of help files from EmmyLua-like annotations. Allows flexible customization of output via hook functions. Used for documenting this plugin.
mini.extra - extra ‘mini.nvim’ functionality. Contains ‘mini.pick’ pickers, ‘mini.ai’ textobjects, and more.
mini.files - navigate and manipulate file system. A file explorer with column view capable of manipulating file system by editing text. Can create/delete/rename/copy/move files/directories inside and across directories. For full experience needs enabled mini.icons module (but works without it).
mini.fuzzy - functions for fast and simple fuzzy matching. It has not only functions to perform fuzzy matching of one string to others, but also a sorter for ‘nvim-telescope/telescope.nvim’.
mini.git - Git integration (https://git-scm.com/). Implements tracking of Git related data (root, branch, etc.), :Git command for better integration with running Neovim instance, and various helpers to explore Git history.
mini.hipatterns - highlight patterns in text with configurable highlighters (pattern and/or highlight group can be string or callable). Works asynchronously with configurable debounce delay.
mini.hues - generate configurable color scheme. Takes only background and foreground colors as required arguments. Can adjust number of hues for non-base colors, saturation, accent color, plugin integration.
mini.icons - icon provider with fixed set of highlight groups. Supports various categories, icon and style customizations, caching for performance. Integrates with Neovim’s filetype matching.
mini.indentscope - visualize and operate on indent scope. Supports customization of debounce delay, animation style, and different granularity of options for scope computing algorithm.
mini.jump - minimal and fast module for smarter jumping to a single character.
MiniJump2d - minimal and fast Lua plugin for jumping (moving cursor) within visible lines via iterative label filtering. Supports custom jump targets (spots), labels, hooks, allowed windows and lines, and more.
mini.keymap - utilities to make special key mappings: multi-step actions (with built-in steps for “smart” <Tab>, <S-Tab>, <CR>, <BS>), combos (more general version of “better escape” like behavior).
mini.map - window with buffer text overview, scrollbar, and highlights. Allows configurable symbols for line encode and scrollbar, extensible highlight integration (with pre-built ones for builtin search, diagnostic, git line status), window properties, and more.
mini.misc - collection of miscellaneous useful functions. Like put() and put_text() which print Lua objects to command line and current buffer respectively.
mini.move - move any selection in any direction. Supports any Visual mode (charwise, linewise, blockwise) and Normal mode (current line) for all four directions (left, right, down, up). Respects count and undo.
mini.notify - show one or more highlighted notifications in a single window. Provides both low-level functions (add, update, remove, clear) and maker of vim.notify() implementation. Sets up automated LSP progress updates.
mini.operators - various text edit operators: replace, exchange, multiply, sort, evaluate. Creates mappings to operate on textobject, line, and visual selection. Supports [count] and dot-repeat.
mini.pairs - autopairs plugin which has minimal defaults and functionality to do per-key expression mappings.
mini.pick - general purpose interactive non-blocking picker with toggleable preview. Has fast default matching with fuzzy/exact/grouped modes. Provides most used built-in pickers for files, pattern matches, buffers, etc. For full experience needs enabled mini.icons module (but works without it).
mini.sessions - session management (read, write, delete) which works using :mksession. Implements both global (from configured directory) and local (from current directory) sessions.
mini.snippets - manage and expand snippets. Supports only syntax from LSP specification. Provides flexible loaders to manage snippet files, exact and fuzzy prefix matching, interactive selection, and rich interactive snippet session experience with dynamic tabstop visualization.
mini.splitjoin - split and join arguments (regions inside brackets between allowed separators). Has customizable pre and post hooks. Works inside comments.
mini.starter - minimal, fast, and flexible start screen. Displayed items are fully customizable both in terms of what they do and how they look (with reasonable defaults). Item selection can be done using prefix query with instant visual feedback.
mini.statusline - minimal and fast statusline. Has ability to use custom content supplied with concise function (using module’s provided section functions) along with builtin default. For full experience needs enabled mini.diff, mini.git, and mini.icons modules (but works without any of them).
mini.surround - fast and feature-rich surround plugin. Add, delete, replace, find, highlight surrounding (like pair of parenthesis, quotes, etc.). Supports dot-repeat, v:count, different search methods, “last”/“next” extended mappings, customization via Lua patterns or functions, and more. Has builtins for brackets, function call, tag, user prompt, and any alphanumeric/punctuation/whitespace character.
mini.test - framework for writing extensive Neovim plugin tests. Supports hierarchical tests, hooks, parametrization, filtering (like from current file or cursor position), screen tests, “busted-style” emulation, customizable reporters, and more. Designed to be used with provided wrapper for managing child Neovim processes.
mini.tabline - minimal tabline which always shows listed (see ‘buflisted’) buffers. Allows showing extra information section in case of multiple vim tabpages. For full experience needs enabled mini.icons module (but works without it).
mini.trailspace - automatic highlighting of trailing whitespace with functionality to remove it.
mini.visits - track and reuse file system visits. Tracks data about each file/directory visit (after delay) and stores it (only) locally. This can be used to get a list of “recent”/“frequent”/“frecent” visits. Allows persistently adding labels to visits enabling flexible workflow.

Disabling recipes

Each module’s core functionality can be disabled globally or buffer-locally by creating appropriate global or buffer-scoped variables equal to v:true. Functionality is disabled if at least one of g: or b: variables is v:true.

Variable names have the same structure: {g,b}:mini*_disable where * is module’s lowercase name. For example, g:minianimate_disable disables mini.animate globally and b:minianimate_disable - for current buffer. Note: in this section disabling ‘mini.animate’ is used as example; everything holds for other module variables.

Considering high number of different scenarios and customization intentions, writing exact rules for disabling module’s functionality is left to user.

Manual disabling

-- Disable globally
vim.g.minianimate_disable = true

-- Disable for current buffer
vim.b.minianimate_disable = true

-- Toggle (disable if enabled, enable if disabled)
vim.g.minianimate_disable = not vim.g.minianimate_disable -- globally
vim.b.minianimate_disable = not vim.b.minianimate_disable -- for buffer

Automated disabling

Automated disabling is suggested to be done inside autocommands:

-- Disable for a certain filetype (for example, "lua")
local f = function(args) vim.b[args.buf].minianimate_disable = true end
vim.api.nvim_create_autocmd('Filetype', { pattern = 'lua', callback = f })

-- Enable only for certain filetypes (for example, "lua" and "help")
local f = function(args)
  local ft = vim.bo[args.buf].filetype
  if ft == 'lua' or ft == 'help' then return end
  vim.b[args.buf].minianimate_disable = true
end
vim.api.nvim_create_autocmd('Filetype', { callback = f })

-- Disable in Visual mode
local f_en = function(args) vim.b[args.buf].minianimate_disable = false end
local enable_opts = { pattern = '[vV\x16]*:*', callback = f_en }
vim.api.nvim_create_autocmd('ModeChanged', enable_opts)

local f_dis = function(args) vim.b[args.buf].minianimate_disable = true end
local disable_opts = { pattern = '*:[vV\x16]*', callback = f_dis }
vim.api.nvim_create_autocmd('ModeChanged', disable_opts)

-- Disable in Terminal buffer
local f = function(args) vim.b[args.buf].minianimate_disable = true end
vim.api.nvim_create_autocmd('TermOpen', { callback = f })

Buffer local config

Each module can be additionally configured locally to buffer by creating appropriate buffer-scoped variable with values to override. It affects only runtime options and not those used once during setup (like most mappings).

Variable names have the same structure: b:mini*_config where * is module’s lowercase name. For example, b:minianimate_config can store information about how mini.animate will act inside current buffer. Its value should be a table with same structure as module’s config. Example:

-- Disable scroll animation in current buffer
vim.b.minianimate_config = { scroll = { enable = false } }

Considering high number of different scenarios and customization intentions, writing exact rules for module’s buffer local configuration is left to user. It is done in similar fashion to mini.nvim-disabling-recipes.

Color schemes

Color schemes based on mini.hues: MiniHues-color-schemes.
Color schemes based on mini.base16: MiniBase16-color-schemes.