echasnovski/mini.nvim

github github
session
star 229
stars
alert-circle 10
open issues
users 5
subscribers
git-branch 13
forks
CREATED

2021-06-18

UPDATED

yesterday


mini.nvim

GitHub license GitHub tag Current version

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

Table of contents

Installation

This plugin offers two branches to install from:

  • main (default) will have latest development version of plugin. All changes since last stable release should be perceived as being in beta testing phase (meaning they already passed alpha-testing and are moderately settled).
  • stable will be updated only upon releases with code tested during public beta-testing phase in main branch.

There are at least the following ways to install this plugin:

  • Using wbthomason/packer.nvim:

    -- Development
    use 'echasnovski/mini.nvim'
    
    -- Stable
    use { 'echasnovski/mini.nvim', branch = 'stable' }
    
  • Using junegunn/vim-plug:

    " Development
    Plug 'echasnovski/mini.nvim'
    
    " Stable
    Plug 'echasnovski/mini.nvim', { 'branch': 'stable' }
    
  • Each module is independent and implemented within single file. You can copy corresponding file from 'lua/mini/' directory to your '.config/nvim/lua' directory and use it from there.

Don't forget to call module's setup() (if required) to enable its functionality.

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. So, 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 (if needed) should be setup separately with require(<name of module>).setup({}) (possibly replace {} with your config table or omit to use defaults). You can supply only values which differ from defaults, which will be used for the rest ones.
    • 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 functionality: instead of require('mini.surround') use MiniSurround (or manually :lua MiniSurround.* in command line); 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 (aft) 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()).
  • Disabling. Each module's core functionality can be disabled globally or buffer-locally by creating appropriate global or buffer-scoped variables with v:true value. For example:
    • To disable MiniSurround globally run :let g:minisurround_disable=v:true.
    • To disable MiniSurround for current buffer run :let b:minisurround_disable=v:true.
    • To toggle MiniSurround globally (disable if enabled, enable if disabled) use of Lua is more appropriate: :lua vim.g.minisurround_disable = not vim.g.minisurround_disable.
  • Highlight groups. Appearance of module's output is controlled by certain highlight group (see :h highlight-groups). To customize them, use highlight command. Note: currently not many Neovim themes support this plugin's highlight groups; fixing this situation is highly appreciated. To see a more calibrated look, use MiniBase16 or plugin's colorscheme minischeme.
  • 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.

Plugin colorscheme

This plugin comes with an official colorscheme named minischeme. This is a MiniBase16 theme created with faster version of the following Lua code: require('mini.base16').setup({palette = palette, name = 'minischeme', use_cterm = true}) where palette is:

  • For dark 'background': require('mini.base16').mini_palette('#112641', '#e2e98f', 75)
  • For light 'background': require('mini.base16').mini_palette('#e2e5ca', '#002a83', 75)

Activate it as a regular colorscheme.

All examples use this colorscheme.

Modules

mini.base16

Fast implementation of chriskempson/base16 theme for manually supplied palette. Has unique palette generator which needs only background and foreground colors.

Default config:

{
  -- Table with names from `base00` to `base0F` and values being strings of
  -- HEX colors with format "#RRGGBB". NOTE: this should be explicitly
  -- supplied in `setup()`.
  palette = nil,

  -- Whether to support cterm colors. Can be boolean, `nil` (same as
  -- `false`), or table with cterm colors. See `setup()` documentation for
  -- more information.
  use_cterm = nil,
}

For more information, read 'mini.base16' section of help file.

Plugins with similar functionality:

mini.bufremove

Buffer removing (unshow, delete, wipeout) while saving window layout.

Default config:

{
  -- Whether to set Vim's settings for buffers (allow hidden buffers)
  set_vim_settings = true,
}

For more information, read 'mini.bufremove' section of help file.

Plugins with similar functionality:

mini.comment

Fast and familiar per-line code commenting.

Default config:

{
  -- Module mappings. Use `''` (empty string) to disable one.
  mappings = {
    -- Toggle comment (like `gcip` - comment inner paragraph) for both
    -- Normal and Visual modes
    comment = 'gc',

    -- Toggle comment on current line
    comment_line = 'gcc',

    -- Define 'comment' textobject (like `dgc` - delete whole comment block)
    textobject = 'gc',
  },
}

For more information, read 'mini.comment' section of help file.

Plugins with similar functionality:

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

Default config:

{
  -- Delay (debounce type, in ms) between certain Neovim event and action.
  -- This can be used to (virtually) disable certain automatic actions by
  -- setting very high delay time (like 10^7).
  delay = { completion = 100, info = 100, signature = 50 },

  -- Maximum dimensions of floating windows for certain actions. Action
  -- entry should be a table with 'height' and 'width' fields.
  window_dimensions = {
    info = { height = 25, width = 80 },
    signature = { height = 25, width = 80 },
  },

  -- Way of how module does LSP completion
  lsp_completion = {
    -- `source_func` should be one of 'completefunc' or 'omnifunc'.
    source_func = 'completefunc',

    -- `auto_setup` should be boolean indicating if LSP completion is set up
    -- on every `BufEnter` event.
    auto_setup = true,

    -- `process_items` should be a function which takes LSP
    -- 'textDocument/completion' response items and word to complete. Its
    -- output should be a table of the same nature as input items. The most
    -- common use-cases are custom filtering and sorting. You can use
    -- default `process_items` as `MiniCompletion.default_process_items()`.
    process_items = --<function: filters out snippets; sorts by LSP specs>,
  },

  -- Fallback action. It will always be run in Insert mode. To use Neovim's
  -- built-in completion (see `:h ins-completion`), supply its mapping as
  -- string. Example: to use 'whole lines' completion, supply '<C-x><C-l>'.
  fallback_action = --<function: like `<C-n>` completion>,

  -- Module mappings. Use `''` (empty string) to disable one. Some of them
  -- might conflict with system mappings.
  mappings = {
    force_twostep = '<C-Space>', -- Force two-step completion
    force_fallback = '<A-Space>', -- Force fallback completion
  },

  -- Whether to set Vim's settings for better experience (modifies
  -- `shortmess` and `completeopt`)
  set_vim_settings = true,
}

For more information, read 'mini.completion' section of help file.

Plugins with similar functionality:

mini.cursorword

Automatic highlighting of word under cursor (displayed after customizable delay). Current word under cursor can be highlighted differently.

Default config:

{
  -- Delay (in ms) between when cursor moved and when highlighting appeared
  delay = 100,
}

For more information, read 'mini.cursorword' section of help file.

Plugins with similar functionality:

mini.doc

Generation of help files from EmmyLua-like annotations. Allows flexible customization of output via hook functions. Used for documenting this plugin.

Default config:

{
  -- Lua string pattern to determine if line has documentation annotation.
  -- First capture group should describe possible section id. Default value
  -- means that annotation line should:
  -- - Start with `---` at first column.
  -- - Any non-whitespace after `---` will be treated as new section id.
  -- - Single whitespace at the start of main text will be ignored.
  annotation_pattern = '^%-%-%-(%S*) ?',

  -- Identifier of block annotation lines until first captured identifier
  default_section_id = '@text',

  -- Hooks to be applied at certain stage of document life cycle. Should
  -- modify its input in place (and not return new one).
  hooks = {
    -- Applied to block before anything else
    block_pre = --<function: infers header sections (tag and/or signature)>,

    -- Applied to section before anything else
    section_pre = --<function: replaces current aliases>,

    -- Applied if section has specified captured id
    sections = {
      ['@alias'] = --<function: registers alias in MiniDoc.current.aliases>,
      ['@class'] = --<function>,
      -- For most typical usage see |MiniDoc.afterlines_to_code|
      ['@eval'] = --<function: evaluates lines; replaces with their return>,
      ['@field'] = --<function>,
      ['@param'] = --<function>,
      ['@private'] = --<function: registers block for removal>,
      ['@return'] = --<function>,
      ['@seealso'] = --<function>,
      ['@signature'] = --<function: formats signature of documented object>,
      ['@tag'] = --<function: turns its line in proper tag lines>,
      ['@text'] = --<function: purposefully does nothing>,
      ['@type'] = --<function>,
      ['@usage'] = --<function>,
    },

    -- Applied to section after all previous steps
    section_post = --<function: currently does nothing>,

    -- Applied to block after all previous steps
    block_post = --<function: does many things>,

    -- Applied to file after all previous steps
    file = --<function: adds separator>,

    -- Applied to doc after all previous steps
    doc = --<function: adds modeline>,
  },

  -- Path (relative to current directory) to script which handles project
  -- specific help file generation (like custom input files, hooks, etc.).
  script_path = 'scripts/minidoc.lua',
}

For more information, read 'mini.doc' section of help file (which is created with this module).

Plugins with similar functionality:

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.

Default config:

{
  -- Maximum allowed value of match features (width and first match). All
  -- feature values greater than cutoff can be considered "equally bad".
  cutoff = 100,
}

For more information, read 'mini.fuzzy' section of help file.

Plugins with similar functionality:

mini.jump

Minimal and fast module for smarter jumping to a single character. Initial idea and implementation by Adam Blažek.

Default config:

{
  -- Module mappings. Use `''` (empty string) to disable one.
  mappings = {
    forward = 'f',
    backward = 'F',
    forward_till = 't',
    backward_till = 'T',
    repeat_jump = ';',
  },

  -- Delay (in ms) between jump and highlighting all possible jumps. Set to
  -- a very big number (like 10^7) to virtually disable highlighting.
  highlight_delay = 250,
}

For more information, read 'mini.jump' section of help file.

Plugins with similar functionality:

mini.misc

Collection of miscellaneous useful functions. Like put() and put_text() which print Lua objects to command line and current buffer respectively.

Default config:

{
  -- Array of fields to make global (to be used as independent variables)
  make_global = { 'put', 'put_text' },
}

For more information, read 'mini.misc' section of help file.

mini.pairs

Autopairs plugin which has minimal defaults and functionality to do per-key expression mappings.

Default config:

{
  -- In which modes mappings from this `config` should be created
  modes = { insert = true, command = false, terminal = false },

  -- Global mappings. Each right hand side should be a pair information, a
  -- table with at least these fields (see more in |MiniPairs.map|):
  -- - <action> - one of 'open', 'close', 'closeopen'.
  -- - <pair> - two character string for pair to be used.
  -- By default pair is not inserted after `\`, quotes are not recognized by
  -- `<CR>`, `'` does not insert pair after a letter.
  -- Only parts of tables can be tweaked (others will use these defaults).
  mappings = {
    ['('] = { action = 'open', pair = '()', neigh_pattern = '[^\\].' },
    ['['] = { action = 'open', pair = '[]', neigh_pattern = '[^\\].' },
    ['{'] = { action = 'open', pair = '{}', neigh_pattern = '[^\\].' },

    [')'] = { action = 'close', pair = '()', neigh_pattern = '[^\\].' },
    [']'] = { action = 'close', pair = '[]', neigh_pattern = '[^\\].' },
    ['}'] = { action = 'close', pair = '{}', neigh_pattern = '[^\\].' },

    ['"'] = { action = 'closeopen', pair = '""', neigh_pattern = '[^\\].', register = { cr = false } },
    ["'"] = { action = 'closeopen', pair = "''", neigh_pattern = '[^%a\\].', register = { cr = false } },
    ['`'] = { action = 'closeopen', pair = '``', neigh_pattern = '[^\\].', register = { cr = false } },
  },
}

For more information, read 'mini.pairs' section of help file.

Plugins with similar functionality:

mini.sessions

Session management (read, write, delete) which works using |mksession|. It was heavily inspired by 'vim-startify' and should work out of the box with sessions created by it. Works with global (from configured directory) and local (from current directory) sessions.

Default config:

{
  -- Whether to read latest session if Neovim opened without file arguments
  autoread = false,

  -- Whether to write current session before quitting Neovim
  autowrite = true,

  -- Directory where global sessions are stored (use `''` to disable)
  directory = --<"session" subdir of user data directory from |stdpath()|>,

  -- File for local session (use `''` to disable)
  file = 'Session.vim',

  -- Whether to force possibly harmful actions (meaning depends on function)
  force = { read = false, write = true, delete = false },

  -- Whether to print session path after action
  verbose = { read = false, write = true, delete = true },
}

For more information, read 'mini.sessions' section of help file.

Plugins with similar functionality:

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.

Default config:

{
  -- Whether to open starter buffer on VimEnter. Not opened if Neovim was
  -- started with intent to show something else.
  autoopen = true,

  -- Whether to evaluate action of single active item
  evaluate_single = false,

  -- Items to be displayed. Should be an array with the following elements:
  -- - Item: table with <action>, <name>, and <section> keys.
  -- - Function: should return one of these three categories.
  -- - Array: elements of these three types (i.e. item, array, function).
  -- If `nil` (default), default items will be used (see |mini.starter|).
  items = nil,

  -- Header to be displayed before items. Should be a string or function
  -- evaluating to single string (use `\n` for new lines).
  -- If `nil` (default), polite greeting will be used.
  header = nil,

  -- Footer to be displayed after items. Should be a string or function
  -- evaluating to string. If `nil`, default usage help will be shown.
  footer = nil,

  -- Array  of functions to be applied consecutively to initial content.
  -- Each function should take and return content for 'Starter' buffer (see
  -- |mini.starter| for more details).
  content_hooks = nil,

  -- Characters to update query. Each character will have special buffer
  -- mapping overriding your global ones. Be careful to not add `:` as it
  -- allows you to go into command mode.
  query_updaters = [[abcdefghijklmnopqrstuvwxyz0123456789_-.]],
}

For more information, read 'mini.starter' section of help file (also contains example configurations similar to 'vim-startify' and 'dashboard-nvim'). For its benchmarks alongside plugins with similar functionality, see benchmarks/starter/startup-summary.md (more details here).

Plugins with similar functionality:

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 Nerd font, lewis6991/gitsigns.nvim plugin, and kyazdani42/nvim-web-devicons plugin (but works without any them).

Default config:

{
  -- Content of statusline as functions which return statusline string. See
  -- `:h statusline` and code of default contents (used instead of `nil`).
  content = {
    -- Content for active window
    active = nil,
    -- Content for inactive window(s)
    inactive = nil,
  },

  -- Whether to set Vim's settings for statusline (make it always shown)
  set_vim_settings = true,
}

For more information, read 'mini.statusline' section of help file.

Plugins with similar functionality:

mini.surround

Fast surround plugin. Add, delete, replace, find, highlight surrounding (like pair of parenthesis, quotes, etc.). Has special "function call", "tag", and "interactive" surroundings. Supports dot-repeatability, textobject, motions.

Default config:

{
  -- Number of lines within which surrounding is searched
  n_lines = 20,

  -- Duration (in ms) of highlight when calling `MiniSurround.highlight()`
  highlight_duration = 500,

  -- Pattern to match function name in 'function call' surrounding
  -- By default it is a string of letters, '_' or '.'
  funname_pattern = '[%w_%.]+',

  -- Module mappings. Use `''` (empty string) to disable one.
  mappings = {
    add = 'sa', -- Add surrounding
    delete = 'sd', -- Delete surrounding
    find = 'sf', -- Find surrounding (to the right)
    find_left = 'sF', -- Find surrounding (to the left)
    highlight = 'sh', -- Highlight surrounding
    replace = 'sr', -- Replace surrounding
    update_n_lines = 'sn', -- Update `n_lines`
  },
}

For more information, read 'mini.surround' section of help file.

Plugins with similar functionality:

mini.tabline

Minimal tabline which shows listed (see :h buflisted) buffers in case of one tab and falls back to default otherwise. For full experience needs kyazdani42/nvim-web-devicons.

Default config:

{
  -- Whether to show file icons (requires 'kyazdani42/nvim-web-devicons')
  show_icons = true,

  -- Whether to set Vim's settings for tabline (make it always shown and
  -- allow hidden buffers)
  set_vim_settings = true,
}

For more information, read 'mini.tabline' section of help file.

Plugins with similar functionality:

mini.trailspace

Automatic highlighting of trailing whitespace with functionality to remove it.

Default config:

{
  -- Highlight only in normal buffers (ones with empty 'buftype'). This is
  -- useful to not show trailing whitespace where it usually doesn't matter.
  only_in_normal_buffers = true,
}

For more information, read 'mini.trailspace' section of help file.

Plugins with similar functionality:

Planned modules

This is the list of modules I currently intend to implement eventually (as my free time and dedication will allow):

  • 'mini.doc' - automatic generation of (Neo)Vim help files from EmmyLua-like annotations next to source code. Something like similar functionality of tjdevries/tree-sitter-lua.
  • 'mini.indentscope' - show (with vertical line) indent scope under cursor after customizable delay.
  • 'mini.align' - fast text alignment. Something like tommcdo/vim-lion.
  • 'mini.terminal' (or 'mini.repl') - coherently manage terminal windows and send text from buffers to terminal windows. Something like kassio/neoterm.
  • 'mini.exchange' (or 'mini.swap') - exchange two regions of text. Something like tommcdo/vim-exchange.
  • 'mini.arguments' - work with listed arguments. Something like FooSoft/vim-argwrap and AndrewRadev/sideways.vim.
  • 'mini.tree' - file tree explorer. Truncated version of kyazdani42/nvim-tree.