Getting started with Neovim - PDE p.I

Table of Contents

Tags:

Info

This is the first part of the personalized development environment series

Prerequisites

The reader of this guide needs to know the basics of:

  • Vim motions and keys
  • opening and saving files in Vim

Learn here, here and here

Abstract

The pde series is intended to provide a simple guide for a new neovim user to learn about configuring the editor.

The series will cover:

  • neovim config with lua
  • config setup and dir structure
  • must have plugins and their configurations i use
    • language servers
    • fuzzy finders
  • theming with lualine, bufferline

This part covers:

  • neovim config with lua
    • options
    • first plugins
    • plugin options
    • custom keybindings
  • config setup
  • config dir structure

More info:

  • Neovim documentation is located here
  • My configuration can be found here

Installing

To install read the neovim wiki.

Hint: If you are on a linux system use your package manager to install neovim:

1sudo pacman -S neovim
2sudo apt install neovim

Hint 2: For windows I’d recommend installing scoop in the powershell and using it to install neovim

1# allow executing remote scripts
2Set-ExecutionPolicy RemoteSigned -Scope CurrentUser
3# install scoop
4irm get.scoop.sh | iex
5# install neovim using scoop
6scoop install neovim

Config

Neovim can be configured using Vimscript1 or Lua2 - I’d recommend the second option over the first, simply because Lua is a real programming language which also is:

  • minimal and powerful
  • widely used3
  • well documented4
  • fast 5

This guide will use Lua, due to the fact that I noticed significant performance improvements using lua instead of vimscript.

Config guide

Config path

Config paths differ on windows compared to those on a unix system. I use Windows sometimes, therefore I included the following windows guide additionally to the unix guide.

Configuration paths for Neovim, more info here:

  • Windows:

  • C:\Users\<username>\AppData\Local\nvim

  • Unix:

  • $XDG_CONFIG_HOME/nvim

  • ~/<username>/.config/nvim

Config layout

1nvim/
2|   coc-settings.json
3|   init.lua
4|
5\---lua/
6    keybindings.lua
7    options.lua
8    plugin-options.lua
9    plugins.lua
  1. Create the nvim folder
  2. Create the lua folder in the nvim folder
  3. create the init.lua file in the nvim folder
  4. create the following files in the nvim/lua folder:
    • keybindings.lua: we will create new keybindings here
    • options.lua: general options
    • plugin-options.lua: options for plugins
    • plugins.lua: specify plugins we need

Configuring

If any of the following options are not commented well enough, start neovim and run:

:help <option>

After each step save and reload the config using :source %

  1. Open nvim/init.lua and enter the following configuration:
 1-- lua automatically adds all .lua 
 2-- files in the nvim/lua directory to the namespace
 3
 4-- order of import is relevant,
 5-- plugins have to be installed before configuring them
 6
 7-- import the options
 8require("options")
 9-- import the plugins
10require("plugins")
11-- import the plugin options
12require("plugin-options")
13-- import the keybinds
14require("keybindings")
  1. Open nvim/lua/options.lua and enter the following configuration:
 1-- bind variables
 2local g = vim.g
 3local o = vim.opt
 4
 5-- set the leader key to space
 6g.mapleader = " "
 7
 8-- disable default file tree
 9g.loaded_netrw = 1
10g.loaded_netrwPlugin = 1
11g.netrw_banner = 0
12g.netrw_winsize = 0
13
14-- enable line numbers
15o.number = true
16
17-- dont save buffers on closing them
18o.hidden = true
19
20-- enable syntax highlighting
21o.syntax = "on"
22
23-- disable wrapping chars which are out of the current view
24o.wrap = false
25
26-- set encodings
27o.encoding = "utf-8"
28o.fileencoding = "utf-8"
29
30-- more space for commands at the bottom
31o.cmdheight = 2
32
33-- enable better splitting
34o.splitbelow = true
35o.splitright = true
36
37o.conceallevel = 0
38
39-- indentation, 4 spaces for a tab
40o.tabstop = 4
41o.shiftwidth = 4
42
43-- automatically insert tabs
44o.smarttab = true
45
46-- replace tab with spaces
47o.expandtab = true
48
49-- indent blocks automatically
50o.smartindent = true
51o.autoindent = true
52
53-- enable tabline if a tab is there
54o.showtabline = 1
55
56-- dont show mode in the bottom bar
57o.showmode = false
58
59-- set updatetime to 50ms (updates every 50ms)
60o.updatetime = 50
61o.timeoutlen = 500
62
63-- enable better colors
64o.termguicolors = true
65
66-- better searching
67o.incsearch = true
68o.smartcase = true
69o.hlsearch = false
70
71-- disable backups
72o.backup = false
73o.background = "dark"
74
75-- display the current line different from the rest of the file
76o.cursorline = true
77
78-- disable swap files
79o.swapfile = false
  1. Open nvim/lua/plugins.lua and enter the following configuration:
 1-- i use vimplug to manage my plugins
 2
 3-- this checks if vimplug is installed, if not install it
 4vim.cmd([[
 5if empty(glob('~/.config/nvim/autoload/plug.vim'))
 6  silent !curl -fLo ~/.config/nvim/autoload/plug.vim --create-dirs
 7    \ https://raw.githubusercontent.com/junegunn/vim-plug/master/plug.vim
 8endif
 9]])
10
11-- assign variable
12local Plug = vim.fn['plug#']
13
14-- in between this we call Plug to specify plugins
15vim.call('plug#begin', '~/.config/nvim/plugged')
16
17    -- display buffers and tabs nicely
18    Plug 'akinsho/bufferline.nvim'
19
20    -- color theme / sheme
21    Plug('folke/tokyonight.nvim', { branch = 'main' })
22
23    -- comment helper
24    Plug 'tpope/vim-commentary'
25
26    -- status line
27    Plug 'nvim-lualine/lualine.nvim'
28
29    -- file explorer
30    Plug 'nvim-tree/nvim-tree.lua'
31
32    -- icons for everything, file explorer, tabs, statusline
33    Plug 'nvim-tree/nvim-web-devicons'
34
35    -- automatically add "([ pairs if first one is typed
36    Plug 'jiangmiao/auto-pairs'
37
38    -- startup interface
39    Plug 'mhinz/vim-startify'
40vim.call('plug#end')
  1. Open nvim/lua/plugin-options.lua and enter the following configuration:
 1-- set colorsheme
 2vim.cmd([[colorscheme tokyonight-night]])
 3
 4-- bufferline config
 5require("bufferline").setup{
 6    options = {
 7        -- only display tabs, hide buffers
 8        mode = "tabs",
 9        -- style for kitty terminal
10        separator_style = "slant",
11        -- display coc diagnostics
12        diagnostics = "coc"
13    }
14}
15
16-- nvim tree setup
17require("nvim-tree").setup()
18
19
20-- lualine setup
21require("lualine").setup{
22    options = {
23        theme = "palenight"
24    }
25}
  1. Open nvim/lua/keybindings.lua and enter the following configuration:
 1-- helper for mapping custom keybindings
 2-- source: https://gist.github.com/Jarmos-san/d46605cd3a795513526448f36e0db18e#file-example-keymap-lua
 3function map(mode, lhs, rhs, opts)
 4    local options = { noremap = true }
 5    if opts then
 6        options = vim.tbl_extend("force", options, opts)
 7    end
 8    vim.api.nvim_set_keymap(mode, lhs, rhs, options)
 9end
10
11-- toggle the nvim tree sidebar with ctrl+b
12map("n", "<C-b>", ":NvimTreeToggle<CR>", {silent = true})
13
14-- move visual selection down with shift+J
15map("v", "J", ":m '>+1<CR>gv=gv")
16-- move visual selection up with shift+K
17map("v", "K", ":m '<-2<CR>gv=gv")

Before and after

before after Left the now configured neovim, right the stock neovim

Foreshadowing

After setting the foundation by installing plugins, setting options and configuring keybinds we will move on to configuring language servers and fuzzy finders. This and more in Part II and Part III.

  1. https://vimdoc.sourceforge.net/htmldoc/usr_41.html ↩︎

  2. https://www.lua.org/ ↩︎

  3. https://en.wikipedia.org/wiki/Category:Lua_(programming_language)-scriptable_software ↩︎

  4. https://www.lua.org/manual/5.4/ ↩︎

  5. https://sr.ht/~henriquehbr/lua-vs-vimscript/ ↩︎