I spent some time trying to figure out vim configuration. I didn’t want to just copy stuff from Stack Overflow or GitHub without really understanding what’s going on. Some people use default vim which is honestly pretty bare, others have these massive configs that do god knows what. So I decided to make something in between - a config that’s modern and actually documented properly.

The whole thing is organized in sections with comments explaining what each option does. I learned a lot just by going through vim’s documentation and picking what made sense. It works out of the box because it creates all the needed directories automatically. If you’re starting with vim or want to clean up your config, this is a pretty solid baseline I think.

" ============================================================================
" VIM CONFIGURATION - Koenraad
" ============================================================================

" ----------------------------------------------------------------------------
" 1. COMPATIBILITY & FEATURES
" ----------------------------------------------------------------------------
set nocompatible                " Disable Vi compatibility for enhanced features
syntax on                       " Enable syntax highlighting
filetype plugin indent on       " Enable filetype detection, plugins, and indent

" ----------------------------------------------------------------------------
" 2. XDG BASE DIRECTORY COMPLIANCE
" ----------------------------------------------------------------------------
let g:netrw_home=$XDG_STATE_HOME.'/vim'
set viminfofile=$XDG_STATE_HOME/vim/viminfo

" ----------------------------------------------------------------------------
" 3. UI & DISPLAY
" ----------------------------------------------------------------------------
colorscheme desert              " Color scheme
set number                      " Show absolute line numbers
set relativenumber              " Show relative line numbers
set ruler                       " Show cursor position in status line
set showcmd                     " Show incomplete commands in bottom right
set showmode                    " Show current mode in command line
set laststatus=2                " Always show status line
set cmdheight=1                 " Height of command line
set display=lastline            " Show as much as possible of last line
set cursorline                  " Highlight current line
set colorcolumn=80,120          " Visual guides at columns 80 and 120
set scrolloff=8                 " Keep 8 lines above/below cursor
set sidescrolloff=8             " Keep 8 columns left/right of cursor
set list                        " Show invisible characters
set listchars=tab:→\ ,trail:·,nbsp:␣,extends:›,precedes:‹
set showmatch                   " Briefly jump to matching bracket
set matchtime=2                 " Tenths of second to show matching bracket
set title                       " Set window title to filename
set titlestring=%<%F%=%l/%L-%P  " Title format: filename and position
set visualbell                  " Use visual bell instead of beeping
set noerrorbells                " Disable error bells

" ----------------------------------------------------------------------------
" 4. TEXT EDITING & INDENTATION
" ----------------------------------------------------------------------------
set tabstop=2                   " Number of spaces a <Tab> counts for
set shiftwidth=2                " Number of spaces for each step of autoindent
set softtabstop=2               " Number of spaces <Tab> uses in insert mode
set expandtab                   " Use spaces instead of tabs
set smarttab                    " Smart tab behavior at start of line
set autoindent                  " Copy indent from current line to new line
set smartindent                 " Smart autoindenting for C-like programs
set backspace=indent,eol,start  " Allow backspacing over everything
set formatoptions=tcqrn1        " Text formatting options
set textwidth=0                 " Disable automatic line breaking (0 = off)
set wrapmargin=0                " Disable line wrapping by margin
set wrap                        " Visually wrap long lines
set linebreak                   " Wrap at word boundaries
set breakindent                 " Preserve indentation in wrapped lines
set joinspaces                  " Insert two spaces after period when joining
set nostartofline               " Keep cursor column when moving vertically

" ----------------------------------------------------------------------------
" 5. SEARCH
" ----------------------------------------------------------------------------
set hlsearch                    " Highlight all search matches
set incsearch                   " Show matches as you type
set ignorecase                  " Case-insensitive search by default
set smartcase                   " Override ignorecase if pattern has uppercase
set wrapscan                    " Search wraps around end of file
set magic                       " Enable magic characters in patterns
set gdefault                    " Use 'g' flag by default with :s

" ----------------------------------------------------------------------------
" 6. FILE HANDLING
" ----------------------------------------------------------------------------
set nobackup                    " Don't keep backup files after writing
set writebackup                 " Create backup during write operation (safer)
set swapfile                    " Enable swap files for crash recovery
set directory=$XDG_STATE_HOME/vim/swap//  " Centralized swap file location
set autoread                    " Auto-reload files changed outside vim
set autowrite                   " Auto-write file when switching buffers
set hidden                      " Allow switching buffers without saving
set encoding=utf-8              " Internal character encoding
set fileencoding=utf-8          " Default file encoding
set fileformats=unix,dos,mac    " Preferred end-of-line formats
set modeline                    " Enable modelines for per-file settings
set modelines=5                 " Check first/last 5 lines for modeline

" ----------------------------------------------------------------------------
" 7. UNDO & HISTORY
" ----------------------------------------------------------------------------
set undofile                    " Enable persistent undo
set undodir=$XDG_STATE_HOME/vim/undo
set undolevels=10000            " Maximum number of changes that can be undone
set undoreload=10000            " Maximum lines to save for undo on buffer reload
set history=10000               " Command line history size

" ----------------------------------------------------------------------------
" 8. PERFORMANCE
" ----------------------------------------------------------------------------
set re=0                        " Use new regular expression engine
set lazyredraw                  " Don't redraw during macros/scripts
set ttyfast                     " Fast terminal connection
set updatetime=300              " Faster completion (default 4000ms)
set timeoutlen=500              " Time to wait for mapped sequence (ms)
set ttimeoutlen=10              " Time to wait for key code sequence (ms)

" ----------------------------------------------------------------------------
" 9. COMPLETION & WILDMENU
" ----------------------------------------------------------------------------
set wildmenu                    " Enhanced command-line completion
set wildmode=longest:full,full  " Complete longest common string, then full match
set wildignore=*.o,*.obj,*~,*.pyc,*.swp,*.bak,*.class,*.git
set wildignorecase              " Ignore case in command-line completion
set complete=.,w,b,u,t          " Where to scan for completion
set completeopt=menu,menuone,noselect,preview
set pumheight=15                " Maximum items in popup menu

" ----------------------------------------------------------------------------
" 10. FOLDING
" ----------------------------------------------------------------------------
set foldenable                  " Enable folding
set foldmethod=indent           " Fold based on indentation
set foldlevel=99                " Start with all folds open
set foldlevelstart=99           " Open all folds when opening file
set foldnestmax=10              " Maximum fold nesting
set foldcolumn=1                " Show fold column

" ----------------------------------------------------------------------------
" 11. WINDOWS & SPLITS
" ----------------------------------------------------------------------------
set splitbelow                  " Open horizontal splits below
set splitright                  " Open vertical splits to the right
set winheight=10                " Minimum height of current window
set winminheight=1              " Minimum height of inactive windows
set winwidth=20                 " Minimum width of current window
set winminwidth=1               " Minimum width of inactive windows
set equalalways                 " Make all windows equal size after split/close

" ----------------------------------------------------------------------------
" 12. MOUSE & CLIPBOARD
" ----------------------------------------------------------------------------
set mouse=a                     " Enable mouse in all modes
set clipboard=unnamed           " Use system clipboard for yank/put
set ttymouse=xterm2             " Mouse handling for xterm-like terminals

" ----------------------------------------------------------------------------
" 13. BUFFER & SESSION
" ----------------------------------------------------------------------------
set sessionoptions=buffers,curdir,folds,help,tabpages,winsize
set viminfo='100,<50,s10,h      " viminfo settings: marks, registers, etc.

" ----------------------------------------------------------------------------
" 14. MISC OPTIONS
" ----------------------------------------------------------------------------
set shortmess+=I                " Don't show intro message when starting
set belloff=all                 " Never ring the bell for any reason
set confirm                     " Ask for confirmation instead of failing
set virtualedit=block           " Allow cursor anywhere in visual block mode
set report=0                    " Always report number of lines changed
set synmaxcol=500               " Only highlight first 500 columns (performance)
set conceallevel=0              " Don't conceal text
set signcolumn=yes              " Always show sign column (for linters, git, etc)
set showtabline=1               " Show tabline only if there are 2+ tabs

" Create required directories if they don't exist
if !isdirectory($XDG_STATE_HOME . '/vim')
    call mkdir($XDG_STATE_HOME . '/vim', 'p', 0700)
endif

if !isdirectory($XDG_STATE_HOME . '/vim/undo')
    call mkdir($XDG_STATE_HOME . '/vim/undo', 'p', 0700)
endif

if !isdirectory($XDG_STATE_HOME . '/vim/swap')
    call mkdir($XDG_STATE_HOME . '/vim/swap', 'p', 0700)
endif

Here’s what I think makes it good:

• XDG compliance - this was important for me because I hate when vim leaves files everywhere. Now all the swap files, undo history, everything goes into ~/.local/state/vim/ and my projects stay clean
• You won’t lose your work - I enabled persistent undo (10,000 levels!) and swap files for crash recovery. Before I had swap files disabled because they annoyed me, but putting them in a separate folder solved that problem. Now if vim crashes or my laptop dies I can recover everything
• Modern stuff that just works - mouse support, system clipboard (super useful), smart search where it’s case-sensitive only when you type uppercase letters. Also splits open where you expect them (below and right)
• Performance tweaks - reduced the timeout delays and enabled lazy redraw, makes vim feel much snappier especially when running macros

When you open a file you’ll see numbers and symbols like |, -, 2, 3 in the left gutter. That’s the fold column (foldcolumn=1) showing your code’s indentation structure. The numbers show how many levels deep each line is indented - super useful for seeing code structure at a glance. You also get a sign column for linters, git, etc. and relative line numbers in a separate column which makes vim motions like 5j or 3k way easier. If the fold column bothers you just set it to 0, but I find it helpful once you understand what it means.