Customize

vim-config loads your own files right after its own, so you can change anything without editing the config itself. Every file below is optional: create only the ones you need, in your config directory (~/.config/nvim).

Your config files

lua/config/options.lua, lua/config/keymaps.lua and lua/config/autocmds.lua each load right after their Rafi counterpart, so they can override it. An error in one of them shows a warning instead of stopping Neovim.

Options

Options load first, before any plugin.

Your lua/config/options.lua
-- Options load right after rafi.config.options, before any plugin.
-- Defaults that are always set:
-- https://github.com/rafi/vim-config/blob/master/lua/rafi/config/options.lua
-- Add your own options here.

-- For example (default values are shown):

-- Auto format on save
-- vim.g.autoformat = false

-- Elite-mode (hjkl mode, arrow-keys resize window)
-- vim.g.elite_mode = false

-- <Tab> selects completion items, jumps in snippets and opens completion
-- (coding.blink). false keeps <Tab> for snippet jumps and AI actions only.
-- vim.g.cmp_supertab = true

-- External file diff program
-- vim.g.diffprg = 'bcompare'

Keymaps

Keymaps load after startup. Delete a default keymap with vim.keymap.del, or map the same keys again.

Your lua/config/keymaps.lua
-- Keymaps load after startup, right after rafi.config.keymaps.
-- Defaults that are always set:
-- https://github.com/rafi/vim-config/blob/master/lua/rafi/config/keymaps.lua
-- Add your own keymaps here.

-- For example:

-- Delete a default keymap
-- vim.keymap.del('n', '<leader>uw')

-- Map keys again to change what they do
-- vim.keymap.set('n', '<Leader>w', '<cmd>update<CR>', { desc = 'Save File' })

Autocmds

Your lua/config/autocmds.lua
-- Autocmds load right after rafi.config.autocmds.
-- Defaults that are always set:
-- https://github.com/rafi/vim-config/blob/master/lua/rafi/config/autocmds.lua
-- Add your own autocmds here.

-- For example, turn spell checking off in Markdown buffers:
-- vim.api.nvim_create_autocmd('FileType', {
-- 	group = vim.api.nvim_create_augroup('user.markdown', {}),
-- 	pattern = 'markdown',
-- 	callback = function()
-- 		vim.opt_local.spell = false
-- 	end,
-- })

Extras and core plugins

rafi.json in your config directory lists the extras you enabled and the core plugins you disabled. :RafiExtras (Spacemx) edits it for you, or you can edit it by hand and restart Neovim:

json
{
	"extras": ["editor.dial", "lang.go", "ui.deadcolumn"],
	"disabled": ["lualine"]
}

A core plugin in disabled doesn’t load, so you can replace it with your own file. snacks can’t be disabled.

Your plugins

Every lua/plugins/*.lua file is plain Lua, sourced after the extras. Add plugins with vim.pack.add() and set them up right there. See the examples below.

Your extras

An extra of your own goes in lua/plugins/extras/<category>/<name>.lua. Start it with a comment line describing it: :RafiExtras shows that line and lists your extra next to Rafi’s.

LSP settings

Override a server’s settings with vim.lsp.config() in one of your plugin files, or in after/lsp/<server>.lua.

Examples

Add a plugin

Save it as lua/plugins/gruvbox.lua. vim.pack installs it on the next start, and :colorscheme gruvbox switches to it.

lua
vim.pack.add({ 'https://github.com/ellisonleao/gruvbox.nvim' })
require('gruvbox').setup({ contrast = 'hard' })

Load a plugin on first use

rafi.pack runs the code on the first event, filetype or command, so the plugin doesn’t slow down startup.

lua
local pack = require('rafi.pack')

pack.on_event('InsertEnter', function()
	vim.pack.add({ 'https://github.com/windwp/nvim-autopairs' })
	require('nvim-autopairs').setup()
end)

pack.on_filetype('csv', function()
	vim.pack.add({ 'https://github.com/hat0uma/csvview.nvim' })
	require('csvview').setup()
end)

Replace a core plugin

Add “lualine” to disabled in rafi.json, then load your own statusline in lua/plugins/lightline.lua.

lua
vim.pack.add({ 'https://github.com/itchyny/lightline.vim' })
vim.g.lightline = { colorscheme = 'wombat' }

Write your own extra

Save it as lua/plugins/extras/editor/zen.lua and turn it on with :RafiExtras. The first line is the description it shows.

lua
-- Distraction-free writing
local pack = require('rafi.pack')

pack.command('ZenMode', function()
	vim.pack.add({ 'https://github.com/folke/zen-mode.nvim' })
	require('zen-mode').setup({ window = { width = 90 } })
end)
vim.keymap.set('n', '<leader>z', '<cmd>ZenMode<CR>', { desc = 'Zen Mode' })

Change LSP settings

In a lua/plugins/*.lua file, or as after/lsp/<server>.lua returning the table.

lua
vim.lsp.config('yamlls', {
	filetypes = { 'yaml', 'yaml.ansible', 'yaml.docker-compose' },
})
vim.lsp.config('lua_ls', {
	settings = {
		Lua = {
			workspace = { checkThirdParty = false },
			completion = { callSnippet = 'Replace' },
		},
	},
})