Customization¶

This guide covers how to customize the configuration for your needs.

Modifying Keybindings¶

All keybindings are in lua/plugin/which-key.lua. This is the file you’ll edit most often.

Adding a keybinding:

Open lua/plugin/which-key.lua
Find the appropriate section
Add your keybinding:

wk.add({
  { "<leader>x", "<cmd>MyCommand<cr>", desc = "Do something" }
})

Example 1: Add a keybinding to run a custom command

-- In lua/plugin/which-key.lua, add:
wk.add({
  { "<leader>m", "<cmd>Make<cr>", desc = "Run make" }
})

Now <leader>m runs the make command.

Example 2: Add a keybinding to execute a shell command

wk.add({
  { "<leader>sh", "<cmd>!sh /path/to/script.sh<cr>", desc = "Run my script" }
})

Example 3: Add a keybinding to call a Lua function

wk.add({
  { "<leader>z", function() my_custom_function() end, desc = "My function" }
})

Removing a keybinding:

Simply delete or comment out the line in which-key.lua.

Changing the Leader Key¶

The leader key is set in lua/settings.lua:

vim.g.mapleader = " "  -- Space is the leader key

Change to a different key:

vim.g.mapleader = ","  -- Use comma instead

Common choices:

Space (default) - Reach with thumb
Comma - Easy for keyboard
Semicolon - QWERTY layout friendly

Customizing Appearance¶

Color scheme:

Edit lua/plugin/ayu.lua to change the theme:

vim.cmd.colorscheme("ayu")  -- Change "ayu" to another scheme

Requires the colorscheme to be installed.

Font size (terminal setting, not Neovim):

macOS: Terminal > Preferences > Profiles > Text
Linux: Right-click > Preferences or Settings > Appearance
Windows: Not supported (use WSL2)

Line numbers:

In lua/settings.lua:

vim.opt.number = true      -- Show line numbers
vim.opt.relativenumber = true  -- Show relative numbers

Status line:

The status line is in lua/statusline.lua. Modify to show different info.

Indentation guides (vertical lines):

In lua/plugin/indent_blankline.lua:

require('ibl').setup({
    indent = { char = '│' }  -- Change character
})

Editing Python Configuration¶

Tab width:

In lua/settings.lua:

vim.opt.tabstop = 4       -- Display width of tab
vim.opt.shiftwidth = 4    -- Indentation width

Code formatter settings:

Edit pyproject.toml:

[tool.darker]
line_length = 100  # Default is 140

[tool.isort]
profile = "black"

Python linter settings (Ruff):

Edit pyproject.toml:

[tool.ruff]
line-length = 100
select = ["E", "W", "F"]  # What errors to check

LSP settings:

Edit lua/lsp/lsp.lua to customize:

Type checking level
Diagnostic settings
Completion options

Example:

-- Make diagnostics less aggressive
vim.diagnostic.config({
    virtual_text = false,  -- Don't show inline diagnostics
    signs = true,
    underline = true,
})

Adding a New Language Server¶

To add support for another language:

Install the language server
Add configuration to lua/lsp/lsp.lua

Example: Add TypeScript support

npm install -g typescript-language-server

Then in lua/lsp/lsp.lua:

-- Add after Zuban setup
local lspconfig = require('lspconfig')
lspconfig.tsserver.setup({
    capabilities = capabilities,
    on_attach = on_attach,
})

Customizing FZF¶

FZF configuration is in lua/plugin/fzf-lua.lua.

Change search directories:

-- Search only in src/ directory
require('fzf-lua').setup({
    files = {
        cwd = 'src/'
    }
})

Ignore directories:

require('fzf-lua').setup({
    files = {
        exclude = 'node_modules',
    }
})

Change preview window size:

require('fzf-lua').setup({
    fzf_opts = {
        ['--preview-window'] = 'right:40%'
    }
})

Adding Custom Functions¶

Create a new utility file and use it in your config.

Example: Add a custom Python command

Create lua/utils/my_utils.lua:

local M = {}

function M.run_black()
    vim.cmd('!black %')
end

return M

Use in lua/plugin/which-key.lua:

local my_utils = require('utils.my_utils')

wk.add({
    { "<leader>b", function() my_utils.run_black() end, desc = "Format with Black" }
})

Adding a Plugin¶

To add a new plugin (e.g., vim-surround):

Update your plugin manager configuration
Install the plugin
Configure it in a new file in lua/plugin/
Require it in init.lua

Example: Add telescope for advanced searching

Many users replace FZF with telescope. To add it:

Install telescope (use your plugin manager)
Create lua/plugin/telescope.lua:

require('telescope').setup({
    defaults = {
        file_ignore_patterns = {'node_modules', '.git'}
    }
})

Add to init.lua:

require('lua.plugin.telescope')

Add keybindings in which-key.lua

Changing LSP Diagnostic Display¶

Control how diagnostics appear:

-- In lua/lsp/lsp.lua
vim.diagnostic.config({
    virtual_text = false,     -- No inline error messages
    underline = true,          -- Keep underlines
    signs = true,              -- Show signs in gutter
    update_in_insert = false,  -- Don't update while typing
})

Making Neovim Faster¶

Profile startup time:

nvim --startuptime startup.log +q

Check startup.log for slow plugins.

Lazy load plugins:

In plugin configuration, use lazy loading:

require('plugin').setup({
    lazy = true,  -- Load only when needed
})

Disable unused plugins:

In lua/disable_plugins.lua, disable defaults you don’t use.

Customizing Text Wrapping¶

Enable wrapping by default:

-- In lua/settings.lua
vim.opt.wrap = true
vim.opt.linebreak = true  -- Break on words, not characters

Visual indicator at column:

vim.opt.colorcolumn = "88"  -- Show line at column 88

Changing Font for Symbols¶

Icons come from the colorscheme. To use different icons:

Change the colorscheme in lua/plugin/ayu.lua
Or customize the colorscheme to use different Unicode characters

Without a Nerd Font:

Icons won’t display correctly. Install a Nerd Font from: https://www.nerdfonts.com/

Custom Autocommands¶

Add custom actions in lua/autocmds.lua.

Example: Auto-format on save

vim.api.nvim_create_autocmd("BufWritePre", {
    pattern = "*.py",
    callback = function()
        vim.cmd("Format")  -- Or your formatter command
    end
})

Example: Set filetype for custom files

vim.api.nvim_create_autocmd("BufNewFile,BufRead", {
    pattern = "*.myext",
    callback = function()
        vim.bo.filetype = "python"
    end
})

Creating a Configuration Backup¶

Before major changes, save your configuration:

cd ~/dotfiles/nvim
git branch backup-$(date +%Y%m%d)
git add .
git commit -m "Pre-customization backup"

If something breaks:

git checkout backup-YYYYMMDD

Reloading Configuration¶

After editing config files:

Reload all: :luafile %
Or restart Neovim completely

Some changes (like new keybindings) take effect immediately. Others need a restart.

Testing Customizations¶

When adding customizations:

Save your change
Reload configuration (or restart)
Test the feature: :checkhealth for diagnostics
Check :messages` for errors

Common Customization Patterns¶

Pattern 1: Change default behavior

Find the setting in a config file
Edit the value
Reload/restart

Pattern 2: Add new command

Create function in lua/utils/
Add keybinding in which-key.lua
Test the new command

Pattern 3: Replace a plugin

Add new plugin configuration to lua/plugin/
Remove old plugin’s keybindings from which-key.lua
Test that new plugin works

Pattern 4: Disable a feature

Comment out or delete from relevant file
Remove associated keybindings
Restart Neovim

Troubleshooting Customizations¶

Error after editing:

Check syntax with :checkhealth
Look at error message with :messages
Fix the syntax error
Reload with :luafile % or restart

Keybinding doesn’t work:

Verify syntax in which-key.lua
Check with :map <leader>x to see if it’s mapped
Ensure the command exists
Restart Neovim

Plugin not loading:

Verify it’s required in init.lua
Check for errors: :messages
Verify plugin is installed
Restart Neovim

For more help, see Troubleshooting.