vim/README.md

Nixvim Configuration

A standalone Neovim configuration built with nixvim and Nix flakes.

Installation

# First time — install to your Nix profile
./install.sh

# Update an existing installation
./update.sh

Testing your configuration

# Try the config without installing
nix run .

# Verify nothing is broken
nix flake check .

Configuring

Add or modify nix files in ./config. The main entry point is config/default.nix.

Plugin Usage Guide

This configuration comes with a curated set of plugins. Here's how to get the most out of each one.

Navigation

Telescope — fuzzy finder for everything

Keymap	Action
<leader>ff	Find files in the project
<leader>fg	Live grep across all files (uses ripgrep)
<leader>fb	Browse open buffers
<leader>fh	Search help tags

Type to filter results, <CR> to open, <C-x> to open in a split, <C-v> for a vertical split.

Hop — jump to any visible position

Keymap	Action
s + two characters	Jump to any matching two-character sequence on screen

Press s, type two characters, then press the hint letter to jump there instantly. Much faster than f/F or /search for medium-distance jumps.

fzf-lua — alternative fuzzy finder

Command	Action
:FzfLua files	Find files
:FzfLua grep	Grep project
:FzfLua buffers	Switch buffers

Faster than Telescope on very large codebases thanks to the native fzf algorithm.

File Management

nvim-tree — sidebar file explorer

Keymap	Action
<C-n> or :NvimTreeToggle	Toggle the file tree sidebar
a	Create a new file or directory (inside the tree)
d	Delete file (inside the tree)
r	Rename file (inside the tree)
<CR>	Open file or expand folder

Oil — edit the filesystem like a buffer

Command	Action
:Oil	Open the parent directory as an editable buffer

Rename files by editing their names, delete by removing lines, create by adding new lines. Save the buffer (:w) to apply changes.

Bufferline — tab-style buffer bar

Keymap	Action
:bnext / :bprev	Cycle through open buffers
:bdelete	Close the current buffer

Click on tabs with the mouse or use buffer commands to switch between open files.

Git

Fugitive — Git commands inside Neovim

Command	Action
:Git	Open interactive git status (stage with s, commit with cc)
:Git blame	Inline blame annotations for the current file
:Git diff	View diff of current file
:Git log	Browse commit history
:Gwrite	Stage the current file

Lazygit — full git UI in a floating terminal

Command	Action
:LazyGit	Open the lazygit terminal UI

A visual interface for staging, committing, branching, rebasing, and more. Navigate with arrow keys, press ? inside lazygit for help.

Editing

Commentary — toggle comments

Keymap	Action
gcc	Toggle comment on the current line
gc + motion	Toggle comments over a motion (e.g. gcap for a paragraph)
gc in visual mode	Toggle comments on selected lines

vim-surround — manage surrounding characters

Keymap	Action
cs"'	Change surrounding " to '
ds"	Delete surrounding "
ysiw]	Surround the word with []
S" in visual mode	Surround selection with "

cmp — autocompletion

Completion popups appear automatically as you type. Use:

Keymap	Action
<C-n> / <C-p>	Navigate completion items
<CR>	Accept the selected completion
<C-e>	Dismiss the completion menu

Sources include buffer words, file paths, LSP, and more (all enabled automatically).

UI & Visual Aids

which-key — keybinding discovery

Press <leader> (or any prefix key) and wait — a popup shows all available continuations. Great for learning and remembering mappings you don't use often.

indent-blankline — indentation guides

Visible automatically. Vertical lines show indentation levels so you can quickly see code structure and nesting depth.

illuminate — highlight word under cursor

Automatic — all occurrences of the word under your cursor are highlighted. Helps you quickly spot where a variable or function is used.

lualine — statusline

Always visible at the bottom. Shows the current mode, git branch, filename, file type, cursor position, and diagnostics.

Terminal & Environment

toggleterm — embedded terminal

Command	Action
:ToggleTerm	Toggle a persistent terminal at the bottom

The terminal persists its state between toggles, so running processes stay alive.

direnv — automatic environment loading

Automatic — when you open a project with a .envrc, Neovim loads the environment variables and nix shell automatically. No action needed.

Language Support

Treesitter — syntax-aware highlighting

Automatic — provides accurate syntax highlighting, indentation, and code folding for all supported languages. Much better than regex-based highlighting.

Nix — Nix language support

Automatic — syntax highlighting, error checking, and formatting for .nix files.

OpenSCAD — 3D modeling language support

Automatic — syntax highlighting for .scad files.

AI

CodeCompanion — AI assistant

Command	Action
:CodeCompanionChat	Open an AI chat buffer
:CodeCompanionActions	Browse available AI actions

Use it for inline code suggestions, explanations, and refactoring help directly inside the editor.