My Mini Neovim Config

涛叔 2024-09-21 ⏳9.0 min(3.6k words) 🕸️

⛔Warning
None native English speaker. Forgive my Plastic English.🙏

Hello, Guys. Today, I want to introduce you my minimized config of Neovim. I have used Vim/Neovim for almost 10 years. In the beginning, I tended to add more and more configuration and plugins. However, after some years, I have realized that, the more experiences about Vim/Neovim I have, the less configuration or plugins I need. As a result, I try to drop all the unnecessary configuration and plugins as far as I can. So here is my mini Neovim config.

In the my early days of using Vim, I have to add some routine configs. For example, I have to manual enable filetype/syntax/autoindent in the vimrc. Thanks to Neovim, many of these routine options have been setted by default, so I can drop them from the vimrc. This leads my first principle that use and adapt to the default configuration as far as possible.

And I am always following another principle that only add configuration that you understand.

Now let me show you my basic configuration in the ~/.config/nvim/init.vim.

Basic configs

No Mouse

First and foremost, disable the mouse.

set mouse=

The default value of mouse is nvi, which means that Neovim enables mouse in the modes of Normal, Visual, and Insert. In my opinion, if you want to sharpen your Vim sense, you should avoid using mouse as much as possible. On the other hand, enabling mouse do have some annoying byproduct effects. For example, in the default configuration, you can not select text in the Normal mode because vim will enter the Visual mode when you select by mouse.

So close it and forget it.

Visual options

Then I need tweak several visual options.

set linebreak
set cursorline
set laststatus=3
set colorcolumn=80
set termguicolors
set foldmethod=expr
set foldexpr=v:lua.vim.treesitter.foldexpr()

I open the linebreak, so that the whole line of text can be showed in the narrow window with soft wrap. I open the cursorline to highlight the line under cursor. Setting the laststatus to 3 let vim show the status line below all window. And the colorcolumn=80 will indicate me that my code or text may be too wide. And finally, the termguicolors will enable the support of true color, which may let your vim more colorful. Almost all mainstream terminal emulator support the 24-bit true color mode. However, this is not the case of the builtin Terminal app of macOS. Ashamed.

💡Tip
By the way, I am using the WezTerm.

Then are options for folding. Combining both the foldmethod and foldexpr, Vim will fold lines according to the response of lua.vim.treesitter.foldexpr(). The Treesitter need additional config that located in a dedicate plugin. And I will explain more in detail later in this article.

The last problem of visual effects is color scheme. There are tones of color schemes across the Internet. The last one I use, which supports the 24-bit true color, is tender¹. It is beautiful and delightful. The default color scheme of vim used to be unpleasant. However, the Neovim has fixed it². So I just migrate to the new default color scheme as soon as possible.

But not every corner of the default color scheme suits my taste. I do not like it’s background, so I dropped it. And the color of status line is a little to bright, I changed it.

highlight Normal guibg=none
highlight StatusLine guibg=#303030 guifg=#adadad

Searching

So these are all my options for appearance. Now let’s tweak some behaviors of searching.

set ignorecase
set smartcase

By setting the ignorecase, vim will ignore the case of letter for searching, which will be very convenient. However, there are scenarios that you have to search content in the case sensitive way. This is why I enable the smartcase. With this option, if you type keywords contains upper case letter, vim will search in the case sensitive way.

Editing

The final part of basic configuration is for editing.

set formatoptions+=ro
set completeopt+=fuzzy,noinsert,popup

The formatoptions+=ro means appending the options r and o to formatoptions. And it let vim automatically insert the comment leader like // or * if you are editing the comments of programming. The r is for create new line by the Enter key and the o is for creating new line by hit o or O. You can use :h fo-table to get more details. This will be great convenient for programmer.

The completeopt option is for auto completing. Yes, Vim has builtin auto completing function, which can be triggered by <ctrl-x><ctrl-o> in the Insert mode. I append three flags. fuzzy is for fuzzy searching to filter the candidates; noinsert means do not replace the current inputted text using the candidates; popup means show the additional information, like documents of function, in an pop-up window next to the candidates list, instead of the preview window above. All of these flags ares not required, but just for convenience. Just choose according to your preference.

The above content is all about basic configuration. Now let me show you some advanced :)

Remember last position

The only non-basic configuration I want to show is letting vim jump to the last position you exit.

autocmd BufReadPost *
      \ if line("'\"") >= 1 && line("'\"") <= line("$")
      \ |   exe "normal! g`\""
      \ | endif

The autocmd means register callback for certain events. In this case, the event is BufReadPost, which will be triggered after vim has loaded the content of file from disk. And the asterisk * means this callback will be applied to all types of file.

The below lines with prefix of \\ means they are the continuation part of the first line containing the autocmd. With the above configuration, after loading the file content, vim will execute the following if statement.

if line("'\"") >= 1 && line("'\"") <= line("$")
  exe "normal! g`\""
endif

If you want to write all three lines into one line, you have to insert the |.

if line("'\"") >= 1 && line("'\"") <= line("$") | exe "normal! g`\"" | endif

The function call of line("'\"") looks like weird, but its meaning is very simple. Calling the line() function on some position will return the line number of this position. The real argument of line() is '". The single quotation mark ' means retrieve content from some register. Vim has many registers, and every one has a name. The register whose name is double quotation mark " is a special one, because Vim will save the current position of cursor into it automatically. So the call of line("'\"") will get the line number of the last position of cursor. Then the if will compare it with the first line number of 1 and the last line retrieved by line("$"). If the line number of last position is in the middle of the file, it will execute the following directive:

exe "normal! g`\""

The exe means execute, it will let vim execute the following content normal! g`\“, which will emulate in the normal mode striking g, `, and ". As a result, vim will jump the position of the cursor when you last exit.

So far, we have the following content in init.vim:

set mouse=
set linebreak
set cursorline
set colorcolumn=80
set smartcase
set ignorecase
set termguicolors
set formatoptions+=ro
set foldmethod=expr
set foldexpr=v:lua.vim.treesitter.foldexpr()
set completeopt+=fuzzy,noinsert,popup
set laststatus=3

highlight Normal guibg=none
highlight StatusLine guibg=#303030 guifg=#adadad

autocmd BufReadPost *
      \ if line("'\"") >= 1 && line("'\"") <= line("$")
      \ |   exe "normal! g`\""
      \ | endif

Plugins

And now, it is time to introduce the plugins. What Vim is for if you don’t install any plugin? But before our journey, there is one more question to discuss.

Should we use the init.lua instead of init.vim?

`init.lua` vs `init.vim`

Many guys have migrated their init.vim into init.lua. But as far as I’m concerned, it seems more rational to use both of them. The lua is more flexible for dynamic configuration, yet the viml is more clear for static one.

Suppose you want to let vim display line number.

By the init.vim, you need to add

set number

By the init.lua, you need to add

vim.opt.number = true

Which one is more clear? If this example is not typical, I can offer another one.

Recall the aforementioned completeopt option:

set completeopt+=fuzzy,noinsert,popup

The lua version of it is:

vim.opt.completeopt:append({'fuzzy', 'noinsert', 'popup'})

Which one is more clear? I prefer the viml one.

The init.vim can be treated as a DSL of init.lua. For static and short configuration, put them into init.vim. For dynamic and complicated ones, organize them into init.lua.

As Neovim will read the init.lua first. So I create the lua file named after vim.lua, and add the following line in the bottom of the init.vim to load it.

runtime vim.lua

OK, we are ready to begin the topic of plugins.

Plugin Managers

If you already have some experiences of vim plugin, you must known the plugins that manage other plugins. In my early days of using vim, plugins like vundle, vim-plug, dein are popular. But now, some lua-based plugins like lazy.nvim or packer.nvim are in the ascendant. Besides, vim also introduce builtin mechanism to manage plugins.

In my opinion, it is enough to use the builtin package feature plus Git. So I choose to use the git submodule to manage my few plugins.

The builtin package feature is very simple. Vim will load all packages located in the pack/*/start path. The asterisk here can be any folder name you like. I choose to use vendor to name it. So my plugins are locating at pack/vendor/start.

Currently there are only 9 plugins are used by me. Four of them are for file management and searching. Two of them are for Git integrating. One is for treesitter, one is for folding, and the last for LSP. Here is the directory structure:

├── init.vim
├── pack/vendor/start
│   ├── ag
│   ├── fzf
│   ├── gitsigns
│   ├── lspconfig
│   ├── mru
│   ├── pretty-fold
│   ├── tree
│   ├── treesitter
│   └── vimagit
└── vim.lua

Git as Manager

Using Git to manage plugins is very simple. Every plugins is a submodule. For example, if you want to install the nvim-treesitter, you can

git submoduel add https://github.com/nvim-treesitter/nvim-treesitter pack/vendor/treesitter

If you want to update one plugin, you can

git submodule update --remote pack/vendor/treesitter

If you want to update all plugins, you can

git submodule update --remote

If you want to show the commit logs of plugins, you can

git diff --submodule=log

If you want to delete one plugin, you can

git rm -rf pack/vendor/start/treesitter

There is no new configuration grammar to learn. It just works. The other popular plugin manager may have a beautiful UI, but they are very complicate as well. I do not need them.

As we have the ability to manage our them, it’s time to introduce my heirloom plugins.

NvimTree

First, we need a file explorer. I used to use the NerdTree, and now migrated to NvimTree. I have written one dedicated post to introduce this migration³. You can read it for more detail.

git submodule https://github.com/nvim-tree/nvim-tree.lua pack/vendor/start/tree

It’s a lua plugin, so we need enable it in the vim.lua:

vim.g.loaded_netrw = 1
vim.g.loaded_netrwPlugin = 1
require("nvim-tree").setup()

The lua package name is nvim-tree, no matter where the directory you save.

In the first two lines, I disable the builtin newrw plugin. And the third line setups the nvim-tree.

Reboot Neovim, you can use :NvimTreeToggle to open or close the explorer. If you want to open the explorer and focus on the current opened file, you can use the :NvimTreeFindFile command. Both of these commands are very frequently used, so I add two keymap to them:

nnoremap <silent> <leader>e :NvimTreeToggle<cr>
nnoremap <silent> <leader>f :NvimTreeFindFile<cr>

Here comes my third principle, use the default keymap as much as possible, and only map your own one when unavoidable. If you want to map your own key, try to use the <leader> key as prefix to avoid overriding the default keymap.

The default key of <leader> is \\. Some one may change it to ,. I don’t recommend you do it, because , and ; is a pair key for inline-searching. You can type fa to find the next a in the current line. Then you can strike ; to jump to the next one, and strike , to the previous one. If you use , as <leader>, the inline-searching will be lame.

Some one may remap <leader> to the space. It looks like a good idea. The space is the easiest key to type, and you hardly ever use it in the Normal mode. It depends on you. But I still prefer the default key map.

ag/fzf/mru

Besides NvimTree, I also use three self-developed tiny plugins:

ag⁴ use the_silver_searcher (ag) to search by content across files, and save matched paths into quickfix list.
fzf⁵ use the fzf to search by the path and name of files
mru⁶ record and show the most recently used files

All the three plugins are developed by myself. They are developed using very short VimScript. None of them need additional configuration, just put them into the pack/vendor/start. All you need is to set one key map to use them:

nnoremap <silent> <leader>r :Mru<cr>
nnoremap <silent> <leader>s :call fzf#Open()<cr>

I choose <leader>r to open the MRU list, r is for recent. And I choose <leader>s to open the fzf search window, s is for search. As for ag, there is no need to set key map, because you can only use it under the command mode like:

:Ag --lua hello

All the three plugins are good examples for learning vim plugin development. I have written three articles to explain how they work:

However, these articles are written in Chinese. You may read them with the help of something like Google Translate.

OK, we have introduced all file related plugins. Now let’s go on for plugins about Git.

Git Integration

I use gitsins⁷ to show the changing status of Git. And it can also be used to show the diff by :Gitsigns diffthis and show the blame by :Gitsigns blame. It is very fast and the diff view is very nice.

Install:

git submodule add https://github.com/lewis6991/gitsigns.nvim pack/vendor/start/gitsigns

The default configuration is fine for me, so just put one into vim.lua to enable it.

require'gitsigns'.setup()

The vimagit⁸ is used for interactive staging⁹, which means you can add only certain parts of you change to staging area. It is very useful to organize you commit history.

vimagit is a classical vim script plugins, there is no need to setup additional configuration for it, just put it int the start directory.

git submodule add https://github.com/jreybert/vimagit pack/vendor/start/vimagit

OK, the Git part has finished. Now let’s begin the Treesitter part.

Treesitter

In the basic part, I use the v:lua.vim.treesitter.foldexpr() to calculate to folding range. It is offered by the Treesitter module of Neovim. In order to support different languages for syntax highlight, folding, we need to install the nvim-treesitter¹⁰ plugin. The goal of nvim-treesitter is to provide a simple and easy way to use the interface for tree-sitter in Neovim.

Install nvim-treesitter:

git submodule add https://github.com/nvim-treesitter/nvim-treesitter pack/vendor/start/treesitter

I enable the feature of highlight and indent in the vim.lua:

require'nvim-treesitter.configs'.setup {
    highlight = {
        enable = true,
        additional_vim_regex_highlighting = false,
    },
    indent = {
        enable = true,
    },
}

The folding support has already been setted by the foldexpr option. In the highlight part of configuration, I also disable the regex based highlighting feature to disable duplicated highlight, hoping it will improve the speed to open big file.

Neovim defaults support the treesitter configs of c/lua/viml/vimdoc/markdown. If you need to support other language, you should use the :TSInstall <name> to install it. You can use :TSInstallInfo to show the installed and supported language modules.

Pretty Fold

When it comes to folding, I can’t help but recommend one additional plugin, the pretty-fold. Unfortunately, the original project¹¹ seems to be abandoned. This folk¹² is still under maintaining.

The killer feature of pretty-fold is that it puts the folded line number in the tail of current line and retain column of folded code, which is far more clear. So there is no need to install additional tag list plugins.

Install:

git submodule add https://github.com/bbjornstad/pretty-fold.nvim pack/vendor/start

Only one line is needed to enable it in the vim.lua:

require('pretty-fold').setup()

LSP

Finally, we come to the last part of this article, the plugins for the Language Server Protocol (LSP). Neovim has an official repository for configs of common language servers.

Install:

git submodule https://github.com/neovim/nvim-lspconfig pack/vendor/start/lspconfig

Every common programming language may have one ore more language servers. You should choose which one to use and install manually. For me, I use the gopls¹³ for Golang, and rust_analyzer¹⁴ for Rust. How to install these language server is beyond the scope of this post.

The main purpose of the LSP part of this post is to show that there is no need to install additional plugin to use LSP. %he builtin omnifunc can complete items from LSP. All you need is put the following lines into your vim.lua:

local lsp = require'lspconfig'
lsp.gopls.setup({})
lsp.rust_analyzer.setup({})

And it just works for Golang and Rust, if you have installed the corresponding LSP. You can strike <ctrl-x><ctrl-o> to trigger the complete menu, and Neovim will show the candidates coming from LSP.

The latest Neovim will setup many key mappings by default:

K is mapped in Normal mode for vim.lsp.buf.hover()
grn is mapped in Normal mode to vim.lsp.buf.rename()
gra is mapped in Normal and Visual mode to vim.lsp.buf.code_action()
grr is mapped in Normal mode to vim.lsp.buf.references()
<C-S> is mapped in Insert mode to vim.lsp.buf.signature_help()

Some other programming related options will also be modified by default:

omnifunc is set to vim.lsp.omnifunc(), use <C-x><C-o> in insert mode to trigger completion.
tagfunc is set to vim.lsp.tagfunc(). This enables features like go-to-definition, :tjump, and keymaps like <C-]>,<-W_],C-W_}` to utilize the language server.
formatexpr is set to vim.lsp.formatexpr(), so you can format lines via gq if the language server supports it.

Almost all keymaps about programming will work out of box. However, there are some frequently used methods that are not mapped. We need add our own map in vim.lua:

vim.api.nvim_create_autocmd('LspAttach', {
    callback = function(args)
        local function buf_set_keymap(keys, callback)
            local opts = { noremap=true, silent=true, callback=callback }
            vim.api.nvim_buf_set_keymap(args.buf, 'n', keys, '', opts)
        end

        buf_set_keymap('gD', vim.lsp.buf.declaration)
        buf_set_keymap('gd', vim.lsp.buf.definition)
        buf_set_keymap('gri', vim.lsp.buf.implementation)
    end,
})

In this snippet, I create a callback for the event LspAttach. Every time the Neovim start the LSP client, it will execute the callback function.

In my callback, I try to setup some keymaps. Use the lua method nvim_buf_set_keymap is very powerful, yet very complicated. The first argument is buffer id. The second is mode, which we only map in the Normal mode. The third one is the keys we want to use for mapping. The fourth is the target key. But we want to call lua method, so leave it to empty. And the last one is for options. We set the flags of noremap and silent, and the callback is the target lua method.`

As I said before, the lua method is complicated, but very flexible. In the snippet, I define one helper of buf_set_keymap to wrap nvim_buf_set_keymap, and use it to simplify the mapping process. It’s really nice.

I mapped the gD to jump to the declaration of symbol, and gd to the definition. The gri is mapped to jump to the implementation of interface, which is very frequently used by myself. Feel free to add you own map.

Conclusion

Finally, I have shown you all the minimized config of my Neovim. You can find the whole repo with ten years of commit history from here. I hope this article can bring inspiration to you. If you have any questions or suggestions, feel free to leave message to me. Enjoy 🥂🎊

My Mini Neovim Config

Basic configs

No Mouse

Visual options

Searching

Editing

Remember last position

Plugins

init.lua vs init.vim

Plugin Managers

Git as Manager

NvimTree

ag/fzf/mru

Git Integration

Treesitter

Pretty Fold

LSP

Conclusion

`init.lua` vs `init.vim`