Learn Neovim - Building Basic Options & Keymaps in init.lua

#Introduction

After covering the modern configuration directory structure, Lua language basics, and the Neovim Lua API like vim.opt and vim.keymap.set in episode 6, now it is time for something more satisfying: building a real configuration you will use every day.

Picture this: every engineer using a modern IDE has a distinctive editor "feel" — line numbers on the left, consistent indentation, smart search, and shortcuts that feel like extensions of their hands. When you switch machines, change work laptops, or move to a new server, all that "feel" usually disappears and has to be set up again. With a neatly stored Neovim config, all your preferences follow you anywhere — and this is where options (behavior settings) and keymaps (custom shortcuts) become the first two pillars you must build.

In this episode, we will write two complete, ready-to-use files: lua/config/options.lua and lua/config/keymaps.lua. For every option, I will explain why it matters — not just what it does — so you can decide for yourself which ones fit your working style, instead of simply copying someone else's config.

#Building lua/config/options.lua

Editor options are the "operating system" of your editing experience. Let's break them down by category, then assemble them into one complete file.

#Line Numbers: number and relativenumber

These two options determine how line numbers are displayed. number shows the absolute line number in the left gutter. relativenumber shows the relative distance from the cursor position — the lines above and below the cursor show 1, 2, 3, and so on, while the cursor's own line shows its absolute number.

#Indentation: tabstop, shiftwidth, expandtab, smartindent

These four options determine how Neovim handles tabs and indentation — the topic that most often causes "holy wars" between engineering teams.

#Search: ignorecase, smartcase, hlsearch, incsearch

Search options determine how /pattern behaves. The ignorecase + smartcase pair has the biggest impact on your speed:

#Display & UI: termguicolors, cursorline, scrolloff, signcolumn

These four options shape your editor's "face":

#Behavior: clipboard, undofile, mouse

#The Complete options.lua

Here is the complete, ready-to-use lua/config/options.lua:

local opt = vim.opt
 
-- Nomor baris
opt.number = true
opt.relativenumber = true
 
-- Indentasi
opt.tabstop = 4
opt.shiftwidth = 4
opt.expandtab = true
opt.smartindent = true
 
-- Pencarian
opt.ignorecase = true
opt.smartcase = true
opt.hlsearch = true
opt.incsearch = true
 
-- Tampilan & UI
opt.termguicolors = true
opt.cursorline = true
opt.scrolloff = 8
opt.signcolumn = "yes"
 
-- Perilaku
opt.clipboard = "unnamedplus"
opt.undofile = true
opt.mouse = "a"

#Building lua/config/keymaps.lua

If options define the editor's behavior, keymaps define your speed. This is the most personal place in the entire config — and the part most often rewritten as you discover your own work patterns.

#Understanding the Leader Key

The leader key concept is one of Vim's most important inventions. The idea is simple: provide one special "trigger" key so all your custom shortcuts live under that namespace, without colliding with built-in shortcuts.

vim.g.mapleader = " " sets space as the leader. Consequently, the combination <leader>w means pressing space then w. Why space? Because the space key in normal mode has no important function and is always easily reachable with both thumbs — that is why space has become the de-facto standard in the modern Neovim community.

#The Anatomy of vim.keymap.set

Its full signature: vim.keymap.set(mode, lhs, rhs, opts).

• mode — the mode where the keymap applies (see the mode table below).
• lhs — the key combination you press (left-hand side).
• rhs — the action to run (right-hand side): can be a command string or a Lua function.
• opts — advanced options like silent, desc, buffer, noremap.

#Mode Table

#The Complete keymaps.lua

Here is the complete lua/config/keymaps.lua. Notice that we create the alias local map = vim.keymap.set to keep the file concise and readable:

vim.g.mapleader = " "
vim.g.maplocalleader = " "
 
local map = vim.keymap.set
 
-- ==================== Normal Mode ====================
 
-- Simpan & keluar
map("n", "<leader>w", "<Cmd>w<CR>", { desc = "Simpan file" })
map("n", "<leader>q", "<Cmd>q<CR>", { desc = "Tutup window" })
map("n", "<leader>x", "<Cmd>bd<CR>", { desc = "Tutup buffer" })
 
-- Navigasi buffer
map("n", "<leader>bn", "<Cmd>bnext<CR>", { desc = "Buffer berikutnya" })
map("n", "<leader>bp", "<Cmd>bprevious<CR>", { desc = "Buffer sebelumnya" })
map("n", "<leader>bb", "<Cmd>b#<CR>", { desc = "Buffer alternatif" })
 
-- Window split
map("n", "<leader>sh", "<Cmd>split<CR>", { desc = "Split horizontal" })
map("n", "<leader>sv", "<Cmd>vsplit<CR>", { desc = "Split vertikal" })
map("n", "<leader>so", "<Cmd>only<CR>", { desc = "Tutup window lain" })
 
-- Pindah antar window (Ctrl-w h/j/k/l tanpa Ctrl-w)
map("n", "<C-h>", "<C-w>h", { desc = "Ke window kiri" })
map("n", "<C-j>", "<C-w>j", { desc = "Ke window bawah" })
map("n", "<C-k>", "<C-w>k", { desc = "Ke window atas" })
map("n", "<C-l>", "<C-w>l", { desc = "Ke window kanan" })
 
-- Hapus sorotan pencarian
map("n", "<Esc><Esc>", "<Cmd>nohlsearch<CR>", { desc = "Hapus sorotan" })
map("n", "<leader>nh", "<Cmd>nohlsearch<CR>", { desc = "Hapus sorotan" })
 
-- File explorer bawaan (akan diganti plugin di episode 12)
map("n", "<leader>e", "<Cmd>Ex<CR>", { desc = "Buka file explorer" })
 
-- ==================== Insert Mode ====================
 
-- Keluar insert mode dengan jj (lebih cepat dari Esc)
map("i", "jj", "<Esc>", { desc = "Keluar insert mode" })
map("i", "<C-s>", "<Cmd>w<CR>", { desc = "Simpan tanpa keluar mode" })
 
-- ==================== Visual Mode ====================
 
-- Pertahankan seleksi saat indentasi
map("v", "<", "<gv", { desc = "Indentasi kiri (pertahankan seleksi)" })
map("v", ">", ">gv", { desc = "Indentasi kanan (pertahankan seleksi)" })
map("v", "p", '"_dP', { desc = "Paste tanpa menimpa register" })
 
-- ==================== Terminal Mode ====================
 
map("t", "<Esc><Esc>", "<C-\\><C-n>", { desc = "Keluar terminal ke normal" })

#Why Use <Cmd> and Not :?

This is one of those details that is rarely explained but has a big impact. Most tutorials write mappings like map("n", "<leader>w", ":w<CR>"). But there is a subtle difference between : and <Cmd>:

• With :, Neovim enters command-line mode and then types the command. The result: the cursor temporarily moves, an echo appears in the command-line, and in visual mode, a range <,'> is automatically prepended to the command — so :w in visual mode will only write the selected lines!
• With <Cmd>...<CR>, the command executes without leaving the active mode and without echo. This is why the mappings above use <Cmd>w<CR> — cleaner, and safe to use in visual mode.

#silent and desc Tips

Two small options with a big impact:

• silent = true hides the command echo in the command-line. Without it, every <leader>w shows :w at the bottom of the screen — a small visual distraction that gets annoying over time.
• desc gives every mapping a name. It appears in :map for debugging and — more importantly — becomes the main material for the which-key popup we will install in episode 20. Describing mappings from the start is a small investment with a big return.

#Common Options & Keymaps Pitfalls

1. A leader key that "never registers". The symptom: <leader>w throws E15: Invalid expression or does nothing. The cause is almost always mapleader set after the keymap — or the config being reloaded before mapleader had a chance to be set.
2. A leader timing that is too tight. By default timeoutlen is 1000ms. If you press space then wait more than a second before the next letter, the mapping will not trigger. If it feels slow, lower it with opt.timeoutlen = 500 in options.lua.
3. Mappings conflicting with built-ins. Before overriding a built-in shortcut (for example <C-h> for windows), first check :map <C-h> to see its original function. Sometimes changing a standard key unknowingly breaks a feature you are using.
4. Using : in visual mode mappings without understanding the automatic <,'> range. The solution: <Cmd> (see above).
5. expandtab enabled on all files can break files that require tabs (Makefiles). Solution: disable it per-filetype — we will discuss this with ftplugin in episode 8.
6. Too many mappings piling up on each other. If <leader>s is already used for split, do not use <leader>s for something else. Stay consistent with one leading letter per function group.
7. Forgetting silent. Mappings that show echo feel "noisy". Get in the habit of including { silent = true, desc = ... } from the start.

#Closing

In episode 7 we built the first two pillars of a Neovim config. In lua/config/options.lua, you set line numbers with number + relativenumber, indentation with tabstop/shiftwidth/expandtab/smartindent, smart search with ignorecase + smartcase, display with termguicolors/cursorline/scrolloff/signcolumn, and behavior with clipboard = "unnamedplus", undofile, and mouse. In lua/config/keymaps.lua, you set space as the leader key, created grouped shortcuts (<leader>w, <leader>b, <leader>s), learned the difference between <Cmd> and :, and realized why silent and desc matter.

Key points to take with you:

• vim.g.mapleader = " " must be placed before all <leader> keymaps.
• scrolloff = 8 and signcolumn = "yes" keep context and prevent layout jumping.
• clipboard = "unnamedplus" connects the default register to the system clipboard.
• Use <Cmd>...<CR> for commands that should be safe in all modes, especially visual.
• Every mapping deserves silent = true and desc for comfort and readability.

Your config is now alive: the editor feels comfortable, and your hands are starting to "dance" over the leader key. But there is one type of power we have not built yet — the editor's ability to react to events on its own: auto-saving, tidying whitespace, or running special commands. In episode 8, we will cover Autocommands, Filetype Detection & Custom Commands — building lua/config/autocmds.lua, creating custom commands like :TrimWhitespace, and setting per-language options with ftplugin. Stay motivated!