DEV Community: Heiker

Simple Neovim config

Heiker — Wed, 18 Sep 2024 13:04:58 +0000

Can I offer you a nice Neovim configuration in this trying time?

40 lines of code. That's all you need to have a solid starting point. Believe it or not, even those IDE-like features people talk about online can be enabled using just 1 plugin and a few keymaps.

You can try this simple config and then add new things to it based on the problems you encounter along the way. Or just take this as an opportunity to learn about the basics of Neovim configuration.

Installing Neovim

We are going to need Neovim v0.9 or greater. But be aware a lot of plugins written in lua only guarantee support for the latest stable version. Right now that's v0.12 which was released on March 29, 2026.

If you are on linux, pay attention to the version your package manager has available.

If you know how to install precompiled executables you can download the latest version from the github releases.

There is also a Neovim version manager called bob. You can try it: MordechaiHadad/bob

The config file

The entry point for our Neovim configuration will be a file called init.lua. The location of this file can change depending on the operating system, so to save ourselves some trouble we will create it using Neovim in headless mode.

Execute this command on the terminal.

nvim --headless -c 'exe "write ++p" stdpath("config") . "/init.lua"' -c 'quit'

Once the configuration file exists we can check where it is using this command in the terminal:

nvim --headless -c 'echo $MYVIMRC' -c 'quit'

Now we can start adding some code. But first, if you are not familiar with lua I suggest taking some time to understand the syntax of the language.

There is no need to memorize everything or become a lua expert, just review the syntax and have a reference at hand.

Editor settings

Neovim's defaults are actually good but there are still a few options that need to be enabled/changed. To do this in lua vim.o is the recommended method. We access a property through vim.o and assign a value to it. Like this.

vim.o.option_name = value

Where option_name can be anything on this list: Quickref - option list.

Here's some basic settings that you may find useful:

Enable line numbers.

vim.o.number = true

Disable line wrapping

vim.o.wrap = false

Adjust the width of the tab character.

vim.o.tabstop = 2
vim.o.shiftwidth = 2

Ignore case when the search pattern is all lowercase

vim.o.smartcase = true
vim.o.ignorecase = true

Clear search highlights after submit

vim.o.hlsearch = false

Reserve a space in the gutter for signs. Some plugins use this to show icons.

vim.o.signcolumn = 'yes'

Changing Neovim's theme

The way we do this in lua is using vim.cmd. Use vim.cmd to execute the command colorscheme.

Ideally, we would do something like this.

vim.cmd.colorscheme('retrobox')

There is nothing wrong with the example above. That is the correct way to change the theme. However, retrobox is a recent a addition to Neovim. If you have Neovim v0.9.5 or lower the command will fail. For the sake of backwards compatibility I will recommend using a "protective call," this way you can setup a backup theme just in case.

local ok_theme = pcall(vim.cmd.colorscheme, 'retrobox')
if not ok_theme then
  vim.cmd.colorscheme('habamax')
end

Clipboard interaction

This is where we learn about vim.keymap.set(), the function we use to create new keymaps.

By default when you copy some text using the y keymap Neovim will store that in a register. The p keymap, which we use to paste, also uses the same register as y. Basically, Neovim will ignore the system clipboard. We can still use it but we have to be explicit.

Now, I like to keep the default behavior and what I do is create new keymaps to use the system clipboard.

vim.keymap.set({'n', 'x'}, 'gy', '"+y', {desc = 'Copy to clipboard'})
vim.keymap.set({'n', 'x'}, 'gp', '"+p', {desc = 'Paste clipboard text'})

With this gy will be the keymap to copy content to the clipboard, and gp will paste content from the clipboard to Neovim.

Side note: {'n', 'x'} is the list of vim modes where we want our keymap to be created. n is normal mode and x is visual mode.

The leader key

Usually we don't go around making keymaps that override the defaults like we did in the previous section. Most of the time we prefix our custom keymaps with the special string <leader>. This way we don't override an important feature or cause some sort of conflict.

But what's <leader>?

By default is the \ key. So, if we create a keymap like this:

vim.keymap.set('n', '<leader>h', '<cmd>echo "hello there"<cr>')

Then \ + h will print the message hello there.

But we can change that using the vim global variable mapleader.

vim.g.mapleader = ','

With this your leader key will change from \ to ,. But note that if you want to use a special sequence like Control + k you'll have to use its keycode.

vim.g.mapleader = vim.keycode('<C-k>')

Most people use the Space key as their leader key.

vim.g.mapleader = ' '

Yes, that's a string with a blank space. vim.keycode was added in Neovim v0.10, so before that people just did that thing with the blank space. So if you have it, then you can make it more explicit.

vim.g.mapleader = vim.keycode('<Space>')

Is important to note order matters, you must to define mapleader before you use <leader> in your keymaps.

Command shorcuts

Now let's make keymaps that can execute Ex-commands.

There are two ways of doing it, and this is my favorite:

<cmd>...<cr>

<cmd> is a special sequence that tells Neovim that you want to execute a vim expression. <cr> represents the enter key, it marks the end of the expression you want to execute.

Here are a couple of examples:

Save current file.

vim.keymap.set('n', '<leader>w', '<cmd>write<cr>', {desc = 'Save file'})

Close all files and exit Neovim.

vim.keymap.set('n', '<leader>q', '<cmd>quitall<cr>', {desc = 'Exit vim'})

Installing plugins

There is a new feature called vim.pack. This is a fully functional plugin manager built into Neovim. But only those who have access to Neovim v0.12 can use it. If you are one of the lucky ones you can learn more about it here: A guide to vim.pack.

Because I aim for backwards compatibility with Neovim v0.9.5 I will show you how to use mini.deps. Is worth noting vim.pack's design was based on mini.deps, so it should be fairly easy to migrate from one to the other.

Now the question is, how does one install a plugin without a plugin manager?

For this we are going to use Vim packages. Long story short, we can put plugins in a specific location in they should work.

Let's use Neovim in headless mode again, this time to create the directory were mini.deps should be.

nvim --headless -c 'call mkdir(stdpath("data") . "/site/pack/deps/start/", "p")' -c 'quit'

This other command will show the full path of the directory we just created.

nvim --headless -c 'echo stdpath("data") . "/site/pack/deps/start/"' -c 'quit'

Now navigate to that location using your terminal. You will want to execute the command git clone inside that directory.

Install mini.nvim

mini.deps is part of a project called mini.nvim, which is a collection of lua modules aimed to solve common problems and enhance some of Neovim builtin features. So we want to download mini.nvim using this command.

git clone --filter=blob:none https://github.com/nvim-mini/mini.nvim

If you are using Neovim v0.9 make sure to pin to the commit 3923662 since that's the last version that supports v0.9.

git switch --detach 3923662bf3d6ca49a9503f8d7196ea0450983e6a

After the install is complete we should generate the help tags.

nvim --headless -c 'helptags ALL' -c 'quit'

To use the plugin we must load the module mini.deps. But here we want to use in a way that is "safe." Because what if we copy our configuration to a new machine but we forget to download mini.nvim? If we do it the normal way we get hit by a scary wall of red text. We can make the experience less jarring by adding a few lines code.

local ok, MiniDeps = pcall(require, 'mini.deps')
if not ok then
  vim.notify('[WARN] mini.deps module not found', vim.log.levels.WARN)
  return
end

Here if something goes wrong Neovim will output a single line message then it will stop the execution of the script.

If everything goes according to plan every function of the mini.deps module will be inside the variable MiniDeps.

Is important to note all features of mini.nvim are opt-in, meaning we have to do something in our configuration to enable a module. For mini.deps we have to use a function called .setup(). So we add this after we load the module.

MiniDeps.setup({})

Install nvim-lspconfig

We will use this plugin to help us enable IDE-like features.

At this point we have mini.deps available so is easier to install a new plugin. This is the minimum amount of code we need.

MiniDeps.add('neovim/nvim-lspconfig')

The .add() function will make sure the plugin is installed and loaded. And is also the reason I recommend using mini.deps. In Neovim v0.12 we can add new plugins like this:

vim.pack.add({'https://github.com/neovim/nvim-lspconfig'})

There are some sutle differences between mini.deps and vim.pack but for the most part those two functions do the same thing.

The moment we need to add more information about the plugin we want to download we should replace the string with a lua table. For example, let's say we want to download a previous version of nvim-lspconfig. This is what we do.

MiniDeps.add({
  source = 'neovim/nvim-lspconfig',
  checkout = 'v1.8.0'
})

With vim.pack we do this:

vim.pack.add({
  {
    src = 'https://github.com/neovim/nvim-lspconfig',
    version = 'v1.8.0'
  },
})

Note that vim.pack.add() can install multiple plugins with a single function call. On the other hand MiniDeps.add() can only install one plugin at a time. So to install multiple plugins with mini.deps you execute MiniDeps.add() as many times as needed.

Now the first argument to MiniDeps.add() is a lua table with some properties. source would be the link to the plugin. In mini.deps github links get a special treatment because is very popular, so here we can just specify the github user and the name of the repository. checkout can be a commit hash, tag or branch name. In this case v1.8.0 is a tag on the nvim-lspconfig repository, it is the last version that supports Neovim v0.9.

To know more details about mini.deps read the official documentation: mini.nvim/doc/mini-deps.html.

File explorer

You should know that Neovim already has a file explorer, it's called netrw. We are not going to use it here because it has a few quirks I dislike. Still, I think you should know it exists.

Since we have mini.nvim available let's use the file explorer it provides: mini.files.

First, we call mini.files setup function.

require('mini.files').setup({})

This is a common convention of lua plugins. Sometimes you have to execute a function called .setup() to enable the plugin. Notice I said is a convention, it is not a rule. Some plugins execute their setup automatically.

How do we use mini.files?

We make a keymap to open the file explorer.

vim.keymap.set('n', '<leader>e', '<cmd>lua MiniFiles.open()<cr>', {desc = 'File explorer'})

After we open the file explorer press g then ?, this will show the keymaps available.

What if we want to change the settings in mini.files?

Any custom setting should be inside the {} of the setup function. Here's an example.

require('mini.files').setup({
  mappings = {
    show_help = 'gh',
  },
})

This will change the keymap that shows the help window. Instead of g? now is gh (get help).

These custom settings are in a "lua table." If there is piece of syntax that you should learn is that one. Knowing the correct syntax of a lua table will prevent so many headaches.

And how did I know those settings exists?

In Neovim's command-line I executed this command.

:help mini.files

That took me to the help page of mini.files.

Remember when we installed mini.nvim? We generated some called help tags. These tags allow you to navigate to the "offline" documentation of the plugin: the help page.

The tab complete feature of the :help command is really good too. You can type :help mini and then press the Tab key, Neovim will show you all the help tags that start with mini.

One more thing, if the font on your terminal doesn't support "icons" then you can add the mini.icons module. Set the style property to ascii.

require('mini.icons').setup({style = 'ascii'})

Navigating between files

For educational purposes only, I will tell you what I do when I don't have plugins installed: I use the files command to list the open files, then use the buffer command to navigate the file I want. And to make it convenient I make a keymap.

vim.keymap.set('n', '<leader><space>', '<cmd>files<cr>:buffer ', {desc = 'Search open files'})

In the :buffer command you can tab complete the name of the file or use the "id" of the buffer.

But why do that when we have mini.nvim installed? We can use the module mini.pick. This one provides a fancy interactive filter. And it also gives us commands we can use to search files.

If you use the module mini.extra you will have access to more search commands in mini.pick.

Anyway, enable mini.pick module.

require('mini.pick').setup({})

Then create keymaps to start the search between files.

vim.keymap.set('n', '<leader><space>', '<cmd>Pick buffers<cr>', {desc = 'Search open files'})
vim.keymap.set('n', '<leader>ff', '<cmd>Pick files<cr>', {desc = 'Search all files'})
vim.keymap.set('n', '<leader>fh', '<cmd>Pick help<cr>', {desc = 'Search help tags'})

Code completion

For this we will use mini.completion and mini.snippets.

require('mini.snippets').setup({})
require('mini.completion').setup({})

mini.completion is kind of a wrapper around Neovim's builtin completion mechanism. Neovim makes you press specific keybindings depending on the type of completion you want to get. And what mini.completion can do is take that burden away from you, by triggering the completion automatically as you type. In other words, it adds true autocompletion to Neovim.

By default you just get suggestions based on words of the current file. But whenever possible it'll try to use the LSP client to provide smart code completion.

To control the completion menu we use Neovim's default keybindings:

<Down>: Select the next item on the list.
<Up>: Select previous item on the list.
<Ctrl-n>: Select and insert text of the next item on the list.
<Ctrl-p>: Select and insert text of the previous item on the list.
<Ctrl-y>: Confirm selected item.
<Ctrl-e>: Cancel the completion.
<Enter>: If item was selected using <Up> or <Down> it confirms selection. If no item is selected, hides completion menu. Else, inserts a newline character.

Unfortunately, Neovim's builtin completion mechanism does not offer any support for snippets by default. That's why we have mini.snippets. But to be fair, newer versions of Neovim do have some support for snippets... but even with that, it still doesn't offer as many features as mini.snippets.

The LSP client

Neovim's LSP client is the thing that enables the nice IDE-like features. Things like go to definition, rename variable, inspect function signature. You get the idea. But this "client" doesn't work on its own, it needs a server. In this case a "server" is an external program that implements the LSP specification. If you want to know more details about LSP and language servers, watch this video by TJ DeVries: LSP explained (5 min).

What do we need to do here? We follow these 3 steps.

Install a language server
Configure that language server
Create some keymaps (optional)

Step 1: Install a language server

The Neovim community has created a resource where we can find a list of language servers. This list is in nvim-lspconfig documentation: configs.md.

Since I need some examples for the next step I'm going to show the install commands for the go language server and the rust language server.

If you have the toolchain for the go programming language you can download its language server (gopls) using this command.

go install golang.org/x/tools/gopls@latest

If you have rustup installed you can download rust_analyzer using this command.

rustup component add rust-analyzer

Step 2: Configure a language server

Now you have to "enable" each language server you have installed in your system.

On Neovim v0.11 you can use the function vim.lsp.enable().

vim.lsp.enable('example_server')

On Neovim v0.10 or lower you must use the "legacy setup" function of nvim-lspconfig.

require('lspconfig').example_server.setup({})

If you have the language server for go and rust you would do this.

vim.lsp.enable({'gopls', 'rust_analyzer'})

Or this.

require('lspconfig').gopls.setup({})
require('lspconfig').rust_analyzer.setup({})

If you want your config to be backwards compatible you can write a function that uses the correct method.

-- This function will use the "legacy setup" on older Neovim version.
-- The new api is only available on Neovim v0.11 or greater.
local function lsp_setup(server, opts)
  if vim.fn.has('nvim-0.11') == 0 then
    require('lspconfig')[server].setup(opts)
    return
  end

  if not vim.tbl_isempty(opts) then
    vim.lsp.config(server, opts)
  end

  vim.lsp.enable(server)
end

Then you can write the setup like this:

lsp_setup('gopls', {})
lsp_setup('rust_analyzer', {})

Do note there are a handful of language servers that can't be configured with vim.lsp.enable(). The list of missing servers is in this github issue: nvim-lspconfig/issues/3705.

Step 3: Create keymaps

After a language server is active in the current buffer we can use the functions under the module vim.lsp.buf. On Neovim v0.11 we have a handful of keymaps that trigger functions on this module. But on older versions we have to create the keymaps ourselves.

-- NOTE: These keymaps are already part of Neovim v0.11.
-- You do not have to add them to your personal configuration
-- if you are using Neovim v0.11 or greater.

-- Displays a function's signature information
vim.keymap.set('i', '<C-s>', '<cmd>lua vim.lsp.buf.signature_help()<cr>')

-- Lists all symbols in the current buffer
vim.keymap.set('n', 'gO', '<cmd>lua vim.lsp.buf.document_symbol()<cr>')

-- Lists all the implementations for the symbol under the cursor
vim.keymap.set('n', 'gri', '<cmd>lua vim.lsp.buf.implementation()<cr>')

-- Jumps to the definition of the type symbol
vim.keymap.set('n', 'grt', '<cmd>lua vim.lsp.buf.type_definition()<cr>')

-- Lists all the references
vim.keymap.set('n', 'grr', '<cmd>lua vim.lsp.buf.references()<cr>')

-- Renames all references to the symbol under the cursor
vim.keymap.set('n', 'grn', '<cmd>lua vim.lsp.buf.rename()<cr>')

-- Selects a code action available at the current cursor position
vim.keymap.set('n', 'gra', '<cmd>lua vim.lsp.buf.code_action()<cr>')

-- Show diagnostics in a floating window
vim.keymap.set('n', '<C-w>d', '<cmd>lua vim.diagnostic.open_float()<cr>')
vim.keymap.set('n', '<C-w><C-d>', '<cmd>lua vim.diagnostic.open_float()<cr>')

-- Jump next/previous diagnostic in the current buffer
vim.keymap.set('n', '[d', '<cmd>lua vim.diagnostic.goto_prev()<cr>')
vim.keymap.set('n', ']d', '<cmd>lua vim.diagnostic.goto_next()<cr>')

vim.api.nvim_create_autocmd('LspAttach', {
  callback = function(event)
    -- NOTE: By default `K` uses the program specified in 'keywordprg'
    -- Here we force it to use the LSP client

    -- Display documentation of the symbol under the cursor
    vim.keymap.set('n', 'K', '<cmd>lua vim.lsp.buf.hover()<cr>', {buffer = event.buf})
  end,
})

Keep in mind

Every language server is an independent project. A language server can have its own unique configuration method outside of Neovim. They can have bugs, limitations and quirks.

Some language servers were created for VS Code, the fact that Neovim and other editors can use them is just a happy accident. I believe the language servers for html and css fit in this category. They can have features that only work on VS Code. For example, Neovim can't enable the language server for css inside an html style tag (see issue 26783). That probably works fine in VS Code.

Honorable mention

nvim-treesitter is a plugin that has been around since 2020. A lot of people will say it's essential to your Neovim experience, and I do agree to some extend. It is incredibly useful... as a dependency for other plugins. It allows Neovim to gather more information about source code of the current file, and plugin authors can do really cool things with that. Treesitter became known in the community because it could be used to enhance the syntax highlight of many programming languages.

There are things you need to be aware of:

It needs a C compiler.
- Not a problem on linux or mac but it is a problem on windows.
It only supports the latest stable version of Neovim.
- It can drop the support for previous versions of Neovim really fast.
Is considered experimental.
- It can introduce breaking changes at any point in time.
- They do use git tags to track versions, in case you need a specific version.

To know more about tree-sitter watch this video: tree-sitter explained (15 min).

If you decide to try it, you can use the command :TSInstall to download a treesitter parser for the language you want, and then you can enable the enhanced syntax highlight using an autocommand.

For example, you can download the treesitter parser for javascript using this command.

:TSInstall javascript

And then create an autocommand that will call the function vim.treesitter.start() in any filetype that uses javascript syntax. Like this.

vim.api.nvim_create_autocmd('FileType', {
  pattern = {'javascript', 'javascriptreact', 'js', 'jsx'},
  callback = function()
    vim.treesitter.start()
  end,
})

init.lua

And this is it. This is all you need to get started if you are using Neovim v0.12. If you need backwards compatibility with Neovim v0.9, use this other configuration instead.

-- NOTE: This configuration is meant for Neovim v0.12 or greater

-- Learn about Neovim's lua api
-- https://neovim.io/doc/user/lua-guide.html

vim.o.number = true
vim.o.tabstop = 2
vim.o.shiftwidth = 2
vim.o.smartcase = true
vim.o.ignorecase = true
vim.o.wrap = false
vim.o.hlsearch = false
vim.o.signcolumn = 'yes'

-- Space as the leader key
vim.g.mapleader = vim.keycode('<Space>')

-- Basic clipboard interaction
vim.keymap.set({'n', 'x'}, 'gy', '"+y', {desc = 'Copy to clipboard'})
vim.keymap.set({'n', 'x'}, 'gp', '"+p', {desc = 'Paste clipboard text'})

-- Command shortcuts
vim.keymap.set('n', '<leader>w', '<cmd>write<cr>', {desc = 'Save file'})
vim.keymap.set('n', '<leader>q', '<cmd>quitall<cr>', {desc = 'Exit vim'})

vim.cmd.colorscheme('retrobox')

vim.pack.add({
  'https://github.com/neovim/nvim-lspconfig',
  'https://github.com/nvim-mini/mini.nvim',
})

require('mini.snippets').setup({})
require('mini.completion').setup({})

require('mini.files').setup({})
vim.keymap.set('n', '<leader>e', '<cmd>lua MiniFiles.open()<cr>', {desc = 'File explorer'})

require('mini.pick').setup({})
vim.keymap.set('n', '<leader><space>', '<cmd>Pick buffers<cr>', {desc = 'Search open files'})
vim.keymap.set('n', '<leader>ff', '<cmd>Pick files<cr>', {desc = 'Search all files'})
vim.keymap.set('n', '<leader>fh', '<cmd>Pick help<cr>', {desc = 'Search help tags'})

-- List of compatible language servers is here:
-- https://github.com/neovim/nvim-lspconfig/blob/master/doc/configs.md
vim.lsp.enable({'gopls', 'rust_analyzer'})

Backwards compatible config

For those of you that are using Ubuntu or Debian based operating systems, you have to be aware of the version available in the official repo of your system. In Ubuntu 24.04 you'll have v0.9.5. And any system based on Debian 13 will have v0.10.4 available.

You can still have a good experience using older versions of Neovim but the configuration will be a little bit more complex.

-- NOTE: This is meant to be backwards compatible with Neovim v0.9.5

-- Learn about Neovim's lua api
-- https://neovim.io/doc/user/lua-guide.html

vim.o.number = true
vim.o.tabstop = 2
vim.o.shiftwidth = 2
vim.o.smartcase = true
vim.o.ignorecase = true
vim.o.wrap = false
vim.o.hlsearch = false
vim.o.signcolumn = 'yes'

-- Space as the leader key
vim.g.mapleader = ' '

-- Basic clipboard interaction
vim.keymap.set({'n', 'x'}, 'gy', '"+y', {desc = 'Copy to clipboard'})
vim.keymap.set({'n', 'x'}, 'gp', '"+p', {desc = 'Paste clipboard text'})

-- Command shortcuts
vim.keymap.set('n', '<leader>w', '<cmd>write<cr>', {desc = 'Save file'})
vim.keymap.set('n', '<leader>q', '<cmd>quitall<cr>', {desc = 'Exit vim'})

local ok_theme = pcall(vim.cmd.colorscheme, 'retrobox')
if not ok_theme then
  vim.cmd.colorscheme('habamax')
end

local ok, MiniDeps = pcall(require, 'mini.deps')
if not ok then
  vim.notify('[WARN] mini.deps module not found', vim.log.levels.WARN)
  return
end

MiniDeps.setup({})

MiniDeps.add({
  source = 'nvim-mini/mini.nvim',
  checkout = '3923662bf3d6ca49a9503f8d7196ea0450983e6a',
})

MiniDeps.add({
  source = 'neovim/nvim-lspconfig',
  checkout = vim.fn.has('nvim-0.10') == 1 and 'v2.5.0' or 'v1.8.0'
})

require('mini.snippets').setup({})
require('mini.completion').setup({})

require('mini.files').setup({})
vim.keymap.set('n', '<leader>e', '<cmd>lua MiniFiles.open()<cr>', {desc = 'File explorer'})

require('mini.pick').setup({})
vim.keymap.set('n', '<leader><space>', '<cmd>Pick buffers<cr>', {desc = 'Search open files'})
vim.keymap.set('n', '<leader>ff', '<cmd>Pick files<cr>', {desc = 'Search all files'})
vim.keymap.set('n', '<leader>fh', '<cmd>Pick help<cr>', {desc = 'Search help tags'})

-- Displays a function's signature information
vim.keymap.set('i', '<C-s>', '<cmd>lua vim.lsp.buf.signature_help()<cr>')

-- Lists all symbols in the current buffer
vim.keymap.set('n', 'gO', '<cmd>lua vim.lsp.buf.document_symbol()<cr>')

-- Lists all the implementations for the symbol under the cursor
vim.keymap.set('n', 'gri', '<cmd>lua vim.lsp.buf.implementation()<cr>')

-- Jumps to the definition of the type symbol
vim.keymap.set('n', 'grt', '<cmd>lua vim.lsp.buf.type_definition()<cr>')

-- Lists all the references
vim.keymap.set('n', 'grr', '<cmd>lua vim.lsp.buf.references()<cr>')

-- Renames all references to the symbol under the cursor
vim.keymap.set('n', 'grn', '<cmd>lua vim.lsp.buf.rename()<cr>')

-- Selects a code action available at the current cursor position
vim.keymap.set('n', 'gra', '<cmd>lua vim.lsp.buf.code_action()<cr>')

-- Show diagnostics in a floating window
vim.keymap.set('n', '<C-w>d', '<cmd>lua vim.diagnostic.open_float()<cr>')
vim.keymap.set('n', '<C-w><C-d>', '<cmd>lua vim.diagnostic.open_float()<cr>')

if vim.fn.has('nvim-0.11') == 0 then
  -- Jump next/previous diagnostic in the current buffer
  vim.keymap.set('n', '[d', '<cmd>lua vim.diagnostic.goto_prev()<cr>')
  vim.keymap.set('n', ']d', '<cmd>lua vim.diagnostic.goto_next()<cr>')
end

vim.api.nvim_create_autocmd('LspAttach', {
  callback = function(event)
    -- NOTE: By default `K` uses the program specified in the 'keywordprg' option.
    -- Here we override the default behavior, we force it to use the LSP client

    -- Display documentation of the symbol under the cursor
    vim.keymap.set('n', 'K', '<cmd>lua vim.lsp.buf.hover()<cr>', {buffer = event.buf})
  end,
})

-- This function will use the "legacy setup" on older Neovim version.
-- The new api is only available on Neovim v0.11 or greater.
local function lsp_setup(server, opts)
  if vim.fn.has('nvim-0.11') == 0 then
    require('lspconfig')[server].setup(opts)
    return
  end

  if not vim.tbl_isempty(opts) then
    vim.lsp.config(server, opts)
  end

  vim.lsp.enable(server)
end

-- List of compatible language servers is here:
-- https://github.com/neovim/nvim-lspconfig/blob/master/doc/configs.md
lsp_setup('gopls', {})
lsp_setup('rust_analyzer', {})

Thank you for your time. If you find this article useful and want to support my efforts, consider leaving a tip in ko-fi.com/vonheikemen.

Neovim: Install plugins without a plugin manager

Heiker — Tue, 17 Sep 2024 17:22:05 +0000

Yes, and all we have to do is download them in the right path.

How does it work?

Neovim and vim have this feature called packages. A package is a directory that can contain multiple plugins.

The file structure of package can look like this:

some-package
├── colors
│   ├── a-colorscheme.vim
│   └── some-colorscheme.lua
├── doc
│   └── my-help-page.txt
├── lua
│   └── some-module
│       └── some-file.lua
└── plugin
    ├── a-file.vim
    └── some-file.lua

According to Neovim's documentation, a plugin is literally a script located in the plugin directory. They call it a "global plugin". So in our example, plugin/a-file.vim is one plugin and plugin/some-file.lua is another plugin.

Notice something interesting? This is the same file structure all Neovim plugins can have. So what we consider to be one plugin, Neovim's documentation calls it a package.

But where should we add these things?

The pack directory

Every directory in the packpath option can contain a directory called pack. Inside pack we can group our packages.

For example:

pack
└── vendor
    ├── opt
    │   └── package-one
    └── start
        ├── package-two
        └── package-three

vendor is just a random name I chose for this group. You can pick any name you want.

Within our group we can have opt packages and start packages.

Packages in the start directory will be available in the runtimepath during Neovim startup process.

A package in the opt directory will only be added to the runtimepath after we call the command :packadd. This is the way we can lazy load plugins.

The download path

First, inspect the value of the option packpath. Execute this command in Neovim.

:set packpath?

If you find that unreadable, you can try to print each path using lua. Execute this command.

:lua vim.tbl_map(print, vim.opt.packpath:get())

That's the list of directories where you can have a pack directory.

Example time:

By default Neovim's configuration directory is a part of the packpath, so that's a perfectly valid place to create a pack directory.

Let's pretend we are using linux and want to download mini.nvim. We could execute this command the terminal.

git clone https://github.com/nvim-mini/mini.nvim \
  ~/.config/nvim/pack/vendor/start/mini.nvim

Note that after we download a plugin we need to generate the help tags using this command inside Neovim.

:helptags ALL

After we create the help tags we can use the :help command to navigate to the documentation of the plugin.

Now that mini.nvim is available in Neovim's runtimepath we can test it. We can try for example the module mini.files in our Neovim configuration.

Let's create a keyboard shortcut to toggle mini.files explorer.

local mini_files = require('mini.files')

mini_files.setup({})

vim.keymap.set('n', '<F2>', function()
  if mini_files.close() then
    return
  end

  mini_files.open()
end)

A little command

If you want, you can have a Neovim command that uses git clone to download plugins from github.

This should work just fine:

vim.api.nvim_create_user_command(
  'GitPlugin',
  function(input)
    local repo = input.fargs
    local url = 'https://github.com/%s/%s.git'
    local plugin_dir = vim.fn.stdpath('config') 
      .. '/pack/vendor/start/%s'

    if repo[1] == nil or repo[2] == nil then
      local msg = 'Must provide user name and repository'
      vim.notify(msg, vim.log.levels.WARN)
      return
    end

    local full_url = url:format(repo[1], repo[2])
    local command = {'git', 'clone', full_url, plugin_dir:format(repo[2])}

    local on_done = function()
      vim.cmd('packloadall! | helptags ALL')
      vim.notify('Done.')
    end

    vim.notify('Cloning repository...')
    vim.fn.jobstart(command, {on_exit = on_done})
  end,
  {nargs = '+'}
)

Going back to our previous example, now we could download mini.nvim using this command inside Neovim:

GitPlugin nvim-mini mini.nvim

Conclusion

You are ready to enjoy Neovim plugins available on github without a plugin manager.

I want to clarify, I'm not saying plugin managers are useless. You probably still need one. Neovim doesn't have a mechanism to update plugins, or remove them. The package feature only loads plugins into Neovim's runtime. You still need to manage your plugins somehow.

Thank you for your time. If you find this article useful and want to support my efforts, consider leaving a tip in ko-fi.com/vonheikemen.

Neovim: creating keymaps in lua

Heiker — Sun, 10 Mar 2024 23:57:10 +0000

If you've read old tutorials about Neovim configuration you've find the way they create keymaps is a little bit different from what people do now. And if you check other people's configuration sometimes you'll find they create their keymaps using lazy.nvim. This is causing confusion among Neovim users.

Here I will explain why each method for creating keymaps exists and tell you when they are useful.

I will not explain in detail every option and possibility of each method. I just want to give you enough information to decide which one you should use in what situation.

nvim_set_keymap

This function was introduced in Neovim v0.5 and it's part of the Nvim API. This means nvim_set_keymap is accesible from lua, vimscript and also remote plugins.

For example, you could use nvim_set_keymap in command mode. This is a valid.

:call nvim_set_keymap('n', '<F2>', ':echo "hello"<cr>', {'noremap': v:true})

If you wanted to do the same in lua it'll be like this

vim.api.nvim_set_keymap('n', '<F2>', ':echo "hello"<cr>', {noremap = true})

And what about remote plugins. What's that? Those are plugins that communicate with external processes. They can be written in any programming language that can send messages through RPC.

In a python remote plugin using pynvim, you could write something like this.

vim.api.set_keymap('n', '<F2>', ':echo "hello"<cr>', {'noremap': True})

Note: I have never used pynvim. I just assume this is a valid method based on the documentation.

When to use it?

The only good reason to use nvim_set_keymap in your own personal configuration is if you can't upgrade to Neovim v0.7 or greater.

vim.keymap.set

This function was introduced in Neovim v0.7 and its part of the lua API. This means its only accesible in lua.

But why?

nvim_set_keymap exists and can be used in lua. What's the purpose of vim.keymap.set?

Short answer: to have better defaults.

Long answer: nvim_set_keymap behaves like the vimscript command :map. Now here's the thing, most people prefer the command :noremap. And there's another issue, you can't assign a lua function in the third argument. You have to use the options in the fourth argument.

If you want to use a lua function in nvim_set_keymap you end up with something like this.

vim.api.nvim_set_keymap(
  'n',
  '<F2>',
  '',
  {
    noremap = true,
    callback = function()
      print('hello')
    end,
  }
)

Almost every configuration I saw online had some sort wrapper around nvim_set_keymap to modify the defaults settings. And binding lua functions is very verbose. Because of details like these vim.keymap.set was created.

What's the difference?

vim.keymap.set is not recursive by default. You don't have to specify noremap = true.
Did you know noremap stands for "no recursive mapping"? Having that negative prefix is kind of confusing. So in vim.keymap.set if you want a recursive mapping you say remap = true.
You can use a lua function in the third argument.
Lua functions in combination with the option expr = true handles keycodes automatically.
vim.keymap.set can define buffer local keymaps.

So our previous example can be written like this.

vim.keymap.set('n', '<F2>', function()
  print('hello')
end)

When to use it?

Whenever possible. This is the recommended way of creating keymaps in your personal configuration.

lazy.nvim's "keys" property

And then there were three...

lazy.nvim offers a bunch of features. Among those there is one that allows users to create keymaps, that is the keys property in the plugin configuration.

Why?

One of the selling points of lazy.nvim is its ability to load plugins on demand using a (relatively) simple configuration. You can delay loading a plugin until you really, really need it.

Consider this example

{
  'nvim-telescope/telescope.nvim',
  branch = '0.1.x',
  dependencies = {'nvim-lua/plenary.nvim'},
  cmd = 'Telescope',
},

Here we have a configuration for telescope.nvim, a very popular fuzzy finder.

With this in your lazy.nvim setup it will install telescope.nvim and also plenary.nvim. But they will not be loaded until you use the command Telescope. If you never use that command Neovim is not going to execute any files in the source code of telescope.nvim.

Now, cmd is not the only way to load a plugin on demand. You can also tell lazy.nvim to do it when you press a keymap. Like this.

{
  'nvim-telescope/telescope.nvim',
  branch = '0.1.x',
  dependencies = {'nvim-lua/plenary.nvim'},
  keys = {
    {'<F2>', '<cmd>Telescope find_files<cr>'},
  },
},

In this example telescope.nvim will only be loaded after we press the <F2> key.

Consider the side effects

When a plugin is not loaded is like it doesn't even exists.

In the previous example we had a keys property. But notice it didn't have a cmd property. So if the plugin is not loaded and you try to execute the command :Telescope find_files manually in command mode, that would fail. If you try to use the command :help telescope.nvim to read the help page, that would also fail. That is because Neovim doesn't even know where telescope.nvim is installed. It can't give you access to anything.

Is worth mention some plugins do need to execute some commands or functions during Neovim's initialization process. So when you delay loading a plugin it may not work as expected.

When to use it?

I don't think there is ever a situation were you NEED to use this method. Is purely optional. You would use this when you want to delay loading a plugin.

I would use this feature of lazy.nvim in a plugin that I rarely need. Something like neogit for example. I can spend hours coding without using it. In that particular case I think is nice to have the option to load it when I actually call it.

Conclusion

I recommend using vim.keymap.set() whenever possible.

lazy.nvim's keys property does more than just create a keymap. It's one way the user can tell lazy.nvim to delay loading a plugin.

Thank you for your time. If you find this article useful and want to support my efforts, consider leaving a tip in ko-fi.com/vonheikemen.

Guía de uso del cliente LSP de Neovim

Heiker — Sat, 20 Jan 2024 15:51:11 +0000

El título original para este post era "Cómo agregar funcionalidades como las de un IDE a Neovim sin instalar plugins de terceros." Suena más interesante pero tiene demasiadas palabras. Aún así, es básicamente lo que quiero enseñarles.

En esta ocasión quiero explicar cómo configurar un servidor LSP en Neovim v0.11. Y voy a mostrarles cómo funciona porque este nuevo método es simplemente una abstracción sobre funcionalidades que han estado en Neovim durante mucho tiempo. Así podrán construir su propia configuración incluso en versiones anteriores de Neovim.

Requerimientos

Neovim en su versión v0.8 o mayor
Un servidor LSP
Paciencia/Energía para escribir un poco de lua por cada servidor LSP que se quiere configurar

Si no conocen el lenguaje lua aquí les dejo un par de recursos donde pueden aprender lo básico:

Todo comienza con el servidor LSP

Un servidor LSP es un programa externo que sigue el Protocolo de Servidor de Lenguajes (Language Server Protocol). En este se definen los parámetros que puede recibir un servidor LSP, y también cómo debe responder. El propósito de todo esto es que cualquier herramienta que implemente el protocolo pueda comunicarse con un servidor LSP.

Entonces, el servidor LSP es el programa que va a analizar nuestro código y le dice a nuestro editor qué debe hacer.

¿Qué servidores LSP tenemos disponibles?

La página web del protocolo tiene una lista de servidores.

En este caso en particular...

Quiero usar Gleam y LuaLS como ejemplos prácticos.

Gleam en realidad es un conjunto de herramientas. Incluye un compilador, un formateador de código y un servidor LSP. Las instrucciones de instalación se encuentran en la documentación oficial: Getting started.

LuaLS es un servidor LSP para el lenguaje lua. Pueden descargar la versión más reciente desde su repositorio, en la sección github releases. O, pueden compilarlo con el código fuente.

Una vez que tienen un servidor LSP instalado recomiendo verificar si Neovim puede encontrar el ejecutable. Para esto pueden usar la función exepath.

El ejecutable de Gleam es gleam.

:echo exepath('gleam')

Y el de LuaLS es lua-language-server.

:echo exepath('lua-language-server')

Estos comandos deben mostrar la ubicación del ejecutable en su sistema. De no ser así, significa que algo salió mal durante la instalación del servidor LSP.

Uso básico

Antes de empezar a escribir código deberíamos aprender cómo usar el servidor LSP. Esta información debería estar en la documentación oficial del servidor que queremos usar.

Si no podemos encontrar instrucciones de uso básico en la documentación, podemos ir al repositorio de nvim-lspconfig y buscamos el directorio lsp. Ahí podemos encontrar archivos de configuración para un montón de servidores.

Justo ahora estamos interesados en Gleam, entonces deberíamos revisar el contenido de gleam.lua.

return {
    cmd = { 'gleam', 'lsp' },
    filetypes = { 'gleam' },
    root_markers = { 'gleam.toml', '.git' },
}

Aquí tenemos la información esencial que necesitamos para poder integrar un servidor LSP en Neovim.

La propiedad cmd contiene el comando que necesitamos para inicializar el servidor LSP. Recuerden que un servidor LSP es un programa externo. Quiere decir que gleam lsp es un comando válido que podemos ejecutar manualmente en nuestra terminal. Y curiosamente, si hacemos eso nos mostrará este mensaje.

This command is intended to be run by language server clients such
as a text editor rather than being run directly in the console.

El mensaje dice "este comando fue creado para ser ejecutado por un cliente LSP como por ejemplo un editor de texto, en lugar de ser ejecutado directamente por cónsola."

En la propiedad filetypes tenemos la lista de lenguajes que el servidor LSP soporta. Deben tener en cuenta que cada nombre debe ser un "filetype" válido en Neovim.

En root_markers tenemos una lista de archivos y directorios. Esta información se usa para determinar la "raíz" de nuestro proyecto. Es decir el directorio principal del proyecto.

El directorio lsp

A partir de la versión v0.11 el directorio lsp forma parte de lo que llamamos runtimepath. Quiere decir que tenemos la posibilidad de crear nuestro propio directorio lsp. Ahí podemos colocar la configuración de los servidores LSP que tenemos instalados, sin necesidad de instalar nvim-lspconfig como un plugin.

Imaginen por un momento que nuestra configuración personal de Neovim tiene esta estructura:

nvim
├── init.vim
├── .nvim.lua
└── lsp
    ├── gleam.lua
    └── luals-nvim.lua

La configuración dentro de nvim/lsp/gleam.lua puede ser exactamente igual a la que tiene nvim-lspconfig.

-- nvim/lsp/gleam.lua

return {
  cmd = {'gleam', 'lsp'},
  filetypes = {'gleam'},
  root_markers = {'gleam.toml', '.git'},
}

Ahora bien, cuando configuramos un servidor LSP tenemos ciertas libertades. Entonces, en luals-nvim voy a mostrar una configuración de LuaLS específicamente creada para Neovim donde hay un script llamado .nvim.lua en el directorio raíz.

-- nvim/lsp/luals-nvim.lua

return {
  cmd = {'lua-language-server'},
  filetypes = {'lua'},
  root_markers = {'.nvim.lua'},
  settings = {
    Lua = {
      runtime = {
        version = 'LuaJIT',
        path = {'lua/?.lua', 'lua/?/init.lua'},
      },
      diagnostics = {
        globals = {'vim'},
      },
      telemetry = {
        enable = false,
      },
      workspace = {
        checkThirdParty = false,
        library = {
          vim.env.VIMRUNTIME,
        },
      },
    },
  },
}

Dentro del directorio lsp los archivos que creamos pueden tener cualquier nombre. Por eso elegí luals-nvim en lugar de algo genérico como lua o luals. Y la configuración que "retornamos" en el script debe contener los mismos parámetros que vim.lsp.config() espera.

Noten que en este ejemplo tenemos una propiedad llamada settings. Esa propiedad está reservada para opciones específicas del servidor LSP. Quiere decir que en Neovim no disponemos de una documentación que nos diga cuáles son las opciones que podemos colocar. Debemos ir a la documentación del servidor LSP y ver qué opciones tenemos disponibles.

Deben saber que los archivos dentro del directorio lsp no son ejecutados automáticamente. Debemos decirle a Neovim qué servidores LSP queremos usar. Para usar un servidor LSP debemos ejecutar la función vim.lsp.enable().

En este ejemplo el archivo init.vim puede tener este código:

" nvim/init.vim

set exrc

lua vim.lsp.enable('gleam')

¿Por qué usar init.vim?

Simplemente quería una excusa para mostrar que se puede ejecutar una función de lua en vimscript. He notado que algunos usuarios de Vim creen que para usar lua deben eliminar toda la configuración que tienen en vimscript. No es así. Lua y vimscript pueden coexistir.

En fin, al iniciar Neovim este buscará un archivo en el runtimepath que coincida con el patrón lsp/gleam.lua. Luego creará un autocomando usando la lista de lenguajes que suministramos en filetypes. Entonces si abrimos un archivo de tipo gleam Neovim intentará inicializar el servidor LSP.

¿Y qué pasa con LuaLS?

La configuración que tenemos para LuaLS sólo es útil para Neovim, lo que nos da una oportunidad para usar una configuración local. En Vim logramos esto usando la opción exrc. Cuando habilitamos los archivos exrc Vim/Neovim ejecutará un script que esté en directorio de trabajo actual. En nuestro ejemplo sería .nvim.lua. Esto es una espada de doble filo. Por eso en Neovim la opción exrc tiene un comportamiento diferente. Cuando se detecta una configuración local Neovim nos preguntará si "confiamos" en el archivo, y si aceptamos se ejecutará. La próxima vez que se detecte la misma configuración local se ejecutará automáticamente si el contenido del archivo no ha cambiado.

Yo recomendaría crear un alias para habilitar la opción exrc desde la terminal, en lugar de colocarlo directo en su configuración personal. Algo como esto.

alias code='nvim --cmd "set exrc"'

De vuelta a LuaLS. Luego de Neovim termine de ejecutar el archivo init.vim (o init.lua) buscará el script .nvim.lua en el directorio actual. El que está en nuestra configuración tendrá este código.

-- nvim/.nvim.lua

vim.lsp.enable('luals-nvim')

De esta manera Neovim no intentará usar lsp/luals-nvim.lua si no lo abrimos en el directorio donde está nuestra configuración personal. La desventaja de este método es que debemos abrir Neovim exactamente donde está .nvim.lua.

¿Se puede configurar todo en un archivo?

Si ustedes son la clase de persona que prefiere una configuración simple donde todo está en un sólo archivo, les tengo buenas noticias. No están obligados a usar el directorio lsp.

La función vim.lsp.config() puede usarse para extender las configuraciones que se encuentran en el directorio lsp. Pero también la podemos usar para crear configuraciones nuevas, sin necesidad de crear un archivo aparte.

Por ejemplo:

-- nvim/init.lua

vim.lsp.config('gleam', {
  cmd = {'gleam', 'lsp'},
  filetypes = {'gleam'},
  root_markers = {'gleam.toml', '.git'},
})

vim.lsp.enable('gleam')

¿Y si algo sale mal?

Si Neovim no fue capaz de iniciar el proceso del servidor LSP pueden revisar el log. Ejecuten este comando en Neovim:

:lua vim.cmd.edit(vim.lsp.get_log_path())

Cuando algo sale mal habrá unas líneas que comienzan con [ERROR]. Tal vez ahí pueden encontrar alguna información útil.

Si quieren un log con más detalles pueden ejecutar esta función.

vim.lsp.set_log_level('debug')

Y desde Neovim v0.10 pueden hacer un "chequeo de salud" usando este comando:

:checkhealth lsp

Filetypes

En versiones anteriores de Neovim no tenemos disponible vim.lsp.enable(), pero podemos replicar su funcionalidad. Ya sabemos lo que necesitamos sólo nos falta juntar las piezas.

Si el servidor LSP que queremos usar sólo soporta un lenguaje de programación entonces podemos crear un "filetype plugin."

Para crear un filetype plugin debemos ir a nuestra configuración de Neovim, y ahí debemos crear un directorio llamado ftplugin. Podemos ejecutar este comando en Neovim.

:call mkdir('./ftplugin', 'p')

Luego debemos crear un script con el mismo nombre de un tipo de archivo.

Si queremos crear un filetype plugin para Gleam debemos crear un archivo llamado gleam.lua.

:edit ftplugin/gleam.lua | write

En este script vamos a ejecutar la función que "conectará" el servidor LSP con Neovim.

Por otro lado, si el servidor LSP soporta varios tipos de archivos tenemos la opción de crear un autocomando en el evento FileType. Algo como esto.

vim.api.nvim_create_autocmd('FileType', {
  pattern = {'css', 'less', 'sass'},
  callback = function()
    ---
    -- Aquí podemos habilitar el servidor LSP
    ---
  end,
})

Aquí la propiedad pattern es donde debemos colocar los tipos de archivos que soporta el servidor LSP. Esta es la misma información que colocamos en la propiedad filetypes cuando configuramos un servidor LSP en Neovim v0.11.

Dentro del filetype plugin o el autocomando debemos ejecutar la función que va a inicializar el servidor LSP. Pero primero, debemos conocer la lógica detrás de root_markers.

Directorio raíz

Un servidor LSP necesita saber la ruta de nuestro proyecto. La ubicación exacta dentro de nuestro sistema. Este es un problema que debemos resolver en Neovim.

En Neovim v0.10 podemos usar una función llamada vim.fs.root(). A esta función le vamos a dar una lista de nombres de archivos y nos devolverá una ruta que podemos usar.

¿Pero qué vamos a buscar? Archivos de configuración, los que usualmente colocamos en la raíz de un proyecto. En proyectos de Gleam siempre hay un archivo gleam.toml. En proyectos de javascript usualmente hay un package.json. En rust está el cargo.toml. Este es el tipo de información que vamos a darle a vim.fs.root() para que nos devuelva la ruta correcta.

Entonces en el filetype plugin de Gleam podemos hacer una prueba con vim.fs.root().

-- nvim/ftplugin/gleam.lua
-- NOTA: vim.fs.root() sólo está disponble en Neovim v0.10 o mayor

local root_markers = {'gleam.toml'}
local root_dir = vim.fs.root(0, root_markers)

print(root_dir)

En Neovim v0.9 o menor debemos recrear el comportamiento de vim.fs.root(). En este caso podemos usar vim.fs.find().

-- nvim/ftplugin/gleam.lua
-- NOTA: Este código es para Neovim v0.9.5 o menor

local root_markers = {'gleam.toml'}
local buffer = vim.api.nvim_buf_get_name(0)
local paths = vim.fs.find(root_markers, {
    upward = true,
    path = vim.fn.fnamemodify(buffer, ':p:h'),
})

local root_dir = vim.fs.dirname(paths[1])

print(root_dir)

Creando el cliente

Estamos listos para conectar Neovim con el servidor LSP. Ahora debemos usar la función vim.lsp.start() para inicializar el servidor LSP. Esta es la misma función que vim.lsp.enable() ejecuta por nosotros.

Esto es lo que deben saber, la primera vez que ejecutamos vim.lsp.start() Neovim iniciará nuestro servidor LSP como un proceso externo. Cuando se ejecuta nuevamente Neovim simplemente le enviará información al proceso del servidor LSP.

Entonces, el filetype plugin para Gleam debería tener este código:

-- nvim/ftplugin/gleam.lua
-- NOTA: vim.fs.root() sólo está disponble en Neovim v0.10 o mayor

local root_markers = {'gleam.toml'}
local root_dir = vim.fs.root(0, root_markers)

if root_dir then
  vim.lsp.start({
    cmd = {'gleam', 'lsp'},
    root_dir = root_dir,
  })
end

Con esta configuración ya podremos utilizar algunas funcionalidades. Por ejemplo, si editamos un archivo Gleam y este tiene un error, Neovim nos dirá en qué línea se encuentra el error.

Diagnostics

"Diagnostic" es el término que se usa en Neovim para los errores que se encuentran en nuestro código fuente.

Un diagnóstico puede tener un signo al inicio de la línea para indicarnos que hay un error. Este es el diagnostic sign. El espacio que necesita este signo está escondido por defecto, y cuando Neovim va a mostrarlo toda la pantalla se mueve a la derecha. Este comportamiento puede configurarse.

Si configuramos la opción signcolumn con la cadena de texto yes Neovim reserva el espacio para el signo. Tendremos un espacio en blanco al inicio de la línea en todo momento.

En init.vim pueden configurarlo de esta manera.

set signcolumn=yes

Si usan init.lua.

vim.o.signcolumn = 'yes'

Por otro lado si asignamos la cadena de texto no, Neovim no mostrará ningún signo. No recomiendo esta opción, especialmente si no están al tanto de las consecuencias. Si quieren esconder los signos de diagnósticos hay una alternativa mejor.

vim.diagnostic

En lua tenemos acceso al módulo vim.diagnostic, y dentro de este módulo está una función llamada .config(). Si con esta función podremos configurar el comportamiento de los diagnósticos.

Esconder los signos

Esta es la forma segura de deshabilitar los signos de los diagnósticos.

vim.diagnostic.config({
  signs = false,
})

Texto virtual

Tenemos la opción de mostrar un fragmento del mensaje de error al final de la línea. A esto se le conoce como "virtual text." En Neovim v0.11 está deshabilitado por defecto. Así lo podemos habilitar.

vim.diagnostic.config({
  virtual_text = false,
})

Si tienen Neovim v0.10 o mayor pueden leer el diagnóstico completo usando <C-w>d (control + w luego d). Este atajo ejecuta la función vim.diagnostic.open_float().

Si están usando Neovim v0.9.5 o menor tendrán que crear un atajo de teclado.

vim.keymap.set('n', '<C-w>d', '<cmd>lua vim.diagnostic.open_float()<cr>')

Ahora bien, me gustaría poder explicarles con más detalle cada opción en vim.diagnostic.config() pero no tenemos tiempo. Si quieren explorar las demás opciones pueden leer la documentación.

Funcionalidades gratis

Hablemos de las funcionalidades que Neovim nos ofrece con la configuración que tenemos hasta ahora, que es básicamente lo mínimo.

Cuando un servidor LSP está activo en un archivo Neovim habilita ciertas funcionalidades.

Desde Neovim v0.8

A la opción tagfunc se le asigna una función que usa el servidor LSP activo. En otras palabras, podemos saltar a la definición de una función o clase usando el atajo <C-]> (Control + ]). Y podemos volver a la posición anterior usando <C-t> (Control + t).
La opción formatexpr se le asigna una función que usa el servidor LSP activo. Esto quiere decir que podemos usar el operador gq para formatear un fragmento de código. Ejemplo: podemos ir al modo visual, seleccionamos un pedazo de código, presionamos gq y Neovim le pedirá al servidor LSP activo que formatee el código.
La opción omnifunc también es configurada. Esta nos permite obtener completado de código. En modo de inserción el atajo <C-x><C-o> (control + x y luego control + o) nos presentará sugerencias que el servidor LSP cree que son relevantes.

Desde Neovim v0.9

Se agrega soporte para el "resaltado semántico." Resulta que algunos servidores proporcionan información acerca de los símbolos que se encuentran en el archivo actual, y Neovim puede usar esta información para crear un resaltado de código más preciso.

Desde Neovim v0.10

Si estamos en modo normal y no tenemos ningún atajo vinculado a K, podremos usarlo para leer la documentación del símbolo que está debajo del cursor.
En modo normal, el atajo <C-w>d muestra los diagnósticos de la línea debajo del cursor.
En modo normal, el atajo ]d mueve el cursor hacia siguiente diagnóstico más cercano.
En modo normal, el atajo [d mueve el cursor hacia diagnóstico previo.

Desde Neovim v0.11

En modo normal, el atajo grn renombra todas las referencias del símbolo debajo del cursor.
En modo normal, el atajo gra muestra una lista de "code actions" disponibles para la línea actual.
En modo normal, el atajo grr muestra todas las referencias del símbolo debajo del cursor.
En modo normal, el atajo gri muestra la implementación del símbolo debajo del cursor.
En modo normal, el atajo gO muestra lista todos los símbolos que existen en el archivo actual.
En modo de inserción, el atajo <Ctrl-s> (Control + s) muestra documentación de los argumentos de la función debajo del cursor.

Atajos

En Neovim v0.11 ya tenemos atajos asignados para las funcionalidades que ofrece el editor. Pero en versiones anteriores debemos crear estos atajos nosotros mismos.

Este es el código que necesitamos en lua.

-- Pueden agregar esto en su archivo `init.lua`

-- Estos atajos ya forman parte de Neovim v0.10
vim.keymap.set('n', '[d', '<cmd>lua vim.diagnostic.goto_prev()<cr>')
vim.keymap.set('n', ']d', '<cmd>lua vim.diagnostic.goto_next()<cr>')
vim.keymap.set('n', '<C-w>d', '<cmd>lua vim.diagnostic.open_float()<cr>')
vim.keymap.set('n', '<C-w><C-d>', '<cmd>lua vim.diagnostic.open_float()<cr>')

vim.api.nvim_create_autocmd('LspAttach', {
  callback = function(event)
    local bufmap = function(mode, rhs, lhs)
      vim.keymap.set(mode, rhs, lhs, {buffer = event.buf})
    end

    -- Estos atajos ya forman parte de Neovim v0.11
    bufmap('n', 'K', '<cmd>lua vim.lsp.buf.hover()<cr>')
    bufmap('n', 'grr', '<cmd>lua vim.lsp.buf.references()<cr>')
    bufmap('n', 'gri', '<cmd>lua vim.lsp.buf.implementation()<cr>')
    bufmap('n', 'grn', '<cmd>lua vim.lsp.buf.rename()<cr>')
    bufmap('n', 'gra', '<cmd>lua vim.lsp.buf.code_action()<cr>')
    bufmap('n', 'gO', '<cmd>lua vim.lsp.buf.document_symbol()<cr>')
    bufmap({'i', 's'}, '<C-s>', '<cmd>lua vim.lsp.buf.signature_help()<cr>')

    -- Estos son atajos extras
    bufmap('n', 'gd', '<cmd>lua vim.lsp.buf.definition()<cr>')
    bufmap('n', 'grt', '<cmd>lua vim.lsp.buf.type_definition()<cr>')
    bufmap('n', 'grd', '<cmd>lua vim.lsp.buf.declaration()<cr>')
    bufmap({'n', 'x'}, 'gq', '<cmd>lua vim.lsp.buf.format({async = true})<cr>')
  end,
})

Y este sería el equivalente en vimscript.

" Pueden agregar esto en su archivo `init.vim`

" Estos atajos ya forman parte de Neovim v0.10
nnoremap [d <cmd>lua vim.diagnostic.goto_prev()<cr>
nnoremap ]d <cmd>lua vim.diagnostic.goto_next()<cr>
nnoremap <C-w>d <cmd>lua vim.diagnostic.open_float()<cr>
nnoremap <C-w><C-d> <cmd>lua vim.diagnostic.open_float()<cr>

function! LspAttached() abort
  " Estos atajos ya forman parte de Neovim v0.11
  nnoremap <buffer> K <cmd>lua vim.lsp.buf.hover()<cr>
  nnoremap <buffer> grr <cmd>lua vim.lsp.buf.references()<cr>
  nnoremap <buffer> gri <cmd>lua vim.lsp.buf.implementation()<cr>
  nnoremap <buffer> grn <cmd>lua vim.lsp.buf.rename()<cr>
  nnoremap <buffer> gra <cmd>lua vim.lsp.buf.code_action()<cr>
  nnoremap <buffer> gO <cmd>lua vim.lsp.buf.document_symbol()<cr>
  inoremap <buffer> <C-s> <cmd>lua vim.lsp.buf.signature_help()<cr>
  snoremap <buffer> <C-s> <cmd>lua vim.lsp.buf.signature_help()<cr>

  " Estos son atajos extras
  nnoremap <buffer> gd <cmd>lua vim.lsp.buf.definition()<cr>
  nnoremap <buffer> gq <cmd>lua vim.lsp.buf.format({async = true})<cr>
  xnoremap <buffer> gq <cmd>lua vim.lsp.buf.format({async = true})<cr>
  nnoremap <buffer> grd <cmd>lua vim.lsp.buf.declaration()<cr>
  nnoremap <buffer> grt <cmd>lua vim.lsp.buf.type_definition()<cr>
endfunction

autocmd LspAttach * call LspAttached()

Advertencia

No todos los servidores implementan el protocolo LSP en su totalidad. Y no todas las funcionalidades son consistentes entre servidores.

Por ejemplo, Gleam puede mostrar errores en nuestro código en tiempo real, sin necesidad de guardar los cambios en el archivo. Pero rust-analyzer, el servidor LSP para rust, sólo puede mostrar errores una vez que se guardan cambios en el archivo.

Otro ejemplo. ruff-lsp, un servidor LSP para python, en su descripción menciona que su especialidad es reportar errores y formatear código. Hasta donde pude ver este servidor no ofrece completado de código o resaltado de código semántico.

Lo que intento decir es esto: lean la documentación del servidor LSP para que estén informados de las funcionalidades que ofrece.

Contenido extra

A estas alturas me atrevería a decir que ya tienen el conocimento esencial para usar el cliente LSP de Neovim y ser productivos. Lo que sigue son consejos, ajustes y funcionalidades que pueden implementar agregando un bloque de código a su configuración personal.

Formatear al guardar

Lo que haremos aquí es ejecutar la función vim.lsp.buf.format() antes de que Neovim guarde los cambios a un archivo. Y por supuesto, esto sólo lo haremos cuando hay un servidor LSP activo.

Importante: los servidores LSP con capacidades para formatear código tienen su propia configuración. Por ejemplo, puede que nosotros tengamos la indentación configurada a 2 espacios pero el servidor LSP puede formatear el código con 4 espacios. Entonces, siempre es buena idea indagar en la documentación del servidor LSP para saber cómo configurar el estilo del formateo.

-- Pueden agregar esto en su archivo `init.lua`

local fmt_group = vim.api.nvim_create_augroup('autoformat_cmds', {clear = true})

local function setup_autoformat(event)
  local id = vim.tbl_get(event, 'data', 'client_id')
  local client = id and vim.lsp.get_client_by_id(id)
  if client == nil then
    return
  end

  vim.api.nvim_clear_autocmds({group = fmt_group, buffer = event.buf})

  local buf_format = function(e)
    vim.lsp.buf.format({
      bufnr = e.buf,
      async = false,
      timeout_ms = 10000,
    })
  end

  vim.api.nvim_create_autocmd('BufWritePre', {
    buffer = event.buf,
    group = fmt_group,
    desc = 'Formatear archivo',
    callback = buf_format,
  })
end

vim.api.nvim_create_autocmd('LspAttach', {
  desc = 'Configurar formatear al guardar',
  callback = setup_autoformat,
})

Cambiar texto de signos de diagnósticos

Si estamos usando Neovim en su versión v0.9.5 o menor, debemos usar la función vim.fn.sign_define().

-- Pueden agregar esto en su archivo `init.lua`

local function sign_define(args)
  vim.fn.sign_define(args.name, {
    texthl = args.name,
    text = args.text,
    numhl = ''
  })
end

sign_define({name = 'DiagnosticSignError', text = '✘'})
sign_define({name = 'DiagnosticSignWarn', text = '▲'})
sign_define({name = 'DiagnosticSignHint', text = '⚑'})
sign_define({name = 'DiagnosticSignInfo', text = '»'})

Si estamos usando Neovim en su versión v0.10 o mayor, debemos usar la función vim.diagnostic.config().

-- Pueden agregar esto en su archivo `init.lua`

vim.diagnostic.config({
  signs = {
    text = {
      [vim.diagnostic.severity.ERROR] = '✘',
      [vim.diagnostic.severity.WARN] = '▲',
      [vim.diagnostic.severity.HINT] = '⚑',
      [vim.diagnostic.severity.INFO] = '»',
    },
  },
})

Deshabilitar resaltado semántico

La documentación de Neovim sugiere modificar la instancia del cliente LSP. Debemos "eliminar" la propiedad que activa el resaltado semántico.

-- Pueden agregar esto en su archivo `init.lua`

vim.api.nvim_create_autocmd('LspAttach', {
  desc = 'Deshabilitar resaltado semántico',
  callback = function(event)
    local id = vim.tbl_get(event, 'data', 'client_id')
    local client = id and vim.lsp.get_client_by_id(id)
    if client == nil then
      return
    end

    client.server_capabilities.semanticTokensProvider = nil
  end,
})

Resaltar símbolo debajo del cursor

Para esto vamos a usar la función vim.lsp.buf.document_highlight(). Cuando el cursor pase una cantidad de tiempo sobre un símbolo vamos a ejecutar esa función. Y luego vamos desactivar el resaltado cuando el cursor se mueva de lugar.

Para que esto funcione de manera apropiada el tema del editor debe soportar los siguientes grupos:

LspReferenceRead
LspReferenceText
LspReferenceWrite

Si el tema que tenemos no define ningún color para esos grupos podemos hacer un "vinculo" con un grupo que ya existe. Este es un ejemplo que muestra cómo vincular al grupo Search.

vim.api.nvim_set_hl(0, 'LspReferenceRead', {link = 'Search'})
vim.api.nvim_set_hl(0, 'LspReferenceText', {link = 'Search'})
vim.api.nvim_set_hl(0, 'LspReferenceWrite', {link = 'Search'})

-- Pueden agregar esto en su archivo `init.lua`

-- tiempo en milisegundos para emitir el event `CursorHold`
vim.opt.updatetime = 400

local function highlight_symbol(event)
  local id = vim.tbl_get(event, 'data', 'client_id')
  local client = id and vim.lsp.get_client_by_id(id)
  if client == nil or not client.supports_method('textDocument/documentHighlight') then
    return
  end

  local group = vim.api.nvim_create_augroup('highlight_symbol', {clear = false})

  vim.api.nvim_clear_autocmds({buffer = event.buf, group = group})

  vim.api.nvim_create_autocmd({'CursorHold', 'CursorHoldI'}, {
    group = group,
    buffer = event.buf,
    callback = vim.lsp.buf.document_highlight,
  })

  vim.api.nvim_create_autocmd({'CursorMoved', 'CursorMovedI'}, {
    group = group,
    buffer = event.buf,
    callback = vim.lsp.buf.clear_references,
  })
end

vim.api.nvim_create_autocmd('LspAttach', {
  desc = 'Resaltar símbolo debajo del cursor',
  callback = highlight_symbol,
})

Tab para completar

Para mantener una implementación simple vamos a hacer lo siguiente: Si el menú de sugerencias es visible, usaremos Tab y Shift + Tab para navegar entre las sugerencias. Si el cursor está sobre un espacio en blanco, insertaremos el caracter <Tab>. Si no, mostraremos el menú de sugerencias.

Ahora bien, si tenemos un servidor LSP activo que puede proveer sugerencias usamos eso. De lo contrario le pediremos a Neovim que sugiera palabras que se encuentran en el archivo actual.

Nota: recuerden que pueden confirmar una sugerencia usando Enter o <C-y> (Control + y).

-- Pueden agregar esto en su archivo `init.lua`

vim.opt.completeopt = {'menu', 'menuone', 'noselect', 'noinsert'}
vim.opt.shortmess:append('c')

local function tab_complete()
  if vim.fn.pumvisible() == 1 then
    -- navega al siguiente elemento en la lista
    return '<Down>'
  end

  local c = vim.fn.col('.') - 1
  local is_whitespace = c == 0 or vim.fn.getline('.'):sub(c, c):match('%s')

  if is_whitespace then
    -- inserta el caracter tab
    return '<Tab>'
  end

  local lsp_completion = vim.bo.omnifunc == 'v:lua.vim.lsp.omnifunc'

  if lsp_completion then
    -- activa el completado con el servidor LSP
    return '<C-x><C-o>'
  end

  -- sugiere palabras en el archivo actual
  return '<C-x><C-n>'
end

local function tab_prev()
  if vim.fn.pumvisible() == 1 then
    -- navega al elemento anterior en la lista
    return '<Up>'
  end

  -- inserta el caracter tab
  return '<Tab>'
end

vim.keymap.set('i', '<Tab>', tab_complete, {expr = true})
vim.keymap.set('i', '<S-Tab>', tab_prev, {expr = true})

Expandir snippets

En Neovim v0.11 tenemos acceso a un módulo llamado vim.lsp.completion, con esto podremos extender las funcionalidades del mecanismo de completado de código. Para ser más específico, Neovim podrá responder a más "comandos de edición" que retorne un servidor LSP. Por ejemplo, podremos expandir snippets de código.

Por el momento las funcionalidades de vim.lsp.completion son opcionales, debemos usar la función vim.lsp.completion.enable() para habilitarlas.

-- Pueden agregar esto en su archivo `init.lua`

vim.opt.completeopt = {'menu', 'menuone', 'noinsert', 'noselect'}

vim.api.nvim_create_autocmd('LspAttach', {
  desc = 'Habilitar vim.lsp.completion',
  callback = function(event)
    local client_id = vim.tbl_get(event, 'data', 'client_id')
    if client_id == nil then
      return
    end

    vim.lsp.completion.enable(true, client_id, event.buf, {autotrigger = false})

    -- Activar el menú de sugerencias manualmente
    vim.keymap.set('i', '<C-Space>', '<cmd>lua vim.lsp.completion.trigger()<cr>')
  end
})

Noten que el último argumento en .enable() tiene la propiedad autotrigger. false es el valor por defecto entonces yo lo dejo así. Si cambian ese valor a true Neovim podrá activar el completado de código cuando encuentre un "trigger character". Por ejemplo, con el servidor LSP de lua Neovim mostrará sugerencias cuando se encuentre con el caracter . o :.

Habilitar "inlay hints"

Inlay hints es parecido al texto virtual. Estos son fragmento de texto que Neovim agrega a lo que estamos editando, pero que en realidad no es parte del archivo. En este caso se usa para mostrar el tipo/clase de una variable o argumento de una función.

En este caso debemos usar la función vim.lsp.inlay_hint.enable() en el archivo donde queremos habilitar esta funcionalidad. Como siempre, podemos usar un autocomando con el evento LspAttach.

Nota: la mayoría de los servidores que tienen soporte para esta funcionalidad la deshabilitan por defecto. Esto quiere decir que activar los inlay hints en Neovim no es suficiente, también debemos buscar las opciones específicas del servidor LSP y configurarlas en la función vim.lsp.start().

-- Pueden agregar esto en su archivo `init.lua`

vim.api.nvim_create_autocmd('LspAttach', {
  desc = 'Habilitar inlay hints',
  callback = function(event)
    local id = vim.tbl_get(event, 'data', 'client_id')
    local client = id and vim.lsp.get_client_by_id(id)
    if client == nil or not client.supports_method('textDocument/inlayHint') then
      return
    end

    vim.lsp.inlay_hint.enable(true, {bufnr = event.buf})
  end,
})

Conclusión

Espero haber demostrado que no es tan difícil usar un servidor LSP en Neovim. La parte que realmente requiere esfuerzo es aprender todo el contexto necesario. ¿Qué significa LSP? ¿Qué es un servidor LSP? ¿Filetype plugin? Pero una vez que tienen conocimiento de todas las piezas involucradas todo se hace más fácil.

Una cosa más... por favor no ignoren el "conocimento básico." Dediquen un poco de tiempo para aprender la sintaxis de lua. Aprendan sobre el comando :help en Neovim. Investiguen un poco sobre la API de lua que ofrece Neovim. Les aconsejo leer la guía oficial de lua que está en la documentación de Neovim, es buen punto de partida.

Gracias por su tiempo. Si este artículo les pareció útil y quieren apoyar mis esfuerzos para crear más contenido pueden dejar una propina en ko-fi.com/vonheikemen.

A guide on Neovim's LSP client

Heiker — Sat, 13 Jan 2024 13:28:01 +0000

Pueden leer la versión en español aquí.

Maybe I should have called this "How to enable IDE-like features without third party plugins." Sounds interesting, right? That's basically what I want to show you here.

I'm going to explain how to use the new configuration method that was introduced in Neovim v0.11. And I want to show how it works because it's basically a layer on top of existing features. This way you can make your own setup even on older Neovim versions.

Requirements

Neovim v0.8 or greater.
A language server.
Patience/Energy to write some lua code for each language server.

If you don't know anything about lua here are a couple of links that can help you learn the basics:

Let's start with the language server

A language server is an external program that follows the Language Server Protocol. The LSP specification defines what type of messages a language server can receive and also how it should respond. The idea here is that any tool that follows the LSP specification can communicate with a language server.

And so the language server is the thing that analyzes our source code and it can tell the editor what to do.

Where can we find these language servers?

The website for the LSP specification has a list.

In this particular case...

I want to use Gleam and LuaLS as examples.

Gleam is a toolchain. It has a compiler, a formatter and a language server. Install instructions are in the official documentation: Getting started.

LuaLS is a language server for lua. You can download it from github releases or build it from source.

Once you have a language server installed it's a good idea to check if Neovim "knows" where it is. You can check that using the function exepath().

For Gleam you want to search for the gleam executable.

:echo exepath('gleam')

LuaLS' executable is called lua-language-server.

:echo exepath('lua-language-server')

This should show you the path to the executable. If it doesn't, it means something went wrong during the installation.

Basic Usage

Before we write any code we should learn how to use the language server. This should be in the official documentation of said server.

If we can't find the basic usage in the documentation we can go to nvim-lspconfig's github repository. In there we look for a folder called lsp, this contains configuration files for a bunch of language servers.

Say we are interested in Gleam, we should go and inspect the contents of gleam.lua.

return {
  cmd = { 'gleam', 'lsp' },
  filetypes = { 'gleam' },
  root_markers = { 'gleam.toml', '.git' },
}

This shows the minimum amount of information we need to make a language server work.

The cmd property has the command we need to start the language server. Remember, language servers are external programs so gleam lsp is a valid command you can type on the terminal. And funny enough, if you do that it'll give you this message.

This command is intended to be run by language server clients such
as a text editor rather than being run directly in the console.

filetypes is the list of languages the server can handle. These must be valid filetype names that Neovim supports.

root_markers should be a list of files or folders. We will use this to determine the root of the project.

The lsp folder

This lsp folder is not something unique only nvim-lspconfig can have. Since Neovim v0.11 it is now part of the runtimepath. This means we can have an lsp folder inside our own personal configuration.

Imagine a Neovim config folder with this structure:

nvim
├── init.vim
├── .nvim.lua
└── lsp
    ├── gleam.lua
    └── luals-nvim.lua

The configuration inside nvim/lsp/gleam.lua can be the exact same thing nvim-lspconfig has.

-- nvim/lsp/gleam.lua

return {
  cmd = {'gleam', 'lsp'},
  filetypes = {'gleam'},
  root_markers = {'gleam.toml', '.git'},
}

We do have some amount of freedom here. So in luals-nvim I want to have a configuration made specifically for a Neovim config with an .nvim.lua script at the root.

-- nvim/lsp/luals-nvim.lua

return {
  cmd = {'lua-language-server'},
  filetypes = {'lua'},
  root_markers = {'.nvim.lua'},
  settings = {
    Lua = {
      runtime = {
        version = 'LuaJIT',
        path = {'lua/?.lua', 'lua/?/init.lua'},
      },
      diagnostics = {
        globals = {'vim'},
      },
      telemetry = {
        enable = false,
      },
      workspace = {
        checkThirdParty = false,
        library = {
          vim.env.VIMRUNTIME,
        },
      },
    },
  },
}

Inside the lsp folder the files can have any name. So I made this luals-nvim instead of something generic like lua or luals. And the return value can be anything that the vim.lsp.config() function expects.

Notice in this one we have a settings property. That's reserved for server specific options. You'll have to search the documentation of the language server to know what options you can add there.

Now, having a configuration in the lsp folder doesn't mean Neovim will use it. We have to be explicit. To use a language server we must call the function vim.lsp.enable().

So in this example the init.vim looks like this.

" nvim/init.vim

set exrc

lua vim.lsp.enable('gleam')

But why init.vim?

I just wanted an excuse to show is possible to execute lua code inside vimscript. Some Vim users think they have to delete their vimscript config to use lua. That's just not true.

Anyway, next time we open Neovim it will look for a file that matches the pattern lsp/gleam.lua inside the runtimepath. Then it will create an autocommand using the list we provided in the filetypes property. So whenever we open a file with the type gleam Neovim will try to enable the language server.

What about LuaLS?

The config we have for LuaLS only makes sense for Neovim. So I think this is a good oportunity to use an exrc file. Vim's version of a project local config. When the exrc option is enabled Vim/Neovim will execute a script located in the current working directory. This is both convenient and dangerous. So Neovim's exrc is slightly different from Vim. Neovim will ask you if you "trust" the file, and if you say yes it'll be executed. If the content of the file remains the same Neovim won't ask again, it'll just execute it automatically.

Personally, I would create an alias to enable exrc instead of having it in the init file. Something like this.

alias code='nvim --cmd "set exrc"'

Let's go back to LuaLS. After Neovim is done executing the init file it will search for an .nvim.lua in the current working directory. The one in our Neovim folder will have this.

-- nvim/.nvim.lua

vim.lsp.enable('luals-nvim')

So Neovim will not even try to use lsp/luals-nvim.lua if we are not inside the config folder. The downside of this approach (right now) is that we have to open Neovim in the exact location where .nvim.lua is stored.

Single file setup?

If you are the kind of person that has a very simple config that fits in one file, I have good news for you. You are not forced to use the lsp folder to configure a language server.

The configurations inside the lsp folder can be extended using the function vim.lsp.config(). But this can also be used to create an entire new config, without needing to create a new file.

Here's an example:

-- nvim/init.lua

vim.lsp.config('gleam', {
  cmd = {'gleam', 'lsp'},
  filetypes = {'gleam'},
  root_markers = {'gleam.toml', '.git'},
})

vim.lsp.enable('gleam')

Where to look if something goes wrong?

If Neovim wasn't able to start the language server, you can take a look at the log file, execute this command inside Neovim:

:lua vim.cmd.edit(vim.lsp.get_log_path())

Look for the lines that start with [ERROR]. Maybe there is an error message with some useful information.

If you want the logs to have more details, increase the log level using this function.

vim.lsp.set_log_level('debug')

And since Neovim v0.10 you can do a "health check" with this command:

:checkhealth lsp

Execute on filetype

Turns out vim.lsp.enable() is actually a layer on top of things we already had. We can still use a language server without plugins on older Neovim versions, we just need to know how to put the pieces together.

If the server we want to use only supports one language it makes sense to use a "filetype plugin."

We create a filetype plugin in our Neovim configuration simply by adding a script in the folder ftplugin. Note that the name of the script needs to be the same as a valid filetype.

We can navigate to Neovim's configuration folder, open Neovim and then create the ftplugin folder.

:call mkdir('./ftplugin', 'p')

If we want a filetype plugin for Gleam we create a new file called gleam.lua.

:edit ftplugin/gleam.lua | write

On the other hand, if we have a language server that can work on multiple filetypes we can use an autocommand on the event FileType.

vim.api.nvim_create_autocmd('FileType', {
  pattern = {'css', 'less', 'sass'},
  callback = function()
    ---
    -- In here you can do whatever you want
    ---
  end,
})

The pattern of the FileType event is a list of filetypes. The same thing you would provide in the filetypes property of an lsp config file.

Inside the filetype plugin or the autocommand we are going to execute the function that enables the language server. But first, we need to know how recreate the logic behind root_markers.

Root directory

Language servers need to know what is the path of our project folder and this is a problem Neovim needs to solve.

On Neovim v0.10 we can use a function called vim.fs.root(). We will give it a list of files and it will return the parent directory of the first match.

What do we look for? We search for common configuration files that projects have in the root folder. So, in a Gleam project there is always a gleam.toml file. Javascript projects usually have a package.json. Rust projects have a cargo.toml. We feed this information to vim.fs.root() and it should give us a path we can use.

We can make a test already by adding this piece of code in a gleam filetype plugin.

-- nvim/ftplugin/gleam.lua
-- NOTE: vim.fs.root() is only available on Neovim v0.10 or greater

local root_markers = {'gleam.toml'}
local root_dir = vim.fs.root(0, root_markers)

print(root_dir)

On Neovim v0.9 or lower we would have to recreate the behavior of vim.fs.root(). For this we can use vim.fs.find().

-- nvim/ftplugin/gleam.lua
-- NOTE: this code is for Neovim v0.9.5 or lower

local root_markers = {'gleam.toml'}
local buffer = vim.api.nvim_buf_get_name(0)
local paths = vim.fs.find(root_markers, {
  upward = true,
  path = vim.fn.fnamemodify(buffer, ':p:h'),
})

local root_dir = vim.fs.dirname(paths[1])

print(root_dir)

Start the client

We are ready to enable the language server. Now we call the function vim.lsp.start(), which is the same thing vim.lsp.enable() uses under the hood.

The first time this is executed it will launch the language server as an external process. When called again with the same root directory it will only send information to the existing process.

Our gleam filetype plugin can look like this.

-- nvim/ftplugin/gleam.lua
-- NOTE: vim.fs.root() is only available on Neovim v0.10 or greater

local root_markers = {'gleam.toml'}
local root_dir = vim.fs.root(0, root_markers)

if root_dir then
  vim.lsp.start({
    cmd = {'gleam', 'lsp'},
    root_dir = root_dir,
  })
end

With this setup we should get "diagnostics" out the box. If there is an error in a gleam file Neovim will show what line has the error.

About the diagnostics

So the diagnostics signs, the thing Neovim uses to tell us there is an error in our source code... by default the space needed to render that sign is hidden and when there is a sign the whole screen shifts to the right. That behavior can be configured.

If you set the option signcolumn to the string yes Neovim will reserve the space for the sign. You will have a whitespace reserved for any type of signs in the gutter.

In your init.vim you can have this.

set signcolumn=yes

Or, if you have an init.lua.

vim.o.signcolumn = 'yes'

If you set signcolumn to the string no, Neovim will hide the column altogether. Don't do that unless you are fully aware of the consequences. There is a better way to hide the diagnostic signs.

vim.diagnostic

There is a lua module dedicated specifically to diagnostics: vim.diagnostic. This has a .config() function we can use to configure the interface of the diagnostics.

Hide diagnostic signs

This is the safe way to disable the diagnostics sign.

vim.diagnostic.config({
  signs = false,
})

Virtual text

There is an option to show the error message inline. This is called "virtual text." This used to be enabled by default, but now on Neovim v0.11 is disabled.

vim.diagnostic.config({
  virtual_text = true,
})

If you have Neovim v0.10 or greater you can read the diagnostic message under the cursor with the keybinding <C-w>d (control + w then d). This will trigger the function vim.diagnostic.open_float().

When using Neovim v0.9.5 or lower you'll have to create that keybinding yourself.

vim.keymap.set('n', '<C-w>d', '<cmd>lua vim.diagnostic.open_float()<cr>')

Now, I would love to explain all the options vim.diagnostic.config() supports but we don't have time for that. If you want to know more you can read the documentation.

What else do we get for free?

These are things Neovim does when a language server active in the buffer.

Since Neovim v0.8

There is an LSP powered tagfunc. That means we can jump to the definition of a function or class using the keybinding <C-]> (control + ]). And can jump back to where we were using <C-t>.
The formatexpr option is set to a function that uses the language server. This means the gq operator can format a piece of code. We can enter visual mode, select a piece of text, press gq and Neovim will request the language server to format the code.
The omnifunc option is also set. This one enables smart code completions. In insert mode the keybinding <C-x><C-o> (control + x then control + o) will trigger the completion menu with suggestions that the language server think are relevant.

Since Neovim v0.9

Semantic highlight is supported. Some language servers can provide information about the tokens in the source code, this allows for a more accurate syntax highlight.

Since Neovim v0.10

In normal mode, if we don't have a custom keybinding for K then it will display the available documentation for the symbol under the cursor.
In normal mode, <C-w>d opens a floating window showing the diagnostics in the line under the cursor.
In normal mode, [d and ]d can be used to move the cursor to the previous and next diagnostic of the current file.

Since Neovim v0.11

In normal mode, grn renames all references of the symbol under the cursor.
In normal mode, gra shows a list of code actions available in the line under the cursor.
In normal mode, grr lists all the references of the symbol under the cursor.
In normal mode, gri lists all the implementations for the symbol under the cursor.
In normal mode, gO lists all symbols in the current buffer.
In insert mode, <Ctrl-s> displays the function signature of the symbol under the cursor.

LSP keymaps

Neovim v0.11 has defaults keymaps for almost everything now. The good news is that older versions of Neovim have the same features as v0.11, so the only thing we have to do is create keymaps for them.

So here's the code you can add in your personal configuration.

-- you can add this in your init.lua

-- These keymaps are the defaults in Neovim v0.10
vim.keymap.set('n', '[d', '<cmd>lua vim.diagnostic.goto_prev()<cr>')
vim.keymap.set('n', ']d', '<cmd>lua vim.diagnostic.goto_next()<cr>')
vim.keymap.set('n', '<C-w>d', '<cmd>lua vim.diagnostic.open_float()<cr>')
vim.keymap.set('n', '<C-w><C-d>', '<cmd>lua vim.diagnostic.open_float()<cr>')

vim.api.nvim_create_autocmd('LspAttach', {
  callback = function(event)
    local bufmap = function(mode, rhs, lhs)
      vim.keymap.set(mode, rhs, lhs, {buffer = event.buf})
    end

    -- These keymaps are the defaults in Neovim v0.11
    bufmap('n', 'K', '<cmd>lua vim.lsp.buf.hover()<cr>')
    bufmap('n', 'grr', '<cmd>lua vim.lsp.buf.references()<cr>')
    bufmap('n', 'gri', '<cmd>lua vim.lsp.buf.implementation()<cr>')
    bufmap('n', 'grn', '<cmd>lua vim.lsp.buf.rename()<cr>')
    bufmap('n', 'gra', '<cmd>lua vim.lsp.buf.code_action()<cr>')
    bufmap('n', 'gO', '<cmd>lua vim.lsp.buf.document_symbol()<cr>')
    bufmap({'i', 's'}, '<C-s>', '<cmd>lua vim.lsp.buf.signature_help()<cr>')

    -- These are custom keymaps
    bufmap('n', 'gd', '<cmd>lua vim.lsp.buf.definition()<cr>')
    bufmap('n', 'grt', '<cmd>lua vim.lsp.buf.type_definition()<cr>')
    bufmap('n', 'grd', '<cmd>lua vim.lsp.buf.declaration()<cr>')
    bufmap({'n', 'x'}, 'gq', '<cmd>lua vim.lsp.buf.format({async = true})<cr>')
  end,
})

And here is the vimscript equivalent:

" you can add this in your init.vim

" These keymaps are the defaults in Neovim v0.10
nnoremap [d <cmd>lua vim.diagnostic.goto_prev()<cr>
nnoremap ]d <cmd>lua vim.diagnostic.goto_next()<cr>
nnoremap <C-w>d <cmd>lua vim.diagnostic.open_float()<cr>
nnoremap <C-w><C-d> <cmd>lua vim.diagnostic.open_float()<cr>

function! LspAttached() abort
  " These keymaps are the defaults in Neovim v0.11
  nnoremap <buffer> K <cmd>lua vim.lsp.buf.hover()<cr>
  nnoremap <buffer> grr <cmd>lua vim.lsp.buf.references()<cr>
  nnoremap <buffer> gri <cmd>lua vim.lsp.buf.implementation()<cr>
  nnoremap <buffer> grn <cmd>lua vim.lsp.buf.rename()<cr>
  nnoremap <buffer> gra <cmd>lua vim.lsp.buf.code_action()<cr>
  nnoremap <buffer> gO <cmd>lua vim.lsp.buf.document_symbol()<cr>
  inoremap <buffer> <C-s> <cmd>lua vim.lsp.buf.signature_help()<cr>
  snoremap <buffer> <C-s> <cmd>lua vim.lsp.buf.signature_help()<cr>

  " These are custom keymaps
  nnoremap <buffer> gd <cmd>lua vim.lsp.buf.definition()<cr>
  nnoremap <buffer> gq <cmd>lua vim.lsp.buf.format({async = true})<cr>
  xnoremap <buffer> gq <cmd>lua vim.lsp.buf.format({async = true})<cr>
  nnoremap <buffer> grd <cmd>lua vim.lsp.buf.declaration()<cr>
  nnoremap <buffer> grt <cmd>lua vim.lsp.buf.type_definition()<cr>
endfunction

autocmd LspAttach * call LspAttached()

Fair warning

Not every language server implements the entire LSP specification. The features may not be consistent between servers.

For example, Gleam can show diagnostics in real time, there is no need to save the file to get new diagnostics. But rust-analyzer, the language server for rust, can only update diagnostics after saving the file.

Here's another example: ruff-lsp, a language server for python. It describes itself as a linter and code formatter. As far as I can tell ruff-lsp does not provide code completions or semantic highlights.

What I want say is this: read the documentation of the language server so you know what it can do.

Bonus content

At this point I'd say you have all the essential knowledge needed to be productive. What follows are tips, configurations, and features you can implement by adding some boilerplate code in your Neovim configuration.

Format on save

What we do here is trigger the function vim.lsp.buf.format() before Neovim saves a file. And of course, we only do it when there is an active language server.

Important note: most language servers with formatting capabilities have their own style settings. For example, we can have 2 space indent in our Neovim config but maybe the language server formats the code with 4 space indent. So it's a good idea to check the documentation of the language server to see how to configure that.

-- You can add this in your init.lua
-- or a global plugin

local fmt_group = vim.api.nvim_create_augroup('autoformat_cmds', {clear = true})

local function setup_autoformat(event)
  local id = vim.tbl_get(event, 'data', 'client_id')
  local client = id and vim.lsp.get_client_by_id(id)
  if client == nil then
    return
  end

  vim.api.nvim_clear_autocmds({group = fmt_group, buffer = event.buf})

  local buf_format = function(e)
    vim.lsp.buf.format({
      bufnr = e.buf,
      async = false,
      timeout_ms = 10000,
    })
  end

  vim.api.nvim_create_autocmd('BufWritePre', {
    buffer = event.buf,
    group = fmt_group,
    desc = 'Format current buffer',
    callback = buf_format,
  })
end

vim.api.nvim_create_autocmd('LspAttach', {
  desc = 'Setup format on save',
  callback = setup_autoformat,
})

Change diagnostics sign text

When using Neovim v0.9.5 or lower we need to call the function vim.fn.sign_define().

-- You can add this in your init.lua
-- or a global plugin

local function sign_define(args)
  vim.fn.sign_define(args.name, {
    texthl = args.name,
    text = args.text,
    numhl = ''
  })
end

sign_define({name = 'DiagnosticSignError', text = '✘'})
sign_define({name = 'DiagnosticSignWarn', text = '▲'})
sign_define({name = 'DiagnosticSignHint', text = '⚑'})
sign_define({name = 'DiagnosticSignInfo', text = '»'})

When using Neovim v0.10 or greater we should do this with vim.diagnostic.config().

-- You can add this in your init.lua
-- or a global plugin

vim.diagnostic.config({
  signs = {
    text = {
      [vim.diagnostic.severity.ERROR] = '✘',
      [vim.diagnostic.severity.WARN] = '▲',
      [vim.diagnostic.severity.HINT] = '⚑',
      [vim.diagnostic.severity.INFO] = '»',
    },
  },
})

Disable semantic highlights

To opt-out of this feature Neovim's documentation suggest that we "delete" a property from the LSP client instance.

-- You can add this in your init.lua
-- or a global plugin

vim.api.nvim_create_autocmd('LspAttach', {
  desc = 'Disable LSP semantic highlights',
  callback = function(event)
    local id = vim.tbl_get(event, 'data', 'client_id')
    local client = id and vim.lsp.get_client_by_id(id)
    if client == nil then
      return
    end

    client.server_capabilities.semanticTokensProvider = nil
  end,
})

Highlight symbol under cursor

What we want to do here is call the function vim.lsp.buf.document_highlight() when the cursor spends some amount of time on top of a symbol. And then clear the highlight when the cursor moves.

Note, for this to work properly the colorscheme needs to support the following highlight groups:

LspReferenceRead
LspReferenceText
LspReferenceWrite

If the colorscheme does not support these highlight groups, we can "link" them to an existing group. Here's an example using the Search highlight group.

vim.api.nvim_set_hl(0, 'LspReferenceRead', {link = 'Search'})
vim.api.nvim_set_hl(0, 'LspReferenceText', {link = 'Search'})
vim.api.nvim_set_hl(0, 'LspReferenceWrite', {link = 'Search'})

-- You can add this in your init.lua
-- or a global plugin

-- time it takes to trigger the `CursorHold` event
vim.opt.updatetime = 400

local function highlight_symbol(event)
  local id = vim.tbl_get(event, 'data', 'client_id')
  local client = id and vim.lsp.get_client_by_id(id)
  if client == nil or not client.supports_method('textDocument/documentHighlight') then
    return
  end

  local group = vim.api.nvim_create_augroup('highlight_symbol', {clear = false})

  vim.api.nvim_clear_autocmds({buffer = event.buf, group = group})

  vim.api.nvim_create_autocmd({'CursorHold', 'CursorHoldI'}, {
    group = group,
    buffer = event.buf,
    callback = vim.lsp.buf.document_highlight,
  })

  vim.api.nvim_create_autocmd({'CursorMoved', 'CursorMovedI'}, {
    group = group,
    buffer = event.buf,
    callback = vim.lsp.buf.clear_references,
  })
end

vim.api.nvim_create_autocmd('LspAttach', {
  desc = 'Setup highlight symbol',
  callback = highlight_symbol,
})

Simple tab complete

In this one we will use the Tab (and shift tab) key to navigate between the items in the completion menu. When the completion menu is not visible and the cursor is in a whitespace character, it will insert a tab character. Else, it will trigger the completion menu.

When the language server can provide code completion it'll use that. Otherwise, it will try to suggest words found in the current buffer.

Note that you can use the Enter key or <C-y> to confirm the current item in the completion menu

-- You can add this in your init.lua
-- or a global plugin

vim.opt.completeopt = {'menu', 'menuone', 'noselect', 'noinsert'}
vim.opt.shortmess:append('c')

local function tab_complete()
  if vim.fn.pumvisible() == 1 then
    -- navigate to next item in completion menu
    return '<Down>'
  end

  local c = vim.fn.col('.') - 1
  local is_whitespace = c == 0 or vim.fn.getline('.'):sub(c, c):match('%s')

  if is_whitespace then
    -- insert tab
    return '<Tab>'
  end

  local lsp_completion = vim.bo.omnifunc == 'v:lua.vim.lsp.omnifunc'

  if lsp_completion then
    -- trigger lsp code completion
    return '<C-x><C-o>'
  end

  -- suggest words in current buffer
  return '<C-x><C-n>'
end

local function tab_prev()
  if vim.fn.pumvisible() == 1 then
    -- navigate to previous item in completion menu
    return '<Up>'
  end

  -- insert tab
  return '<Tab>'
end

vim.keymap.set('i', '<Tab>', tab_complete, {expr = true})
vim.keymap.set('i', '<S-Tab>', tab_prev, {expr = true})

Expand snippets

Neovim v0.11 or greater is required.

For this we use a new module called vim.lsp.completion, this will extend the behavior of the builtin completion so it can support "additional text edits" a language server can provide. Additional edits can be things like adding missing import statements or expanding code snippets.

Right now you have to opt-in to the features vim.lsp.completion provides. So, when a language server is active you have to call the vim.lsp.completion.enable() function.

-- You can add this in your init.lua
-- or a global plugin
vim.opt.completeopt = {'menu', 'menuone', 'noinsert', 'noselect'}

vim.api.nvim_create_autocmd('LspAttach', {
  desc = 'Enable vim.lsp.completion',
  callback = function(event)
    local client_id = vim.tbl_get(event, 'data', 'client_id')
    if client_id == nil then
      return
    end

    vim.lsp.completion.enable(true, client_id, event.buf, {autotrigger = false})

    -- Trigger lsp completion manually using Ctrl + Space
    vim.keymap.set('i', '<C-Space>', '<cmd>lua vim.lsp.completion.trigger()<cr>')
  end
})

Notice in the last argument to .enable() there is a property called autotrigger. false is the default value so I just leave it like that. If you set it to true Neovim will trigger the completion menu when it finds a trigger character. Trigger characters change depending on the language server. In lua for example, the completion will be triggered automatically after a . or : character.

Enable inlay hints

Neovim v0.10 or greater is required.

For this we can use the function vim.lsp.inlay_hint.enable().

Note that some language servers may have inlay hints disabled by default. The settings needed to enable hints should be in the documentation of the language server.

-- You can add this in your init.lua
-- or a global plugin

vim.api.nvim_create_autocmd('LspAttach', {
  desc = 'Enable inlay hints',
  callback = function(event)
    local id = vim.tbl_get(event, 'data', 'client_id')
    local client = id and vim.lsp.get_client_by_id(id)
    if client == nil or not client.supports_method('textDocument/inlayHint') then
      return
    end

    vim.lsp.inlay_hint.enable(true, {bufnr = event.buf})
  end,
})

Conclusion

Hopefully I showed is not difficult to "connect" a language server with Neovim. The hard part is gathering all the context inside your head. What does LSP even mean? What's a language server? Filetype plugin? I hardly know her. But once you know about the moving pieces and where to find the information you need, it gets easier.

One last thing, don't ignore the basics. Take your time and learn lua, read Neovim's lua guide and learn how to navigate Neovim's documentation with the :help command.

Thank you for your time. If you find this article useful and want to support my efforts, consider leaving a tip in ko-fi.com/vonheikemen.

Lazy.nvim: plugin configuration

Heiker — Sun, 07 Jan 2024 00:09:45 +0000

Here I'm going to explain how different options in lazy.nvim's plugin configuration interact with each other, and explore a little bit the import system it has. I hope I can give you the basic knowledge that you need to structure your personal Neovim configuration however you want, using lazy.nvim's import feature.

Plugin Spec

In lazy.nvim's documentation they have the concept of "plugin spec." This describes the data lazy.nvim needs about the plugin we want to install. Things like the url of the plugin, the branch we want to download or the plugin dependencies (if it even have dependencies).

From a technical point of view the plugin spec is a "lua table" with a specific set of properties.

Here is an example of a plugin spec for the plugin mini.surround.

{
  'nvim-mini/mini.surround',
  branch = 'stable',
  main = 'mini.surround',
  opts = {
    search_method = 'cover_or_next',
  },
}

And so this plugin spec is the thing you give to lazy.nvim's setup function. In your personal Neovim configuration you would have something like this.

require('lazy').setup({
  {
    'nvim-mini/mini.surround',
    branch = 'stable',
    main = 'mini.surround',
    opts = {
      search_method = 'cover_or_next',
    },
  },
})

You can find the full list of properties in lazy.nvim's documentation.

The shortest spec

Because Folke (the author of lazy.nvim) is awesome, the only piece of data we need to download a plugin is the short url. So this is a valid plugin spec.

{'nvim-mini/mini.surround'}

Notice this is still a "lua table," so actually the shortest spec we can give to lazy.nvim is a string with a short url.

'nvim-mini/mini.surround'

Keep in mind, if you do this, lazy.nvim's is going to make some decision for you. In this example I'm showing it might not choose the stable branch for mini.surround. And it won't setup the plugin automatically.

This short spec is best to apply for plugins that don't require user intervention. So mini.surround might not be one of those.

"Plugin lifecycle"

In this section we are going to look at some lua functions we can use in the plugin spec.

These functions get executed at different points in time during lazy.nvim's initialization process.

init

This function that gets executed during Neovim's startup process before the plugin is loaded. Note that lazy.nvim will always execute it during startup even if the plugin is configured to be lazy loaded.

When is this useful?

In case we want to configure a plugin written in vimscript. These types of plugins are configured using global variables that must be created before the plugin loads.

Here is an example of a plugin spec for ctrlsf.vim.

{
  'dyng/ctrlsf.vim',
  init = function()
    -- to create global variables accessible to
    -- vimscript we use`vim.g`

    vim.g.ctrlsf_default_root = 'cwd'
    vim.g.ctrlsf_auto_focus = {at = 'start'}
  end,
}

opts

Let me show you the plugin spec for mini.surround again.

{
  'nvim-mini/mini.surround',
  branch = 'stable',
  main = 'mini.surround',
  opts = {
    search_method = 'cover_or_next',
  },
}

Believe or not, when we use the opts property like that we are also using another property called config.

See, like 90% of lua plugins follow a common a convention, they have a lua module that exposes a function called setup. So when we use opts we are telling lazy.nvim that the plugin follows that convention. So lazy.nvim will pass that opts property to the setup function of the plugin.

Let me try to illustrate this with code. Imagine that lazy.nvim is adding a config function for you, and it does something like this.

{
  'nvim-mini/mini.surround',
  branch = 'stable',
  main = 'mini.surround',
  opts = {
    search_method = 'cover_or_next',
  },
  config = function(PluginSpec)
    local options = nil

    if type(PluginSpec.opts) == 'function' then
      options = PluginSpec.opts(PluginSpec)
    elseif type(PluginSpec.opts) ~= 'nil' then
      options = PluginSpec.opts
    end

    require(PluginSpec.main).setup(options) 
  end
}

Of course this is an extremely simplified version of what happens under the hood.

Actually, lazy.nvim will try it's best to figure out what is the name of the "main module" of the plugin. If you decide to use lazy.nvim's config implementation then adding the main property to the plugin spec is optional.

Notice in the implementation I showed opts can also be a function. lazy.nvim allows that too. So you can have a custom implementation that returns the result you want. This is also a valid spec.

{
  'nvim-mini/mini.surround',
  branch = 'stable',
  main = 'mini.surround',
  opts = function(PluginSpec)
    -- silly example

    if vim.env.THIS_IS_MY_WORK_PC == 'yes' then
      -- work pc gets the custom configuration
      return {
        search_method = 'cover_or_next',
      }
    end

    -- the others just use whatever 
    -- defaults mini.surround has
    return {}
  end,
}

When does this opts function gets executed?

Whenever config gets executed. Speaking of which...

config

This is the function that gets executed after lazy.nvim loads the plugin.

The common usecase for this function is to call the setup function of lua plugins.

So we can write the plugin spec for mini.surround like this.

{
  'nvim-mini/mini.surround',
  branch = 'stable',
  config = function()
    require('mini.surround').setup({
      search_method = 'cover_or_next',
    })
  end,
}

Notice here is not necessary to add main or opts to the plugin spec, we already handle all of that manually. The string mini.surround is written in the require function, and the lua table that used to be in opts is now in the .setup() function.

config & opts

You can use config and opts together if you wanted to. The previous example could be written like this.

{
  'nvim-mini/mini.surround',
  branch = 'stable',
  opts = {
    search_method = 'cover_or_next',
  },
  config = function(PluginSpec, opts)
    require('mini.surround').setup(opts)
  end,
}

Is there a use case for this?

Not if you have full control of your Neovim configuration.

This can be useful if you have multiple plugin spec for the same plugin. And now you may ask, Why? Why would someone have multiple plugin spec for the same thing? You would if you are using a "Neovim distribution" that happens to have lazy.nvim as a plugin manager. Usually in this case the author of the Neovim distribution will give you the chance to override their default options.

If you don't know, a Neovim distribution is basically a pre-made Neovim configuration.

Import (all the things)

So lazy.nvim has this feature that allows you to specify the name of a lua module, and then lazy will get the plugin spec from that module.

Instead of having a full plugin spec you can do something like this.

{import = 'user.plugins'}

Where user.plugins can be any valid name for a lua module.

And the module that you specify can be just one lua module that returns a plugin spec or it can be a folder with a bunch of lua files.

In our example user.plugins can be a lua file, located in Neovim's runtimepath, that returns a lua spec.

# imagine this is your neovim config folder

nvim
├── init.lua
└── lua
    └── user
        └── plugins.lua

And because lazy.nvim is awesome this user.plugins module can also be a folder that contains lua files (that return plugin specs).

# neovim config folder

nvim
├── init.lua
└── lua
    └── user
        └── plugins
            ├── mini.lua
            ├── theming.lua
            └── ...

Example time.

Let's say we have this in our init.lua file.

require('lazy').setup({
  {import = 'user.plugins'},
})

We can create the user.plugins folder and inside we can have file called mini.lua. And in there we can return a plugin spec or a list of plugin spec.

-- nvim/lua/user/plugins/mini.lua

return {
  {
    'nvim-mini/mini.surround',
    branch = 'stable',
    main = 'mini.surround'
    opts = {
      search_method = 'cover_or_next',
    },
  },
  {
    'nvim-mini/mini.comment',
    branch = 'stable',
    main = 'mini.comment',
    opts = {},
  },
}

In that same user.plugins folder we can also have a file called theming.lua. There we can add plugins that modify Neovim's interface somehow.

-- nvim/lua/user/plugins/theming.lua

return {
  {
    'nvim-lualine/lualine.nvim',
    opts = {
      options = {
        icons_enabled = false,
        component_separators = '|',
        section_separators = '',
      },
    },
  },
  {
    'lukas-reineke/indent-blankline.nvim',
    -- i don't think lazy will be able to guess 
    -- `ibl` is the main module, so set it manually
    main = 'ibl',
    opts = {
      enabled = true,
      scope = {
        enabled = false,
      },
      indent = {
        char = '▏',
      },
    }
  }
}

And then we can have other lua files in user.plugins... you get the idea.

Hopefully you can see the potential. You can separate your plugins by category, purpose or configure each plugin in its own file. You are free to do whatever you want, as long as you give lazy.nvim what it needs.

One more thing...

Since you can have your entire plugin setup behind one import, lazy.nvim has a "shortcut" you can use.

So, this example

require('lazy').setup({
  {import = 'user.plugins'},
})

Does the same thing as this

require('lazy').setup('user.plugins')

You can call your entire plugin setup with just one line of code.

Example configuration

If you are interested, I have template configuration up in github that shows a plugin setup split into many modules:

lazy-template

Thank you for your time. If you find this article useful and want to support my efforts, consider leaving a tip in ko-fi.com/vonheikemen.

Lazy.nvim: how to revert a plugin back to a previous version

Heiker — Sun, 30 Jul 2023 20:38:12 +0000

If you've been using Neovim for a while maybe you noticed that plugins receive updates all the time. This isn't always good news, a change can introduce a bug in your config, or maybe it changed the current api. It can be annoying, I know. But today we are going to learn how lazy.nvim can help us recover from bad situations, so we can always have Neovim in a good state.

I'm going to tell you how to rollback a plugin update using lazy.nvim's interface. And also, in case something goes horribly wrong, how you can rollback every plugin installed back to a known previous state.

Revert a plugin

If you know what plugin broke your Neovim config you can execute the command.

:Lazy log some-plugin

Where some-plugin is the name of your plugin. This command will open lazy.nvim's interface and it will show the previous commits.

If I execute the command :Lazy log nvim-lspconfig, this is what I get.

● nvim-lspconfig 371.28ms ⌘ Lsp
  b609127 feat(omnisharp): find root directory for .csx scripts (#2715) (hace 4 días)
  654dd9e fix(rust_analyzer): check active clients is empty (#2734) (hace 5 días)
  6f426c3 docs: update server_configurations.md skip-checks: true (hace 6 días)
  01b25ff docs: make vimdocs consistent with readme (#2732) (hace 6 días)
  dd11ba7 fix(pyright): re-enable single-file mode (#2730) (hace 10 días)
  6c53bf7 fix(pyright): fix root_dir detection (#2727) (hace 10 días)
  443c56a docs: update server_configurations.md skip-checks: true (hace 11 días)
  e7be6d4 feat(v): add `v-analyzer` (#2726) (hace 11 días)

Notice that before each commit message we have the commit hash.

To revert the plugin to any of those commits all I have to do is place the cursor above the commit hash and press r.

The lockfile

If there is no way of knowing which plugin is causing the error then you could use this command

:Lazy restore

With this you will be able to revert all the plugins to the state reflected in the lockfile.

If you don't know, the lockfile is a JSON file that contains the current commit hash of all your plugins. This is located in the same folder as your init.lua or init.vim config. The lockfile is actually called lazy-lock.json.

There is one problem: the lockfile updates with your plugins. If you don't backup your lockfile before an update there is no way to revert to the previous working state.

What to do?

Here are few ideas:

Make a copy

Easiest thing will be to create a copy of the lockfile and just keep it around. You would navigate to your Neovim config folder and copy the file lazy-lock.json.

cp lazy-lock.json lazy-lock.backup.json

There you go. lazy-lock.backup.json can have the last working state of all your plugins. When something goes wrong you simply change the name of the backup file to lazy-lock.json. Then in Neovim you can execute the command :Lazy restore.

Use git

You would want to add the lockfile to git. Have a commit with a stable version of the lockfile. If something goes wrong you can revert the lockfile using the git cli. And then use :Lazy restore inside Neovim.

If you don't know how to revert to a commit with the git cli, try to use the website of your repo (github/gitlab/whatever). Go to the lockfile and copy it to your system.

Automatic backups

What I do is use lua to make a backup of the lockfile. I use the autocommand User LazyUpdatePre, this is executed before lazy.nvim updates the plugins. Here I have a function that creates a copy of the lockfile with a time and date as the name.

Here is the code.

local lazy_cmds = vim.api.nvim_create_augroup('lazy_cmds', {clear = true})
local snapshot_dir = vim.fn.stdpath('data') .. '/plugin-snapshot'
local lockfile = vim.fn.stdpath('config') .. '/lazy-lock.json'

vim.api.nvim_create_user_command(
  'BrowseSnapshots',
  'edit ' .. snapshot_dir,
  {}
)

vim.api.nvim_create_autocmd('User', {
  group = lazy_cmds,
  pattern = 'LazyUpdatePre',
  desc = 'Backup lazy.nvim lockfile',
  callback = function(event)
    vim.fn.mkdir(snapshot_dir, 'p')
    local snapshot = snapshot_dir .. os.date('/%Y-%m-%dT%H:%M:%S.json')

    vim.loop.fs_copyfile(lockfile, snapshot)
  end,
})

If something goes wrong I use the command :BrowseSnapshots to search for the latest lockfile. I usually just grab the commit of the plugin that broke my config, then copy it to the current lockfile. After that, I use the restore command with the name of the plugin.

:Lazy restore some-plugin

If something went really really bad, I would just copy the whole backup and replace the current lockfile.

Conclusion

Is important to be prepared in case a plugin makes our editor unusable. Fortunaly lazy.nvim gives us convenient tools to recover from a bad state. We can use the interface to revert a plugin to a recent version, or we can use the lockfile to revert everything to a previous working state. So there is always a way to have Neovim with a working config.

Thank you for your time. If you find this article useful and want to support my efforts, consider leaving a tip in ko-fi.com/vonheikemen.

Packer.nvim: how to recover from a bad plugin update

Heiker — Sun, 30 Jul 2023 02:25:33 +0000

Neovim's plugin ecosystem moves fast. Sometimes this is great because we get new features. Other times... things break. Having your editor in an unusable state is not fun. But we can recover from that. In going tell you how to use packer.nvim to take your editor back to a good state.

The tools

In packer.nvim there is a thing called a snapshot. This is a JSON file that contains the commit hash of every plugin installed.

To manage the snapshot files packer.nvim offers these commands:

PackerSnapshot {name}:

Creates the snapshot file. The first argument of this command the name of the file.

PackerSnapshotRollback {name} [{plugin}]:

Reverts the plugins back to the commit specified by a snapshot. {name} must be the name of snapshot file. If you provide the argument {plugin} then only that plugin will be restored.

PackerSnapshotDelete {name}

Deletes the snapshot file with {name}.

Our first step

We can't go back to a good state if we don't have snapshot of that.

So the first thing we should do is take a snapshot of our plugins when everything is good. If your editor is working fine right now, you should execute this command.

:PackerSnapshot stable

You could even add a date format to the name. Maybe add month and year.

:PackerSnapshot stable-07-2023

In case of emergency...

What to do when things go wrong? Rollback. Execute the command to revert all your plugins to the state of the stable snapshot.

:PackerSnapshotRollback stable

And remember, you can specify which plugin you want to restore. Something like this would work.

:PackerSnapshotRollback stable nvim-treesitter

Worst case scenario

If your Neovim config breaks before it loads packer.nvim then you'll have to source it yourself.

If your packer config lives in its own lua module, navigate to that file and execute this command

:source %

If you can't execute your packer config without triggering an error, you'll have to go to the place where you have the require('packer').startup block, select the whole thing, then execute this command.

:'<,'>source

Once packer is loaded you can use the rollback command.

Make it convenient

Snapshot are great and all but we can make them better.

We can make a command that creates a snapshot before an update. And make another command that restores the most recent snapshot.

Here is the code.

local last_snapshot = vim.fn.stdpath('data') .. '/last-snapshot-date'

vim.api.nvim_create_user_command(
  'PluginUpdate',
  function()
    local packer = require('packer')
    local name = vim.fn.strftime('%Y-%m-%d@%H:%M:%S')

    packer.snapshot(name)
    vim.fn.writefile({name}, last_snapshot)

    local timer = vim.loop.new_timer()
    local wait_ms = 1000

    timer:start(wait_ms, 0, function()
      timer:stop()
      timer:close()
      packer.sync()
    end)
  end,
  {}
)

vim.api.nvim_create_user_command(
  'PluginRestore',
  function()
    local ok, name = pcall(vim.fn.readfile, last_snapshot, 1)
    if not ok then return end

    require('packer').rollback(name[1])
  end,
  {}
)

With this in your config you will use :PluginUpdate instead of :PackerSync. And if there is a bad update you can use :PluginRestore to go back to the previous state.

How to keep Neovim from breaking

Here is my advice.

Use a stable release. Avoid nightly versions if you can.
Don't update your plugins daily. Stop it.
Update your plugins only on the weekends when you have free time.

Conclusion

Neovim plugins change all the time. They update frecuently and things can break. That's why we need to learn how to deal with this situation. If a plugins breaks our editor, we can go back to a working state using packer.nvim's snapshots.

Thank you for your time. If you find this article useful and want to support my efforts, consider leaving a tip in ko-fi.com/vonheikemen.

How to survive without multiple cursors in vim

Heiker — Sat, 04 Feb 2023 13:28:54 +0000

Pueden leer la versión en español aquí.

Yes, multiple cursors are magical. They are convenient, easy to use and every modern editor has them. Now vim on the other hand doesn't have this feature. It's fine. We can be happy without them. Well... I can and I'm going to tell you how.

We'll go throught a few scenarios where multiple cursors can be useful and I'll tell you what alternatives we have in vim.

Replace word under the cursor

In vim we begin this process by searching the word under the cursor, for this we press the * key. Then we press the sequence cgn to replace the next match. If we want to repeat this action we press the . key. If we want to ignore a match we move to the next with n.

We can make this process a lot more convenient by making a keybinding.

nnoremap <leader>j *``cgn

With this we can use the leader key + j to replace the word under the cursor. We can navigate to other matches with n or N, then use the . key when we want to replace the text.

See in asciinema.

Rename a variable

Maybe the thing we want to change is a variable in our code, in this case we only need to change the valid references. Things get complicated here. Since vim isn't an IDE this kind of features are not available out of the box. But it doesn't mean is impossible, we can still do it, there are plugins that allow us to use LSP servers. It just so happens that rename variables is one the things an LSP server can do.

I use neovim btw, not vim. I just need something like this in my config.

lua require('lspconfig').ts_ls.setup({})

nnoremap <F2> <cmd>lua vim.lsp.buf.rename()<cr>

Here I'm using nvim-lspconfig to configure tsserver. Then I create the keybinding <F2> to rename the variable under the cursor.

See in asciinema.

If you use vim you can try out one these plugins:

Replace a selection

So maybe the thing we want to change is not a word, maybe is a sentence or an html attribute. For this we don't have a built-in tool, we need to implement something ourselves. So let's do that.

First thing we should do is add the current selection to the "search register".

let @/=escape(@", '/')

Here we take the text inside the " register, where our selection is stored, and put it in the / register.

The next step would be to delete the selection and enter insert mode. We use this sequence.

"_cgn

With "_ we tell vim that our next operation should store text in the _ register. With cgn we replace the closest match to our search.

If we put the pieces together in a keybinding, we get this.

xnoremap <leader>j y<cmd>let @/=escape(@", '/')<cr>"_cgn

But this command doesn't handle newlines. It won't work with selection with multiple lines. But we can handle that.

xnoremap <leader>j y<cmd>substitute(escape(@", '/'), '\n', '\\n', 'g')<cr>"_cgn

Now here we use the substitute function to replace the newline character with \n, this way our search term will always be one line.

How do we use this? Same way we did with the previous keybinding <leader>j in the section "Replace word under the cursor". But here we must first enter visual mode and select something. Everything else works the same, if we want to replace we use the . key, then we move to the next match with n.

Add text to the beginning of a list

Let's say we have a list of words and we want to convert them to an ordered list in markdown.

Want to turn this.

volar
html
cssls

Into this.

1. volar
1. html
1. cssls

In vim we have a mode called Visual Block, when in this mode we can add text to each line selected if we go to insert mode using I or A. After you added the text and exit insert mode vim will repeat the action on every line.

Let's go step by step how to use this feature.

See in asciinema.

We go to the first character in the line.
Press Ctrl + v to enter visual block mode.
Select the lines we want to change.
Press I to place the cursor at the beginning of the selection.
Add the text.
Press Esc.

Append to the end of a list

We can do that too. The steps are almost identical to the previous section, the only difference is we need to extend the selection until the end of the line.

Let's add something to the previous example.

Okay, we have our ordered list but now we want to append (is supported) to the end of each item.

See in asciinema.

We go to the first character in the line.
Press Ctrl + v to enter visual block mode.
Select the lines we want to change.
Expand the selection to the end of the line using $.
Press A to place the cursor at the end of the selection.
Add the text.
Press Esc.

Repeat movements

Visual block mode can be useful but is very limited. We can only add text in one place. What do we do in more complex scenarios? We use macros. A macro is a piece of text that describes a sequence of keypresses. We can "record" a macro and repeat the sequence as many times as we want.

How do we use macros? We need to pick a register so the first step is to press q followed by a letter. Then we go and do whatever actions we want. We stop recording the macro by pressing q again. To repeat these actions we press @ followed by the register we chose in the first step.

Example time.

We have this list.

volar
html
cssls
eslint

And we want to turn it into an ordered list of links.

1. [volar](http://localhost/how-to-configure-volar-lsp)
1. [html](http://localhost/how-to-configure-html-lsp)
1. [cssls](http://localhost/how-to-configure-cssls-lsp)
1. [eslint](http://localhost/how-to-configure-eslint-lsp)

Notice here we need to add text to the beginning and the end of the list. Additionally, we need to copy the item in the middle of the link.

What do we do? We record a macro, modify the first item then repeat the macro to convert the rest of the list. These are the steps.

Record the macro in the register i. Press qi.
Modify the first item.
We stop recording the macro by pressing q again.
We repeat the macro three times using 3@i.

See in asciinema.

When we apply a macro using a count we need to consider the position of the cursor. In this particular case I begin the macro by pressing 0, to make sure the cursor is at the beginning of the line. Then at the very end of the macro I press j, so the last movement can place the cursor in the next line.

Apply macro in specific lines

Another interesting way to apply a macro is by using the g command. With it we can begin a search and then execute a command in each line there is a match. In our case we want to apply a macro, we can do that with the command normal @i (where i can be any register).

Say we want to look for every line with the word vim then apply a macro. We do this.

:g/vim/normal @i

Now, you might want to inspect the result of the search before doing anything you'll regret. If you omit the last section with the command then :g will just print the lines.

:g/vim/

If everything looks okay then add the normal @i bit.

Apply a macro in a selection

We don't have to use the g command. The normal commands supports ranges, this means we can select any amount of lines then execute this.

'<,'>normal @i

Note: Don't worry about writing '<,'>, vim will add that for you when you go from visual mode to command mode.

That command will execute the macro in each line of the selection. Keep in mind the cursor will be placed at the beginning of the line automatically.

Search selection and apply macro

Yet another alternative to the g command. Because maybe we don't want to make a regular expresion to search. Most of the time I just want to select something, search it, then apply a macro. We already know how to do all those things, let's just put the pieces together.

Remember this guy?

y<cmd>let @/=substitute(escape(@", '/'), '\n', '\\n', 'g')<cr>

Is the thing we use to search the current selection. After this sequence we need to begin the macro. So we will add this.

gvqi

Since we lose the selection when pressing y we need to reselect everything, so we use gv. Then qi just begins to record the macro in the register i.

Now everything together.

xnoremap <leader>i y<cmd>let @/=substitute(escape(@", '/'), '\n', '\\n', 'g')<cr>gvqi

The story is not over yet. We need to apply the macro in each match. We will use gn to navigate to the match and select it. Once the cursor is in the match we apply the macro with @i. We are not doing that manually, no, we are going to create a keybinding.

nnoremap <F8> gn@i

Story time.

A few months ago I was trying this plugin manager, packer.nvim. I had something like this in my configuration.

require('packer').startup(function(use)
  use({
    'nvim-lualine/lualine.nvim',
    config = function() require('plugins.lualine') end,
  })
  use({
    'akinsho/bufferline.nvim',
    config = function() require('plugins.bufferline') end,
  })
  use({
    'lukas-reineke/indent-blankline.nvim',
    config = function() require('plugins.indent-blankline') end,
  })
end)

It bothered me that I had to repeat function() require... for each plugin. And yes, it's packer thing. They do weird stuff with functions. Anyway, I looked around in a few places and found a way to reduce the boilerplate. I wrote this function.

local function load(name)
  return string.format([[pcall(require, 'plugins.%s')]], name)
end

And with it I could write the config option like this.

config = load('lualine')

Now it's refactor time. I had to change each config option and this is how I did it.

See in asciinema.

I select the pattern I want to search. Go to visual mode and select config =.
I start recording the macro using <leader>i.
I replace the old function with load.
End the macro by pressing q.
Press n to go to the next match.
Press <F8> to apply the macro.

The Good Old Search and Replace

Sometimes a simple tool can do the job.

So vim has the substitute command. This is the syntax.

%s/<pattern>/<replacement>/g

In here % is a range, it means the current buffer. Basically, search the entire buffer. The s is the actual command, 'cause we don't need to type substitute. <pattern> is the regular expression we want to search. <replacement> is the new text. And g is a flag, it tells vim to search the entire line. And notice that each item is separated by /, we could use other characters (like #) if we wanted to.

Say want to change the word config with setup. We just do this.

%s/config/setup/g

It wasn't that difficult. We don't need to know regular expressions to use substitute.

Fighting Kirby

Okay. But there is something you should learn about regular expressions. Is just one simple trick, I swear.

What's this fighting Kirby deal? Is a way to remember this.

\(.*\)

I learned this from ThePrimeagen.

With this pattern we can create a "group". Groups can capture the text in the search pattern, and we can reuse that text in the replacement pattern.

Consider this pattern.

%s/`\(.*\)`/[\1](#how-to-configure-\1-lsp)

Here we capture the text that's surrounded by backticks. Then we reference that text using \1 and the replacement pattern. Here's a demo.

See in asciinema.

This demo shows how neovim makes a live preview, showing me the effects of the command in realtime. And yes, because of this feature I think search and replace is a decent alternative to multiple cursors.

If you liked the fighting Kirby consider making a keybinding for it.

cnoremap <F2> \(.*\)

This way you can press <F2> in command mode and it'll type it for you.

Conclusion

You are ready. You can go out to the world and be productive in vim. I can't guarantee your happiness but you will survive. And its okay if you think multiple cursors are superior to all of this. Doesn't matter, now you can live without them when using vim.

Thank you for your time. If you find this article useful and want to support my efforts, consider leaving a tip in ko-fi.com/vonheikemen.

Cómo sobrevivir sin cursores múltiples en vim

Heiker — Sat, 04 Feb 2023 13:27:29 +0000

Sí, los cursores múltiples son mágicos. Son convenientes, fácil de usar y están presente en muchos editores modernos. Para bien o para mal, vim no los tiene. Pero está bien, podemos ser felices sin ellos. Bueno... yo puedo y voy decirles cómo.

Vamos a repasar las situaciones donde podríamos usar cursores múltiples y veremos qué alternativas tenemos en vim.

Reemplazar palabra debajo del cursor

En vim debemos comenzar el proceso buscando la palabra debajo del cursor, para esto presionamos *. Luego presionamos cgn para reemplazar la próxima ocurrencia. Si queremos repetir la acción presionamos ., sí, el punto. Si no queremos reemplazar la ocurrencia actual podemos ignorarla y pasar a la siguiente presionando n.

Podemos hacer este proceso más rápido si creamos un atajo de teclado que agrupe los primeros dos pasos.

nnoremap <leader>j *``cgn

Con este atajo podremos utilizar la tecla líder + j para reemplazar la palabra actual, luego podremos navegar entre cada ocurrencia de la palabra y usar . para reemplazar el texto.

Ver en asciinema.

Cambiar una variable

Puede ser que la palabra que quieren reemplazar es una variable en su código, en este caso sería ideal que el editor sólo reemplace las referencias que son válidas. Aquí la solución puede ser un poco más complicada. Como saben vim no es un IDE, este tipo de funcionalidad no está habilitada por defecto. Pero no es imposible, existen plugins que nos permiten usar servidores LSP. Resulta que renombrar variables es una de esas funcionalidades que podemos obtener con un servidor LSP.

Personalmente uso Neovim y no vim como tal. En mi caso sólo necesito algo como esto.

lua require('lspconfig').ts_ls.setup({})

nnoremap <F2> <cmd>lua vim.lsp.buf.rename()<cr>

Aquí uso nvim-lspconfig para configurar tsserver. Y creo el atajo <F2> para renombrar variables.

Ver en asciinema.

Si ustedes usan vim pueden probar estos plugins:

Reemplazar selección

Tal vez el texto que queremos reemplazar no es una palabra, tal vez es una oración o un atributo de html. En este caso no tenemos una funcionalidad nativa que nos ayude pero podemos implementar nuestra propia solución.

Lo primero que haremos será colocar la selección actual en el "registro de búsqueda" de vim.

let @/=escape(@", '/')

Aquí tomamos el registro " que contiene la selección más reciente, nos aseguramos de escapar el caracter / para que no ocurra un conflicto en nuestra búsqueda, finalmente asignamos el resultado al registro /.

Luego debemos borrar toda la selección e ir al modo de inserción. Esto lo logramos con esta secuencia.

"_cgn

Con "_ le decimos a vim que queremos usar el registro _ para nuestra siguiente operación. cgn es para reemplazar la primera ocurrencia de una búsqueda.

Si juntamos estas piezas en un atajo tendremos esto.

xnoremap <leader>j y<cmd>let @/=escape(@", '/')<cr>"_cgn

Pero esta solución sólo funciona con búsquedas de una línea. Si por alguna razón quieren reemplazar una selección de múltiples líneas deben hacer esto.

xnoremap <leader>j y<cmd>substitute(escape(@", '/'), '\n', '\\n', 'g')<cr>"_cgn

Aquí usamos la función substitute para reemplazar el salto de línea con \n, así técnicamente nuestra búsqueda siempre será de una línea.

¿Cómo usamos esto? De la misma forma que usamos el atajo <leader>j en la sección "reemplazar palabra debajo del cursor". La diferencia es que en este caso primero debemos ir a modo visual para seleccionar el texto. Luego podremos repetir la acción usando . o podemos movernos a la siguiente ocurrencia usando n.

Añadir texto al inicio de una lista

Digamos que tenemos una lista de palabras y queremos convertirla en una lista ordenada en markdown.

Queremos transformar esto.

volar
html
cssls

En esto.

1. volar
1. html
1. cssls

En vim tenemos un modo llamado "visual block", cuando estamos en este modo tenemos la posibilidad de agregar texto a cada línea de la selección si vamos a modo de inserción usando I o A. Luego de insertar el texto en la primera línea vim procede a repetir esta acción en el resto de las líneas seleccionadas.

Vamos a revisar paso a paso lo que debemos hacer.

Ver en asciinema.

Vamos al primer caracter de la primera línea.
Presionamos Ctrl + v para ir al modo "visual block".
Seleccionamos las líneas que queremos cambiar.
Presionamos I para colocar el cursor al inicio de la selección.
Agregamos el texto que queremos.
Presionamos Esc.

Añadir texto al final de una lista

Sí. También podemos modificar el final de la línea. El proceso es casi idéntico, con la diferencia de aquí debemos expandir la selección hacia el final de la línea.

Digamos que tenemos nuestra lista ordenada pero ahora queremos agregar el texto (is supported) al final de cada línea.

Ver en asciinema.

Vamos al primer caracter de la primera línea.
Presionamos Ctrl + v para ir al modo "visual block".
Seleccionamos las líneas que queremos cambiar.
Expandimos la selección hacia el final de la línea presionando $.
Presionamos A para colocar el cursor al final de la primera línea.
Agregamos el texto que queremos.
Presionamos Esc.

Repetir un movimientos

El modo visual block puede ser útil en muchas situaciones pero es limitado. Sólo puede agregar texto en un lugar. ¿Qué hacemos cuando queremos hacer modificaciones complejas? La respuesta: macros. Un macro es una cadena de texto que describe una secuencia de teclas. Podemos "grabar" un macro y repetirlo tantas veces sea necesario.

¿Cómo usamos un macro? Primero debemos elegir un registro. Algo así como una etiqueta para nuestro macro. Presionamos q seguido de la letra de nuestro registro. Luego ejecutamos las modificaciones que queremos. Finalmente presionamos q para terminar de grabar el macro. Para repetir el macro debemos presionar @ seguido de la letra que elegimos en el primer paso.

Vamos con un ejemplo.

Tenemos esta lista.

volar
html
cssls
eslint

Y queremos convertirlo en una lista ordenada de enlaces.

1. [volar](http://localhost/how-to-configure-volar-lsp)
1. [html](http://localhost/how-to-configure-html-lsp)
1. [cssls](http://localhost/how-to-configure-cssls-lsp)
1. [eslint](http://localhost/how-to-configure-eslint-lsp)

Noten que aquí necesitamos añadir texto al inicio y final de cada línea. También tenemos que copiar el nombre de cada item y colocarlo en el enlace.

Lo que haremos será convertir el primer item y repetir el proceso usando un macro. Estos son los pasos.

Grabamos el macro en el registro i. Presionamos qi.
Modificamos el primer item.
Finalizamos la grabación del macro presionando q nuevamente.
Repetimos el macro tres veces presionando 3@i.

Ver en asciinema.

Cuando aplicamos un macro de esta manera, con repeticiones automáticas, debemos tener en cuenta la posición del cursor. En este caso particular el primer atajo que utilicé al comenzar a grabar el macro fue 0 y terminé presionando j. Con esto me aseguro de que en cada repetición el cursor esté en el primer caracter de la línea, y justo antes de terminar el macro muevo el cursor a la línea que está debajo.

Aplicar un macro en líneas específicas

Otra forma interesante de aplicar un macro es con el comando g. Este comando ejecuta una búsqueda y nos da la oportunidad de ejecutar otro comando en las líneas donde hay una ocurrencia. En nuestro caso lo que queremos hacer después de la búsqueda es ejecutar un macro, para eso usamos el comando normal @i (donde i puede ser cualquier registro).

Digamos que queremos buscar todas las líneas con la palabra vim y ejecutar un macro. Podemos hacer algo así.

:g/vim/normal @i

Si quieren asegurarse de que su búsqueda tiene los resultados esperados pueden omitir la sección que va después de la búsqueda.

:g/vim/

Si todo está bien agregamos normal @i.

Aplicar un macro en una selección

No estamos obligados a usar el comando g, podemos utilizar el comando normal @i sobre una selección ejecutando este comando.

'<,'>normal @i

Nota: No se preocupen por recordar la sintaxis '<,'>, vim lo agregará automáticamente cuando pasamos de modo visual a modo de comando.

Esto ejecutará el macro en i sobre cada línea de la selección. Deben tener en cuenta que cada macro comenzará con el cursor al principio de la línea.

Buscar patrón y ejecutar un macro

Esta es una alternativa al comando g. Porque tal vez no se sienten cómodos usando expresiones regulares. Los entiendo. La mayoría de las veces lo que quiero hacer es seleccionar un pedazo de texto y aplicar un macro sobre algunas ocurrencias. Ya vimos cómo buscar una selección, podemos aplicar este conocimiento para manipular la posición del cursor.

¿Recuerdan esto?

y<cmd>let @/=substitute(escape(@", '/'), '\n', '\\n', 'g')<cr>

Esta es la secuencia que usamos para colocar la selección actual en el registro de búsqueda. Todo lo que tenemos que hacer es iniciar la grabación del macro después de esta función. Así.

gvqi

Con gv vim vuelve a resaltar la selección anterior, porque recuerden que perdemos la selección luego de presionar y. Después con qi comienza la grabación del macro en el registro i.

Si juntamos todo esto en un atajo obtenemos:

xnoremap <leader>i y<cmd>let @/=substitute(escape(@", '/'), '\n', '\\n', 'g')<cr>gvqi

La historia no termina aquí, ahora tenemos que aplicar el macro en las ocurrencias de nuestra selección. Usaremos gn para seleccionar la siguiente ocurrencia y ejecutar el macro.

nnoremap <F8> gn@i

Vamos con un ejemplo de la vida real.

Hace unos meses estaba probando packer.nvim, un manejador de plugins. En mi configuración tenía este código.

require('packer').startup(function(use)
  use({
    'nvim-lualine/lualine.nvim',
    config = function() require('plugins.lualine') end,
  })
  use({
    'akinsho/bufferline.nvim',
    config = function() require('plugins.bufferline') end,
  })
  use({
    'lukas-reineke/indent-blankline.nvim',
    config = function() require('plugins.indent-blankline') end,
  })
end)

Me molestaba tener que repetir function() require... por cada plugin. Busqué por internet y encontré la manera de reducir el código repetido. Escribí esta función.

local function load(name)
  return string.format([[pcall(require, 'plugins.%s')]], name)
end

Con esta función puedo reducir el código necesario para utilizar config. Puedo hacer esto.

config = load('lualine')

Lo que queda es reemplazar la propiedad config de cada plugin.

Ver en asciinema.

Seleccionamos el patrón que vamos a buscar. En este caso config =.
Comenzamos a grabar el macro usando el atajo <leader>i.
Hacemos las operaciones necesarias.
Terminamos de grabar el macro presionando q.
Presionamos n para ir al siguiente punto.
Repetimos el macro con el atajo <F8>.

Búsqueda y reemplazo

Porque muchas veces no necesitamos herramientas complicadas.

En vim podemos usar el comando substitute. Esta es la sintaxis.

%s/<patrón>/<reemplazo>/g

Aquí % es el "rango" de la búsqueda, si usamos % quiere decir que queremos buscar en todo el archivo. s es el comando, no tenemos que escribir el nombre completo substitute. <patrón> es la expresión regular que queremos buscar. <reemplazo> es el texto queremos usar. g es un "flag" que le indica a vim que debe buscar en toda la línea. Noten que cada una de estas secciones está separada por /, pero podemos usar otros caracteres.

Vamos con un ejemplo. Digamos que queremos cambiar la palabra config por setup. No necesitamos conocer nada de expresiones regulares, sólo colocamos las palabras en el lugar correcto.

%s/config/setup/g

El Kirby tuerto

Okey. Si hay algo que les recomiendo aprender de expresiones regulares en vim son los "grupos". Incluso un pequeño truco puede traer muchos beneficios.

¿Qué es eso del kirby tuerto? Es la forma de recordar esta sintaxis.

\(.*\)

Este truco lo aprendí de ThePrimeagen.

Con este patrón podemos capturar un pedazo de texto y crear un "grupo". Una vez que tenemos un grupo podremos utilizar el texto en nuestro texto de reemplazo.

Consideren este comando.

%s/`\(.*\)`/[\1](#how-to-configure-\1-lsp)

Aquí capturamos todo el texto que se encuentre entre comillas. Luego utilizamos el texto del grupo con el patrón \1 en el texto de reemplazo. Aquí tienen un demo.

Ver en asciinema.

En este demo se puede observar en tiempo real el efecto del comando mientras escribo. Tengo entendido que esto es único de neovim (puedo estar equivocado). Pero sí, con este efecto en tiempo real el comando substitute puede ser una buena alternativa (en algunos casos) a los cursores múltiples.

Si les preocupa no poder recordar la sintaxis del Kirby tuerto consideren crear un atajo.

cnoremap <F2> \(.*\)

De esta manera sólo tienen que presionar <F2> para crear el grupo.

Conclusión

Ya están listos. Pueden salir al mundo y ser productivos con vim. No puedo garantizar que serán felices pero sobrevivirán. Está bien si todavía consideran que los cursores múltiples es la mejor herramienta. No importa, pueden vivir sin ellos mientras están en vim.

Gracias por su tiempo. Si este artículo les pareció útil y quieren apoyar mis esfuerzos para crear más contenido pueden dejar una propina en ko-fi.com/vonheikemen.

How to install AstroNvim without overriding your existing Neovim configuration

Heiker — Sat, 24 Sep 2022 14:57:24 +0000

I've notice a lot of people out there trying out AstroNvim, and there are a few that want to use it in order to learn about Neovim. I think this is great but... what isn't so great is the installation process taking over your entire Neovim configuration. Wouldn't it be better if you could use AstroNvim for serious work while you slowly create your own Neovim configuration on the side? We can do this. It is possible and I'll tell you how.

The new environment

If you are using Neovim v0.9 or greater, you can setup an environment variable called NVIM_APPNAME. This variable needs a name. Neovim will use this name to look for a different config folder.

If you startup Neovim like this

NVIM_APPNAME=astronvim nvim

Then Neovim will search your config in ~/.config/astronvim if you are on linux or mac. In windows it will look for ~/AppData/Local/astronvim.

Basically the only thing you need to do is create an alias to start Neovim with a different "app name." In linux, using bash or something similar, you would add this in the config file of your shell.

alias code="NVIM_APPNAME=astronvim nvim"

The following is the original content of this article. It will only be useful to you if you are using Neovim v0.8 or lower, and you plan to use AstroNvim v2 or lower.

Requirements

Before you go any further make sure you have the latest stable version of Neovim installed. You can download it from the releases page in github.

Also, you need to know how to enter "ex-commands" inside Neovim, we'll be using a lot of those.

The new path

First thing you want to do is decide where you want to install AstroNvim. In order to make this configuration portable I like to use a folder structure similar to what Neovim uses. This way I can get the paths I need by calling Neovim's builtin functions.

So, open Neovim and execute this command.

:echo stdpath('data')

This will show Neovim's data folder. In linux and mac it'll show something like this.

/home/dev/.local/share/nvim

In windows (I believe) it returns this.

C:\Users\dev\AppData\Local\nvim-data

We don't want that. Replace nvim with astronvim, like this.

:echo substitute(stdpath('data'), '\(.*\)\zsnvim', 'astronvim', '')

That path, that is where we're going to store (almost) everything related to AstroNvim. Create that folder in your file system.

Next, clone AstroNvim inside the folder you just created, and rename the repository folder to core.

git clone https://github.com/AstroNvim/AstroNvim /path/to/astronvim/core

The entrypoint

We can't use AstroNvim's init.lua, we need to make a new one. We have to make sure our personal Neovim configuration doesn't have any conflict with AstroNvim.

This is the part where we create a configuration folder for AstroNvim. Just like before we are going to follow Neovim's pattern. Check where Neovim stores the configuration using :echo stdpath('config'), and then just replace nvim with astronvim.

Inside this config folder you need to create a lua script. You can call it anything you like but for the purpose of this tutorial I will call it entry.lua.

In entry.lua we are going to mess around with a fair amount of variables.

All the code for entry.lua will be in this Github gist.

Define custom directories

local path_sep = vim.loop.os_uname().version:match('Windows') and '\\' or '/'
local join = function(...) return table.concat({...}, path_sep) end
local getpath = function(arg)
  local path = vim.fn.stdpath(arg)
  return vim.fn.substitute(path, [[\(.*\)\zsnvim]], 'astronvim', '')
end

local data_path = getpath('data')
local astro_config = join(data_path, 'core')
local user_path = getpath('config')

In the first line we figure out what path separator we need. The second line we create a join function so we can create paths using the correct separator. In the third line we use our little stdpath + substitute trick in a function, this will return the paths we need in the new AstroNvim setup.

In data_path we will store everything related to AstroNvim we don't want to manage ourselves. astro_config is the place where we downloaded AstroNvim. And user_path is the directory where we configure AstroNvim.

Setup environment

We are going to do is modify environment variables. Yes. We have to. Changes are only going to take effect in Neovim's process, don't worry. Here's how we do it.

vim.env.XDG_DATA_HOME = data_path
vim.env.XDG_CACHE_HOME = join(data_path, 'cache')
vim.env.XDG_STATE_HOME = join(data_path, 'state')

This will make Neovim change the return value of stdpath, after this it'll point to our custom paths.

Runtime files

Now we go for the runtimepath. This is a Neovim option that specifies what directories it should consider when searching for configuration files. We want to take full control of this, tell Neovim exactly what directories it can use.

vim.opt.runtimepath = {
  user_path,
  astro_config,
  vim.env.VIMRUNTIME,
  join(astro_config, 'after'),
  join(user_path, 'after'),
}

Our brand new runtimepath will be AstroNvim's config, AstroNvim itself and Neovim's own runtime files.

Plugin directories

We also need to take care of plugins. For this we modify packpath. With this option we tell Neovim where it can find "packages". A package in Neovim is a folder that contains one or more plugins, see :help packages for more details.

vim.opt.packpath = {
  join(data_path, 'nvim', 'site'),
  user_path,
  vim.env.VIMRUNTIME
}

Here the first path is where the plugin manager will download plugins. The second path is our AstroNvim config (just in case you want to add plugins there). Third is where Neovim's first party plugin are.

AstroNvim home

astronvim_installation = {home = astro_config}

With this we make sure the command AstroUpdate can find the path where we downloaded AstroNvim.

Sourcing

The last step. All we have to do now is execute AstroNvim's init.lua.

local execute = loadfile(join(astro_config, 'init.lua'))

if not execute then
  vim.api.nvim_err_writeln("Could not load AstroNvim's init.lua")
  return
end

execute()

A new command

In order to use the new entrypoint I recommend using Neovim with the -u flag.

nvim -u /path/to/astronvim/entry.lua

Assuming you are using bash or zsh as your shell, you can create an alias.

alias code='nvim -u /path/to/astronvim/entry.lua'

Or make a new executable script and add it to your PATH.

#! /usr/bin/env sh

nvim -u /path/to/astronvim/entry.lua "$@"

Either way you should be able to call AstroNvim with this new command, and also call Neovim with just nvim.

How do we customize AstroNvim?

In the same folder where we have entry.lua you create a directory called lua, and inside lua create another folder called user. And then inside user you create a file called init.lua

Inside /path/to/astronvim/lua/user/init.lua you need to create a lua table, add your config and then return that table. Like this.

local user = {plugins = {}}

user.colorscheme = 'tokyonight-night'

user.plugins.init = {
  {'folke/tokyonight.nvim'}
}

return user

Here I add a new plugin (a colorscheme) and set a new colorscheme.

I highly recommend that you get familiar with the syntax of lua tables. Learn how to create and modify them. It'll make your life so much easier. And don't forget to read AstroNvim's documentation.

Conclusion

This is it. You made it. Now you have the tools to use AstroNvim and also keep your own configuration for Neovim.

Thank you for your time. If you find this article useful and want to support my efforts, consider leaving a tip in ko-fi.com/vonheikemen.

Neovim: Plugins to get started

Heiker — Thu, 08 Sep 2022 12:53:52 +0000

Pueden leer la versión en español aquí.

It happens very often that people start using Neovim but they miss some features that other text editors have. Listing open files in tabs, a file tree explorer, show the current git branch, and so on. So here I want to show you a set of plugins that will help you add those common features to Neovim.

The only thing I will not cover here is autocompletion. Smart code completion usually involves integrating with external tools. It means there is a fair amount of details that need to be explained, so there is dedicated post for that: Getting started with Neovim's LSP client.

All the configuration shown in this post will be in this repository: nvim-starter - branch: 02-opinionated.

Requirements

If you're completely new to Neovim I recommend learning lua's syntax. If you don't want to learn everything at least have a reference to know what is valid. All the plugins I'll share here are configured using lua.

If you haven't created a configuration for Neovim, do it now. Here is a guide with everything you need to know: Build your first Neovim configuration in lua.

You'll need Neovim's latest stable version. You can download it from the release section in github. From now on I'll assume you are using Neovim v0.9.5 or greater.

How do we install plugins?

First thing we should know is how to install a plugin manually. Turns out we only need to download them in a specific location and Neovim will be able to use it. We can list all the available directories using this command.

:set packpath?

That will show a comma separated list of paths.

We can get something better using a little bit of lua.

:lua vim.tbl_map(print, vim.opt.packpath:get())

This one will show the same list but now every path will be in its own line.

In one of those directories we have to create another directory called pack. Inside pack we create the directory that will hold our plugins. The structure has to be something like this:

pack
└── plugins-from-github
    ├── opt
    │   ├── [plugin 1]
    │   └── [plugin 2]
    └── start
        └── [plugin 3]

Plugins in opt will only be loaded if we execute the command :packadd. The plugins in start will be loaded automatically during Neovim's startup process.

So let's assume we have this path in our packpath.

/home/dev/.local/share/nvim/site

We want to install plugins there, what do we do? Create a pack directory. Then create another directory with any name. Let's use the name github because why not? So the full path for our plugins will be this.

/home/dev/.local/share/nvim/site/pack/github

So to install a plugin like mini.nvim and have it load automatically, we should place it here.

/home/dev/.local/share/nvim/site/pack/github/start/mini.nvim

And that's it.

To know more about packages in Neovim read the help page.

:help packages

Plugin manager

But of course we don't have to download plugins manually, we can use a plugin manager that handles everything for us.

At the moment these are the most popular plugin managers in the Neovim ecosystem.

Remember to read carefully the instructions of the plugin manager you choose.

Plugins

Tokyonight

Github: folke/tokyonight.nvim

Because of course the first thing you have to do is change the default theme. We can achieve this by using the command colorscheme followed by the name of the theme.

In lua we can call vim commands using vim.cmd. So to apply the theme we have to do this.

vim.cmd('colorscheme name-of-theme')

This is the command we need to use tokyonight.

colorscheme tokyonight

Bufferline

Github: akinsho/bufferline.nvim

You know how other editors show a tab for each open file? Okay, that's not how it works in Neovim. For starters we call them tabpages, they are like workspaces, inside a tabpage you can open multiple windows. You can even have different working directories per tabpage. But some people prefer the "traditional" behavior and this is what bufferline does, it modifies the tabline so it can show the currently opened files.

Here we find ourselves in a situation where we need to enable the plugin explicitly. The way we do it is by executing a function called .setup() located in the "main" module of the plugin. For bufferline to work we have to add this line of code to our personal configuration.

require('bufferline').setup({})

This require function is the mechanism we use to load a lua module. The string bufferline is the name of the module itself. And .setup() is a function call, we are telling the lua interpreter we want to execute a function with the name setup.

To customize the plugin's settings you provide a "lua table" to the .setup() function. How do we figure out what settings are available? By reading the documentation.

You can find a reference to the available options in the help page.

:help bufferline-configuration

Here's an example configuration.

require('bufferline').setup({
  options = {
    mode = 'buffers',
    offsets = {
      {filetype = 'snacks_layout_box'}
    },
  }
  highlights = {
    buffer_selected = {
      italic = false
    },
    indicator_selected = {
      fg = {attribute = 'fg', highlight = 'Function'},
      italic = false
    }
  }
})

options.mode: With the value 'buffers' will tell bufferline that we want to show one tab per file.
options.offsets: Must be a list of filetypes. When one of these filetypes appears bufferline will avoid rendering a tab above the window. Here we are adding the snacks_layout_box because it'll be our file explorer. When the explorer window shows up it'll look like a side bar.
highlights: With this we can modify the colors of the components in the tab. Each section (like buffer_selected) must be the name of a component. In this example I'm using italic = false to tell bufferline I want to disable italic characters. The property fg is the one that changes the color of the characters. In here I'm telling it to use the same highlight color my colorscheme uses for functions. If you want to see more details about highlights checkout :help bufferline-highlights.

Is worth noting bufferline also offers handful of user commands to navigate between files and some other stuff. But the one I've used the most is BufferLinePick. This will allow us to select a visible tab without using the mouse. And we can use it in a keymap for extra convenience.

vim.keymap.set('n', 'gt', '<cmd>BufferLinePick<cr>', {})

mini.nvim

Github: nvim-mini/mini.nvim

Website: nvim-mini.org

mini.nvim is a collection of lua modules. This is meant to improve our experience by enhancing Neovim's builtin features or implementing new ones.

There are over 40 modules inside mini.nvim but here I'll show 7 that I find very useful.

mini.statusline

The statusline is a component of Neovim's UI. Is a line located at the bottom of each window. It usually separates the window from the message area. This is where Neovim shows information like the file name and the location of the cursor. And much like the tabline, the statusline can also be modified.

mini.statusline is an implementation of the statusline that looks a little bit better than the default. And it can also show information provided by other modules in mini.nvim.

Just like bufferline has a .setup() every module in mini.nvim follows the same convention. This is enough to make the plugin work.

require('mini.statusline').setup({})

If you want to know more details about a module in mini.nvim use the :help command and the name of the module.

:help mini.statusline

mini.git

mini.git can track information about the current directory if it's git repository. And also provides a user command (:Git) that allows us to use git's cli inside Neovim.

By default mini.statusline will show the current git branch if we enable mini.git.

require('mini.git').setup({})

The :Git command provided by this plugin will try integrate Neovim whenever possible. For example, :Git diff will show the output of the diff in a Neovim buffer. :Git commit will use the current Neovim instance as the editor for the commit message. To know more details read the documentation.

:help mini.git

mini.diff

mini.diff is another "git based" module. This one can show if something was deleted, added or changed in real time.

Let me share with you my personal configuration.

vim.o.signcolumn = 'yes'
require('mini.diff').setup({
  view = {
    style = 'sign',
    signs = {
      add = '▎',
      change = '▎',
      delete = '➤',
    },
  },
})

Here I set the signcolumn option to yes because I want to reserve a space in the gutter, next to the line numbers. And inside the mini.diff settings I change the "style" to sign so it can use the signcolumn to show the indicator when there is a change in the code.

mini.comment

mini.comment provides keymaps to toggle comments in a line of code. By default it provides a gc operator which we can use in normal mode. For example gci{ will toggle comments in all the lines the inside curly braces. And so anything combination that you can do with a regular operator like d or c you can do with gc. The keymap gcc will toggle only the current line.

require('mini.comment').setup({})

It is worth noting this feature mini.comment provides is now part of Neovim as of version v0.10. But Neovim's implementation is not very configurable, you can't change how it works or extend it in any way. mini.comment will work even on Neovim v0.9 and offers a few settings you can change, that includes the function used to provide the comment for the current line.

mini.notify

mini.notify is a custom implementation for vim.notify.

vim.notify is a lua function that plugin authors use to display a message to end users. The default implementation Neovim provides uses the message area. mini.notify implements a custom function so plugin notifications show up in a floating window on the corner.

require('mini.notify').setup({})

mini.clue

mini.clue will help you remember (and maybe discover) Neovim key combinations by showing them in a floating window.

Most of mini.nvim's module work just fine with their default settings but here we have to be explicit. We have to specify which key combination will trigger the floating with the clues. Here's a simple example.

local mini_clue = require('mini.clue')

mini_clue.setup({
  triggers = {
    {mode = 'n', keys = 'g'},
    {mode = 'n', keys = '<leader>'},
  },
  clues = {
    mini_clue.gen_clues.g(),
  },
})

In triggers we add the prefix of the key combination. And clues is where we place the descriptions of the keymaps if we need them.

The cool thing about mini.clue is we don't have to do anything special with our custom keymaps. If we create our keymaps with vim.keymap.set() and provide a description that will be enough for it to appear on mini.clue's floating window. For example.

-- Space as a leader key
vim.g.mapleader = ' '

vim.keymap.set('n', '<leader>w', '<cmd>write<cr>', {desc = 'Save file'})
vim.keymap.set('n', '<leader>q', '<cmd>quit<cr>', {desc = 'Close window'})

mini.clue will be able to show these keymaps in its little floating window, because we specified <leader> as a trigger in the .setup() function.

For builtin keymaps where there is no description mini.clue provides a few functions under gen_clues.

A more complete setup would look like this:

local mini_clue = require('mini.clue')

mini_clue.setup({
  window = {
    delay = 600,
    config = {
      width = 50,
    },
  },
  triggers = {
    {mode = 'n', keys = '['},
    {mode = 'n', keys = ']'},
    {mode = 'n', keys = 'g'},
    {mode = 'x', keys = 'g'},
    {mode = 'n', keys = 'z'},
    {mode = 'x', keys = 'z'},
    {mode = 'n', keys = '<C-w>'},
    {mode = 'i', keys = '<C-x>'},
    {mode = 'n', keys = '<leader>'},
    {mode = 'x', keys = '<leader>'},
  },
  clues = {
    mini_clue.gen_clues.g(),
    mini_clue.gen_clues.z(),
    mini_clue.gen_clues.windows(),
    mini_clue.gen_clues.builtin_completion(),
  },
})

Notice here we even have a window settings to control the width of the floating window, as well as the time it would take for it to appear on screen.

On to the limitations. One thing you should know is that mini.clue does not provide clues for operators. Combinations like ciw or yap can't be annotated. This is because keymaps like c, y, d are operators. A plugin simply can't hijack these operators without having weird side effects or write a non-trivial amount hacks to make it work.

mini.icons

mini.icons can be considered a multi-purpose module.

For plugin authors it provides an abstraction they can use to show icons with highlights.

For end users (like us) it provides a way to enable or disable fancy icons whenever possible. Some times a plugin will use icons but they don't offer a way to disable them. mini.icons can be used as a mechanism to enable or disable fancy icons.

require('mini.icons').setup({style = 'glyph'})

Here the style settings is the one that controls what kind of icons should be used. glyph is the default value. So having mini.icons enabled with the default settings means we want the fancy icons. Changing the style to ascii means mini.icons will use standard characters instead of symbols that may not be supported by the font you are using at the moment.

vim-repeat

Github: tpope/vim-repeat

Adds "dot repeat" support for other plugins. If you don't know, when we press the dot key (.) Neovim tries to repeat the last action we did. For example, if we delete a word using diw we can repeat that just by pressing .. With vim-repeat we can repeat actions made by plugins.

Treesitter

Github: nvim-treesitter/nvim-treesitter

So treesitter is a library that was added to Neovim, with it Neovim can read your code in the same way a compiler does, it scans the code and creates an abstract syntax tree. In other words, it turns your code into a data structure Neovim can query.

By itself treesitter doesn't do anything useful, is more like a tool for Neovim mantainers and plugin authors, they will use treesitter to implement the features everyone else will interact with. For example, inside Neovim there is an alternative mechanism to do syntax highlight, it uses treesitter to assign the highlight groups to the text of a buffer.

Now, for treesitter to actually work we need a treesitter parser. The parser is the thing that reads the code. To install a parser we use the command :TSInstall followed by the name of the language.

So to install a javascript parser we use this command.

:TSInstall javascript

When it comes to features there isn't a unified interface we can use to "enable treesitter." We have to look up the documentation of the feature we want to use and follow the instructions.

To enable the syntax highlight based on treesitter the documentation recommends using a filetype plugin or an autocommand on the FileType event. And then we call the function vim.treesitter.start(). Here's an example using an autocommand to enable the syntax highlight in javascript related filetypes.

vim.api.nvim_create_autocmd('FileType', {
  pattern = {'javascript', 'javascriptreact', 'js', 'jsx'},
  callback = function()
    vim.treesitter.start()
  end,
})

ts-enable.nvim

Github: VonHeikemen/ts-enable.nvim

Using nvim-treesitter now requires some knowledge about how Neovim works. You have to do some amount of work to enable features. Is not that bad if you are willing to install treesitter parsers manually. But it does get complicated when you want nice quality of life features, like installing parsers on demand. ts-enable.nvim is just an abstraction layer, it implements the boilerplate code needed to enable syntax highlight, code folding and indentation based on treesitter.

A basic configuration can look like this:

-- See :help ts-enable-config
vim.g.ts_enable = {
  parsers = {'lua', 'vim', 'vimdoc', 'c', 'query'},
  auto_install = true,
  highlights = true,
  indents = false,
  folds = false,
}

The idea here is that you just specify the names of the treesitter parsers you want to use and the features you want to enable. So you don't have to write any autocommands, ts-enable.nvim will take care of the details of each feature and can also install missing parsers using nvim-treesitter.

Snacks.nvim

Github: folke/snacks.nvim

Snacks.nvim is also a collection of lua modules. But this is different from mini.nvim. Snacks doesn't follow the same design as mini. A module in snacks.nvim doesn't have any self-inflicted limitation. So we could say Snacks is more ambitious than mini.

Most modules in Snacks.nvim can be enabled using a single setup function from the lua module snacks.

local Snacks = require('snacks')

Snacks.setup({
  ---
  -- This is where we write our settings
  ---
})

The snacks module is the main interface of Snacks.nvim. Everything that we interact with is inside this one lua module.

Snacks.input

Snacks.input is a custom implementation for vim.ui.input().

vim.ui.input() is a lua function that plugin authors call to get some information from the user. For example, in a file explorer when trying to rename a file it makes sense to ask the user what is the new name for the file.

Snacks.input implementation shows a floating input in the center of the screen. Instead of using the message area like the default implementation does.

This is what we do to enable it.

Snacks.setup({
  input = {
    enabled = true,
    icon = '❯',
  },
})

Snacks.picker

Snacks.picker does three things: 1) provide an interface to fuzzy find items on a list. 2) implements 50+ "pickers" out of the box. 3) provides a custom implementation for vim.ui.select().

Fuzzy finders became popular in the Neovim community because it provided a way to navigate between files in a very fast way. And the cool thing is that "fuzzy finding" is a very general idea, at its core we are just filtering a list of items. Turns out this is useful for many other use cases. That's why Snacks has 50 something pickers already built-in. We have pickers for open files, project files, undo history, keymaps, commands, color schemes... and many others.

Now, vim.ui.select() is a lua function that plugin authors use to ask the user to pick one of several options. Snacks.picker has a custom implementation that uses its fuzzy find interface.

Snacks.setup({
  picker = {
    enabled = true,
    ui_select = true,
    prompt = '❯ ',
  },
})

Configuring the picker settings in the .setup() is optional if you don't want to use the custom implementation for vim.ui.select(). All the pickers in Snacks can be used even if we don't use the main .setup() function.

How do we use these picker? The most convenient way would be to make them show up by pressing a keymap. You can start with these keymaps:

-- docs: https://github.com/folke/snacks.nvim/blob/main/docs/picker.md
vim.keymap.set('n', '<leader><space>', function() Snacks.picker('buffers') end, {desc = 'Search open files'})
vim.keymap.set('n', '<leader>ff', function() Snacks.picker('files') end, {desc = 'Search all files'})
vim.keymap.set('n', '<leader>fh', function() Snacks.picker('recent') end, {desc = 'Search file history'})
vim.keymap.set('n', '<leader>fg', function() Snacks.picker('grep') end, {desc = 'Search in project'})
vim.keymap.set('n', '<leader>fd', function() Snacks.picker('diagnostics') end, {desc = 'Search diagnostics'})
vim.keymap.set('n', '<leader>fs', function() Snacks.picker('lines') end, {desc = 'Buffer local search'})
vim.keymap.set('n', '<leader>u', function() Snacks.picker('undo') end, {desc = 'Undo history'})
vim.keymap.set('n', '<leader>/', function() Snacks.picker('pickers') end, {desc = 'Search picker'})
vim.keymap.set('n', '<leader>?', function() Snacks.picker('keymaps') end, {desc = 'Search keymaps'})

Snacks.indent

Snacks.indent adds indent guides to the buffer. So we can visualize the indentation level of a block code.

Snacks.setup({
  indent = {
    enabled = true,
    char = '▏',
  },
})

By default the current scope where the cursor is located will be highlighted, and this highlight will have an animation. If we want to disable the animation we use a global variable.

vim.g.snacks_animate = false

To be clear, this will only disable the animation. The current scope will still be highlighted.

Snacks.bigfile

This module is mostly for older Neovim versions.

We can use Snacks.bigfile to disable Neovim features when we open a "big file." Again, this is useful in older Neovim versions because the syntax highlight makes the editor slow to respond. However, in Neovim v0.11 there is an experimental asynchronous highlight enabled, which may eliminate the need for this.

Snacks.setup({
  bigfile = {
    -- Only use `bigfile` module on older Neovim versions
    enabled = vim.fn.has('nvim-0.11') == 0,
    notify = false,
    size = 1024 * 1024, -- 1MB
    setup = function(ctx)
      vim.cmd('syntax clear')
      vim.opt_local.syntax = 'OFF'
      local buffer = vim.b[ctx.buf]
      if buffer.ts_highlight then
        vim.treesitter.stop(ctx.buf)
      end
    end
  },
})

The idea here is that on files that are bigger than 1MB we disable all syntax highlight. Notice the enabled setting will be true if we are using an older version of Neovim below v0.11. So you could omit this module altogether if your Neovim version is recent enough.

Snacks.bufdelete

Snacks.bufdelete offers a few functions we can use to delete a buffer without changing the window layout.

-- docs: https://github.com/folke/snacks.nvim/blob/main/docs/bufdelete.md
vim.keymap.set('n', '<leader>bc', function()
  Snacks.bufdelete()
end, {desc = 'Close buffer'})

Snacks.terminal

Neovim has its own terminal emulator. But this is basically a "special buffer," is not a widget or a component. We can't just "toggle" a terminal window with a keymap like in other modern editors.

Snacks.terminal provides functions to manage terminal windows with ease. For the most common use case we can just create a keymap to toggle a terminal.

-- docs: https://github.com/folke/snacks.nvim/blob/main/docs/terminal.md
vim.keymap.set({'n', 't'}, '<C-g>', function()
  Snacks.terminal.toggle()
end, {desc = 'Toggle terminal window'})

Snacks.explorer

Snacks.explorer is a file explorer with a tree style view. Under the hood this is actually a "picker" for Snacks.picker, so you will find that in the documentation some of the settings should be placed in the picker section of the setup.

To start using it we just enable it in the .setup() function and make a keymap.

Snacks.setup({
  explorer = {
    enabled = true,
    replace_netrw = true,
  },
})

vim.keymap.set('n', '<leader>e', function()
  Snacks.explorer()
end, {desc = 'Toggle file explorer'})

Now if we put everything together we should have something like this:

local Snacks = require('snacks')

Snacks.setup({
  indent = {
    enabled = true,
    char = '▏',
  },
  explorer = {
    enabled = true,
    replace_netrw = true,
  },
  input = {
    enabled = true,
    icon = '❯',
  },
  picker = {
    enabled = true,
    ui_select = true,
    prompt = '❯ ',
  },
  bigfile = {
    -- Only use `bigfile` module on older Neovim versions
    enabled = vim.fn.has('nvim-0.11') == 0,
    notify = false,
    size = 1024 * 1024, -- 1MB
    setup = function(ctx)
      vim.cmd('syntax clear')
      vim.opt_local.syntax = 'OFF'
      local buffer = vim.b[ctx.buf]
      if buffer.ts_highlight then
        vim.treesitter.stop(ctx.buf)
      end
    end
  },
})

-- Disable indent guide animation
vim.g.snacks_animate = false

-- docs: https://github.com/folke/snacks.nvim/blob/main/docs/explorer.md
vim.keymap.set('n', '<leader>e', function()
  Snacks.explorer()
end, {desc = 'Toggle file explorer'})

-- docs: https://github.com/folke/snacks.nvim/blob/main/docs/terminal.md
vim.keymap.set({'n', 't'}, '<C-g>', function()
  Snacks.terminal.toggle()
end, {desc = 'Toggle terminal window'})

-- Close while preserving window layout
-- docs: https://github.com/folke/snacks.nvim/blob/main/docs/bufdelete.md
vim.keymap.set('n', '<leader>bc', function()
  Snacks.bufdelete()
end, {desc = 'Close buffer'})

-- Fuzzy finders
-- docs: https://github.com/folke/snacks.nvim/blob/main/docs/picker.md
vim.keymap.set('n', '<leader><space>', function() Snacks.picker('buffers') end, {desc = 'Search open files'})
vim.keymap.set('n', '<leader>ff', function() Snacks.picker('files') end, {desc = 'Search all files'})
vim.keymap.set('n', '<leader>fh', function() Snacks.picker('recent') end, {desc = 'Search file history'})
vim.keymap.set('n', '<leader>fg', function() Snacks.picker('grep') end, {desc = 'Search in project'})
vim.keymap.set('n', '<leader>fd', function() Snacks.picker('diagnostics') end, {desc = 'Search diagnostics'})
vim.keymap.set('n', '<leader>fs', function() Snacks.picker('lines') end, {desc = 'Buffer local search'})
vim.keymap.set('n', '<leader>u', function() Snacks.picker('undo') end, {desc = 'Undo history'})
vim.keymap.set('n', '<leader>/', function() Snacks.picker('pickers') end, {desc = 'Search picker'})
vim.keymap.set('n', '<leader>?', function() Snacks.picker('keymaps') end, {desc = 'Search keymaps'})

What's next?

Next step is to make Neovim really understand our code: have it autocomplete variables, setup jump to definition, rename variables, all that good stuff. To achieve this I recommend using the builtin LSP client, configure it using nvim-lspconfig. I made another guide specifically for this:

Getting started with neovim's native LSP client

Thank you for your time. If you find this article useful and want to support my efforts, consider leaving a tip in ko-fi.com/vonheikemen.