8000 mini.nvim/doc/mini-basics.txt at main · TailwindRider/mini.nvim · GitHub
[go: up one dir, main page]
Skip to content

mini-basics.txt

Latest commit

 

History

History
361 lines (289 loc) · 12.8 KB

mini-basics.txt

File metadata and controls

361 lines (289 loc) · 12.8 KB
Raw
*mini.basics* Common configuration presets
MIT License Copyright (c) 2023 Evgeni Chasnovski
------------------------------------------------------------------------------
*MiniBasics*
Install, create `init.lua`, add `require('mini.basics').setup()`, and you
are good to go.
Features:
- Presets for common options. It will only change option if it wasn't
manually set before. See more in |MiniBasics.config.options|.
- Presets for common mappings. It will only add a mapping if it wasn't
manually created before. See more in |MiniBasics.config.mappings|.
- Presets for common autocommands. See more in |MiniBasics.config.autocommands|.
- Reverse compatibility is a high priority. Any decision to change already
present behavior will be made with great care.
Notes:
- Main goal of this module is to provide a relatively easier way for
new-ish Neovim users to have better "works out of the box" experience
while having documented relevant options/mappings/autocommands to study.
It is based partially on survey among Neovim users and partially is
coming from personal preferences.
However, more seasoned users almost surely will find something useful.
Still, it is recommended to read about used options/mappings/autocommands
and decide if they are needed. The main way to do that is by reading
Neovim's help pages (linked in help file) and this module's source code
(thoroughly documented for easier comprehension).
# Setup ~
This module needs a setup with `require('mini.basics').setup({})` (replace
`{}` with your `config` table). It will create global Lua table `MiniBasics`
which you can use for scripting or manually (with `:lua MiniBasics.*`).
See |MiniBasics.config| for available config settings.
To stop module from showing non-error feedback, set `config.silent = true`.
# Comparisons ~
- [tpope/vim-sensible](https://github.com/tpope/vim-sensible):
- Most of `tpope/vim-sensible` is already incorporated as default
options in Neovim (see |nvim-defaults|). This module has a much
broader effect.
- [tpope/vim-unimpaired](https://github.com/tpope/vim-unimpaired):
- The `tpope/vim-unimpaired` has mapping for toggling options with `yo`
prefix. This module implements similar functionality with `\` prefix
(see |MiniBasics.config.mappings|).
------------------------------------------------------------------------------
*MiniBasics.setup()*
`MiniBasics.setup`({config})
Module setup
Parameters ~
{config} `(table|nil)` Module config table. See |MiniBasics.config|.
Usage ~
>lua
require('mini.basics').setup() -- use default config
-- OR
require('mini.basics').setup({}) -- replace {} with your config table
<
------------------------------------------------------------------------------
*MiniBasics.config*
`MiniBasics.config`
Defaults ~
>lua
MiniBasics.config = {
-- Options. Set field to `false` to disable.
options = {
-- Basic options ('number', 'ignorecase', and many more)
basic = true,
-- Extra UI features ('winblend', 'listchars', 'pumheight', ...)
extra_ui = false,
-- Presets for window borders ('single', 'double', ...)
-- Default 'auto' infers from 'winborder' option
win_borders = 'auto',
},
-- Mappings. Set field to `false` to disable.
mappings = {
-- Basic mappings (better 'jk', save with Ctrl+S, ...)
basic = true,
-- Prefix for mappings that toggle common options ('wrap', 'spell', ...).
-- Supply empty string to not create these mappings.
option_toggle_prefix = [[\]],
-- Window navigation with <C-hjkl>, resize with <C-arrow>
windows = false,
-- Move cursor in Insert, Command, and Terminal mode with <M-hjkl>
move_with_alt = false,
},
-- Autocommands. Set field to `false` to disable
autocommands = {
-- Basic autocommands (highlight on yank, start Insert in terminal, ...)
basic = true,
-- Set 'relativenumber' only in linewise and blockwise Visual mode
relnum_in_visual_mode = false,
},
-- Whether to disable showing non-error feedback
silent = false,
}
<
# Options ~
*MiniBasics.config.options*
Usage example: >lua
require('mini.basics').setup({
options = {
basic = true,
extra_ui = true,
win_borders = 'double',
}
})
<
## options.basic ~
The `config.options.basic` sets certain options to values which are quite
commonly used (judging by study of available Neovim pre-configurations,
public dotfiles, and surveys).
Any option is changed only if it was not set manually beforehand.
For exact changes, please see source code (`lua/mini/basics.lua`).
Here is the list of affected options (put cursor on it and press |CTRL-]|):
- General:
- Sets |<Leader>| key to |<Space>|. Be sure to make all Leader mappings
after this (otherwise they are made with default <Leader>).
- Runs `:filetype plugin indent on` (see |:filetype-overview|)
- |'backup'|
- |'mouse'|
- |'undofile'|
- |'writebackup'|
- Appearance
- |'breakindent'|
- |'cursorline'|
- |'fillchars'|
- |'linebreak'|
- |'number'|
- |'ruler'|
- |'showmode'|
- |'signcolumn'|
- |'shortmess'|
- |'splitbelow'|
- |'splitkeep'|
- |'splitright'|
- |'wrap'|
- Editing
- |'completeopt'|
- |'formatoptions'|
- |'ignorecase'|
- |'incsearch'|
- |'infercase'|
- |'smartcase'|
- |'smartindent'|
- |'virtualedit'|
## options.extra_ui ~
The `config.options.extra_ui` sets certain options for visual appearance
which might not be aligned with common preferences, but still worth trying.
Any option is changed only if it was not set manually beforehand.
For exact changes, please see source code (`lua/mini/basics.lua`).
List of affected options:
- |'list'|
- |'listchars'|
- |'pumblend'|
- |'pumheight'|
- |'winblend'|
- Runs `:syntax on` (see |:syntax-on|)
## options.win_borders ~
The `config.options.win_borders` updates |'fillchars'| to have a consistent set
of characters for window border (`vert`, `horiz`, `msgsep`, etc.).
A 8000 vailable values:
- `'auto'` - infer from |'winborder'|. On Neovim<0.11 do nothing.
- `'bold'` - bold lines.
- `'dot'` - dot in every cell.
- `'double'` - double line.
- `'single'` - single line.
- `'solid'` - no symbol, only background.
# Mappings ~
*MiniBasics.config.mappings*
Usage example: >lua
require('mini.basics').setup({
mappings = {
basic = true,
option_toggle_prefix = [[\]],
windows = true,
move_with_alt = true,
}
})
<
If you want some mappings to be different or not made at all, set or delete
them after calling |MiniBasics.setup()|.
## mappings.basic ~
The `config.mappings.basic` creates mappings for certain commonly mapped actions
(judging by study of available Neovim pre-configurations and public dotfiles).
Some of the mappings override built-in ones to either improve their
behavior or override its default not very useful action.
It will only add a mapping if it wasn't manually created before.
Here is a table with created mappings : >
|Keys | Modes | Description |
|-------|-----------------|-----------------------------------------------|
| j | Normal, Visual | Move down by visible lines with no [count] |
| k | Normal, Visual | Move up by visible lines with no [count] |
| go | Normal | Add [count] empty lines after cursor |
| gO | Normal | Add [count] empty lines before cursor |
| gy | Normal, Visual | Copy to system clipboard |
| gp | Normal, Visual | Paste from system clipboard |
| gV | Normal | Visually select latest changed or yanked text |
| g/ | Visual | Search inside current visual selection |
| * | Visual | Search forward for current visual selection |
| # | Visual | Search backward for current visual selection |
| <C-c> | Normal | Stop, clear, redraw |
| <C-s> | Normal, Visual, | Save and go to Normal mode |
| | Insert | |
<
Notes:
- See |[count]| for its meaning.
- The <C-c> mapping is basically a combination of |CTRL-C| and |CTRL-L-default|.
This combines related actions under one mapping. Particularly useful with
enabled `mappings.windows` as it overrides |CTRL-L-default|.
- On Neovim>=0.11 there are |[<Space>| / |]<Space>| for adding empty lines.
The `gO` and `go` mappings are still created as they are more aligned with
similarly purposed |O| and |o| keys (although sometimes conflict with |gO|).
## mappings.option_toggle_prefix ~
The `config.mappings.option_toggle_prefix` defines a prefix used for
creating mappings that toggle common options. The result mappings will be
`<prefix> + <suffix>`. For example, with default value, `\w` will toggle |'wrap'|.
Other viable choices for prefix are
- `,` (as a mnemonic for several values to toggle).
- `|` (as a same mnemonic).
- `yo` (used in `tpope/vim-unimpaired`)
- Something with |<Leader>| key, like `<Leader>t` (`t` for "toggle"). Note:
if your prefix contains `<Leader>` key, make sure to set it before
calling |MiniBasics.setup()| (as is done with default `basic` field of
|MiniBasics.config.options|).
After toggling, there will be a feedback about the current option value if
prior to `require('mini.basics').setup()` module wasn't silenced (see
"Silencing" section in |mini.basics|).
It will only add a mapping if it wasn't manually created before.
Here is a list of suffixes for created toggling mappings (all in Normal mode):
- `b` - |'background'|.
- `c` - |'cursorline'|.
- `C` - |'cursorcolumn'|.
- `d` - diagnostic (via |vim.diagnostic| functions).
- `h` - |'hlsearch'| (or |v:hlsearch| to be precise).
- `i` - |'ignorecase'|.
- `l` - |'list'|.
- `n` - |'number'|.
- `r` - |'relativenumber'|.
- `s` - |'spell'|.
- `w` - |'wrap'|.
## mappings.windows ~
The `config.mappings.windows` creates mappings for easier window manipulation.
It will only add a mapping if it wasn't manually created before.
Here is a list with created Normal mode mappings (all respect |[count]|):
- Window navigation:
- `<C-h>` - focus on left window (see |CTRL-W_H|).
- `<C-j>` - focus on below window (see |CTRL-W_J|).
- `<C-k>` - focus on above window (see |CTRL-W_K|).
- `<C-l>` - focus on right window (see |CTRL-W_L|).
Note: this overrides |CTRL-L-default|. Use <C-c> set up in `mappings.basic`.
- Window resize (all use arrow keys; variants of |:resize|; respect |[count]|):
- `<C-left>` - decrease window width.
- `<C-down>` - decrease window height.
- `<C-up>` - increase window height.
- `<C-right>` - increase window width.
## mappings.move_with_alt ~
The `config.mappings.move_with_alt` creates mappings for a more consistent
cursor move in Insert, Command, and Terminal modes. For example, it proves
useful in combination of autopair plugin (like |mini.pairs|) to move right
outside of inserted pairs (no matter what the pair is).
It will only add a mapping if it wasn't manually created before.
Here is a list of created mappings (`<M-x>` means `Alt`/`Meta` plus `x`):
- `<M-h>` - move cursor left. Modes: Insert, Terminal, Command.
- `<M-j>` - move cursor down. Modes: Insert, Terminal.
- `<M-k>` - move cursor up. Modes: Insert, Terminal.
- `<M-l>` - move cursor right. Modes: Insert, Terminal, Command.
# Autocommands ~
*MiniBasics.config.autocommands*
Usage example: >lua
require('mini.basics').setup({
autocommands = {
basic = true,
relnum_in_visual_mode = true,
}
})
<
## autocommands.basic ~
The `config.autocommands.basic` creates some common autocommands:
- Starts insert mode when opening terminal (see |:startinsert| and |TermOpen|).
- Highlights yanked text for a brief period of time. See |vim.hl.on_yank()|
(which is |vim.hl.hl_op()| on Neovim>=0.13 and |vim.highlight.on_yank()|
on Neovim<0.11) and |TextYankPost|.
## autocommands.relnum_in_visual_mode ~
The `config.autocommands.relnum_in_visual_mode` creates autocommands that
enable |'relativenumber'| in linewise and blockwise Visual modes and disable
otherwise. See |ModeChanged|.
------------------------------------------------------------------------------
*MiniBasics.toggle_diagnostic()*
`MiniBasics.toggle_diagnostic`()
Toggle diagnostic for current buffer
This uses |vim.diagnostic| functions per buffer.
Return ~
`(string)` String indicator for new state. Similar to what |:set| `{option}?` shows.
vim:tw=78:ts=8:noet:ft=help:norl:
0