Neovim Configuration for Beginners

Neovim is a powerful and highly customizable text editor, offering a rich set of features for coding and text editing. Its flexible configuration system allows you to tailor the editor to your needs, covering everything from simple settings like indentation to advanced features like plugins and key mappings. With Lua-based configuration, users have unlimited possibilities to create a personalized editing environment, integrating autocompletion, themes, and external tools. This adaptability empowers developers to optimize their workflow and boost productivity effectively.

In this blog post, we will explore how to set up the basic Neovim configuration and use custom keymaps in Neovim.

Configuration File Hierarchy

Before configuring Neovim, let’s look at the file structure of the basic Neovim configuration. Please note that you can still follow this guide even if you have a different project structure. Just be careful when editing the configuration files.

~/.config/
└── nvim
    ├── init.lua
    └── lua
        ├── options.lua
        ├── keymaps.lua
        ├── ...
        └── other_configuration_files.lua

If you haven’t created the nvim and lua directories previously, you need to create them first. Use the following command to create these directories:

mkdir -p ~/.config/nvim/lua

This command will create the nvim and lua directories with the specified file structure.

Load Configuration File Automatically

Neovim uses init.lua file for loading custom configurations defined by users. Every time Neovim starts, it checks the init.lua file and executes the commands within it. To set up the basic configuration for Neovim, we will use init.lua to load the configuration. Open your init.lua file:

nvim ~/.config/nvim/init.lua

and add the following lines to load Neovim configuration and keymaps:

require("options") -- Load Neovim Basic Configuration
require("keymaps") -- Load Custom Keybindings for Neovim

Then save and exit the file with :wq command.

Basic Neovim Configuration

In this tutorial, we will use options.lua file to store our configuration. You can use a different location or add your configuration directly into the init.lua file. First, you need to create/open the options.lua file and then add the following configuration. To create/open the options.lua file, use:

nvim ~/.config/nvim/lua/options.lua

Now you can add your desired configuration to Neovim. Below is a detailed guide to the provided Neovim configuration.

Line Numbers

opt.relativenumber = true
opt.number = true

• relativenumber: Enables relative line numbers, which display the relative line number for each line. The current line is shown as 0, making it easier to navigate using line numbers.
• number: Displays the absolute line number of the cursor line, especially helpful when working with specific line references or navigating long files.

Tabs & Indentation

opt.tabstop = 2
opt.shiftwidth = 2
opt.expandtab = true
opt.autoindent = true

• tabstop: Sets the number of spaces that a tab character represents. In this configuration, tabs are represented as 2 spaces.
• shiftwidth: Sets the number of spaces used for indentation. This also determines how much an auto-indent will add.
• expandtab: Enables the use of spaces instead of tabs. When pressing the “Tab” key, Neovim inserts spaces based on the tabstop value.
• autoindent: Copies the indentation from the current line when starting a new line. This feature makes your code indentation consistent.

Line Wrapping

opt.wrap = false

wrap: Disables line wrapping, ensuring that long lines do not wrap to the next line, thus keeping your code visually aligned and easier to read.

Search Settings

opt.ignorecase = true
opt.smartcase = true

• ignorecase: Ignores case sensitivity when performing searches. This means that search queries will match both upper and lower case characters.
• smartcase: If your search query contains any capital letters, it becomes case-sensitive. If it’s all lowercase, it remains case-insensitive.

Cursor Line

opt.cursorline = true 

cursorline: Highlights the current cursor line, making it stand out among other lines in the file.

Appearance

opt.termguicolors = true
opt.background = "dark"
opt.signcolumn = "yes"

• termguicolors: Enables true colors for the terminal. This allows Neovim to use more accurate colors for syntax highlighting and themes.
• background: Sets the background color for color schemes that support both light and dark variants. In this configuration, the background is set to “dark.”
• signcolumn: Displays a sign column to prevent text shifting when using features like Git gutter.

Backspace

opt.backspace = "indent,eol,start"

backspace: Determines the behavior of the Backspace key. The value "indent,eol,start" allows you to delete the indent, move to the previous line when at the start of a line, and delete characters at the end of a line.

Split Windows

opt.splitright = true
opt.splitbelow = true

• splitright: When splitting a window horizontally, the new window appears on the right.
• splitbelow: When splitting a window vertically, the new window appears below.

Keywords

opt.iskeyword:append("-")

iskeyword: Specifies which characters are considered part of a keyword. In this configuration, the hyphen “ is appended to the default keyword characters.

Clipboard

opt.clipboard:append("unnamedplus") 

clipboard: Specifies the default register to use for copy and paste operations. By default, Neovim uses the unnamed register. This line uses the system clipboard (on systems that support it) as the default register for copying and pasting.

Basic Neovim Keybindings

Keybindings allow you to use shortcuts for a wide range of operations, saving your time and increasing your productivity. One of the advantages of Neovim is the scope of creating custom keymaps as per your needs. We will store our custom keymaps in keymaps.lua file. To create or open the keymaps.lua file, use the following command:

nvim ~/.config/nvim/lua/keymaps.lua

Then add your required keymaps; you can add the recommended keymaps described below.

Setting Up Leader Key

The leader key is a special key used to create custom keybindings and shortcuts. It allows you to define your own key combinations for executing various commands and functions. In this tutorial, the space key is selected as the leader key to avoid overlapping.

-- set leader key to space
vim.g.mapleader = " "
local keymap = vim.keymap -- for conciseness

You can also choose your custom leader key, but it is recommended not to use Alt, Ctrl, Shift, or Super key as the leader key because the system and other programs use these keys to create shortcuts, and using them may cause overlapping.

General Keymaps

Use jk to Exit Insert Mode:

keymap.set("i", "jk", "<ESC>")

This keymap allows you to exit Insert Mode by typing jk in rapid succession.

Clear Search Highlights:

keymap.set("n", "<leader>nh", ":nohl<CR>")

Pressing the leader key (which is set to <Space>) followed by nh will clear the search highlights.

Delete Single Character without Copying into Register:

keymap.set("n", "x", '"_x')

Pressing the x key will delete the character under the cursor without copying it into the default register.

Increment/Decrement Numbers:

keymap.set("n", "<leader>+", "<C-a>") -- increment
keymap.set("n", "<leader>-", "<C-x>") -- decrement

Pressing the leader key (set to <Space>) followed by + will increment the number under the cursor, and pressing <leader>- will decrement it.

Window Management:

keymap.set("n", "<leader>sv", "<C-w>v") -- split window vertically
keymap.set("n", "<leader>sh", "<C-w>s") -- split window horizontally
keymap.set("n", "<leader>se", "<C-w>=") -- make split windows equal width & height
keymap.set("n", "<leader>sx", ":close<CR>") -- close current split window

keymap.set("n", "<leader>to", ":tabnew<CR>") -- open new tab
keymap.set("n", "<leader>tx", ":tabclose<CR>") -- close current tab
keymap.set("n", "<leader>tn", ":tabn<CR>") --  go to next tab
keymap.set("n", "<leader>tp", ":tabp<CR>") --  go to previous tab

These keymaps allow you to perform various window and tab management tasks, such as splitting windows, adjusting their sizes, and navigating between tabs.

Conclusion

With the Lua-based configuration, you can customize Neovim extensively, tailoring it to your specific needs and preferences. From basic settings like line numbering and indentation to more advanced features like themes, autocompletion, and external tools integration, the possibilities are limitless.

In this blog post, we have covered the essential steps to set up the basic Neovim configuration and employ custom keymaps. By following the provided instructions, you can create a personalized editing environment that enhances your productivity and coding experience.

If you have any questions or suggestions, feel free to drop them in the comment section. Happy coding!