Installing Neovim can be as easy as entering a single command, but setting it up requires a little more work. This post introduces a basic setup that includes useful plugins and a language server.

Prerequisites

  • Install a Nerd Font to display icons used by many plugins
    • Remember to enable or use that font in your terminal emulator
  • Install a terminal emulator with 24-bit and 256-color mode so that color schemes work properly

Neovim configuration

Neovim reads configuration in ~/.config/nvim with ~/.config/nvim/init.lua being the equivalent of ~/.vimrc. You may have to create the file yourself. It’s a good idea to also create the directory structure used to install plugins and customize Neovim.

    ~/.config/nvim
    ├── init.lua
    ├── lua
    │   ├── config
    │   │   └── options.lua
    │   └── plugins

Vim options

You could put traditional Vim options in lua/config/options.lua and leave init.lua for Neovim options.

options.lua example

local set = vim.opt
---------------- vim options  ----------------
set.number = true  -- shows line numbers
set.tabstop = 4
set.softtabstop = 4
set.expandtab = true -- make tabs spaces
set.autoindent = true -- auto indent
set.cindent = true
set.shiftwidth = 4 -- autoindent width

To use options.lua, add the following to init.lua

require("config.options")

Lazy plugin management

Lazy is a plugin manager for Neovim. Follow their installation guide to install.

This should be the resulting directory tree

    ~/.config/nvim
    ├── init.lua
    ├── lua
    │   ├── config
    │   │   ├── lazy.lua
    │   │   └── options.lua
    │   └── plugins

Neovim at this point may complain since there are no plugins inside the plugin folder.

Install plugins

Installing plugins with Lazy is as easy as adding a file in lua/plugins with something like the following as the content

    return {
        -- plugin details
    }

For example, you can install the status line plugin Lualine with the file lua/plugins/lualine.lua:

    return {
        'nvim-lualine/lualine.nvim',
        dependencies = { 'nvim-tree/nvim-web-devicons' }
    }

And add the following to init.lua to enable it

    require('lualine').setup{
        -- options here
    }

The next time Neovim starts up, Lazy automatically installs the plugin. You can use the :Lazy command to bring up the Lazy menu.

Other plugins worth installing:

A collection of awesome Neovim plugins: awesome Neovim

Make sure to go through not just the installation steps, but also the optional dependencies to make the plugins work better. For example, ripgrep allows the live_grep feature of Telescope.

Language server protocol

A language server provides features like auto complete and go to definition. nvim-lspconfig is the default Language Server Protocol client, and you can install other plugins, like COQ, to provide more features.

nvim-lspconfig also requires language servers installed on your system, like clangd for C++ or vale (vale-ls) for non-code text like markdown. The list of language server configurations it current has is here or you can view it by running :help lspconfig-all.

Language server example: clangd

To set up nvim-lspconfig and COQ with clangd after installing the COQ plugin, add the following to init.lua

    local lsp = require "lspconfig"
    local coq = require "coq"
    lsp.clangd.setup { coq.lsp_ensure_capabilities {
        cmd = {'clangd', '--background-index', '--clang-tidy'},
        filetypes = { "c", "cpp", "objc", "objcpp", "cuda", "proto" },
        init_options = {
          fallbackFlags = { '-std=c++20' },
        },
    }
    }

Some useful key map settings

    local bufopts = { noremap = true, silent = true, buffer = bufnr }
    vim.keymap.set('n', 'gD', vim.lsp.buf.declaration, bufopts)
    vim.keymap.set('n', 'gd', vim.lsp.buf.definition, bufopts)
    vim.keymap.set('n', 'gi', vim.lsp.buf.implementation, bufopts)
    vim.keymap.set('n', '<leader>D', vim.lsp.buf.type_definition, bufopts)
    vim.keymap.set("n", "]g", vim.diagnostic.goto_next, { desc = 'Go to next LSP error' })
    vim.keymap.set("n", "[g", vim.diagnostic.goto_prev, { desc = 'Go to prev LSP error' })

    vim.keymap.set('n', '<leader>F', "<cmd>lua vim.lsp.buf.format()<CR>", 
                    { desc = 'Format current file'})

Aside: if you don’t like the default formatting style, you can have a ‘global’ .clang-format file in ~ or even / since it searches up parent directories until it finds one by default. For example, ~/.clang-format:

    ---
    # "Global" format file
    BasedOnStyle: LLVM
    IndentWidth: 4
    ---

Language server example: vale-ls

Vale is useful in providing style guidelines when writing documentation, since it can use style guides such as the Microsoft Writing Style Guide and the Google Developer Documentation Style Guide.

Vale comes with a lot of package managers but you may have to download or build vale-ls yourself from here.

To use vale-ls with COQ, add the following to init.lua

    lsp.vale_ls.setup { coq.lsp_ensure_capabilities {
        cmd = {'vale-ls'}, 
        filetypes = { "markdown", "text", "tex", "rst" },
    }
    }

Then follow the quickstart guide in the global configuration directory to get vale-ls working anywhere.

Aside: you can have a ‘global’ list of accepted words by adding the following directory and files

    $VALE_CONFIG_PATH
    └── styles
        └── config
            └── vocabularies
                └── global
                    ├── accept.txt
                    └── reject.txt

and this line in .vale.ini

    Vocab = global

TLDR: the setup

You can find the Neovim setup here.