General Functionality

First I set the mapleader to comma so that it applies for all my mappings. I set hidden to allow for unsaved background tabs, and spell so that I don’t reveal my horrible spelling to the world. Turns out you can set new splits to be on the left, so I turn that on (we live in a world of widescreen monitors, how is this not the default?), and I turn on persistent undo files. All that looks like this:

" Built-In Functionality
"" General
let mapleader = ','

set hidden " Allow background buffers without saving
set spell spelllang=en_us
set splitright " Split to right by default

Text-Wrapping

In general, I want things wrapped at 79 characters—enough, in fact, that it’s easier for me to turn it off when I don’t want it than turn it on when I do. I also like having a highlighted column at 80 characters as a visual guide. I always want hard wraps, so I turn off soft-wrapping.

"" Text Wrapping
set textwidth=79
set colorcolumn=80
set nowrap

Search and Substitutions

I find I want the g flag in my s/ commands far more often than I don’t, so I set it to be on by default. I use highlight searches because that’s half the point, and use the handy combination of ignorecase and smartcase to ignore case when I type in lowercase, but not when I type in capital letters. I also have my first mapping here: comma-space for clearing the highlighted searches. It makes a nice slapping noise, which I quite enjoy, as if to say get that out of here.

"" Search and Substitute
set gdefault " use global flag by default in s: commands
set hlsearch " highlight searches
set ignorecase 
set smartcase " don't ignore capitals in searches
nnoremap <leader><space> :nohls <enter>

Tabs

Because I am not a horrible human being who hates joy and love and light, I use four spaces instead of tabs whenever I can³. The following combo will do that, and should be required by law.

"" Tabs
set tabstop=4
set softtabstop=4
set shiftwidth=4
set expandtab

Backup, Swap, and Undo

The next section might be a little controversial. Backup files, swap files, and undo files are great features of vim, but I hate having them clutter up my actual work directories. This isn’t so bad on Linux, where hidden files are simple things, but on Windows, which will incomprehensibly ignore leading dots when doing file completion, it’s awful. So, after I turn on undo files for persistent undo across sessions, I set folders inside my vim folder to hold all of these (see implementation notes at the end to see how I make empty folders with with Git).

"" Backup, Swap and Undo
set undofile " Persistent Undo
if has("win32")
    set directory=$HOME\vimfiles\swap,$TEMP
    set backupdir=$HOME\vimfiles\backup,$TEMP
    set undodir=$HOME\vimfiles\undo,$TEMP
else
    set directory=~/.vim/swap,/tmp
    set backupdir=~/.vim/backup,/tmp
    set undodir=~/.vim/undo,/tmp
endif

NetRW

Some folks won’t like this section either, because it’s about NetRW, vim’s file explorer. It gets more hate than it deserves, but I find it useful⁴. I set it to have the detail view with human-readable file sizes. The hiding behavior is a little odd, so I just tell the explorer to hide dotfiles, and to set them as hidden by default (this can be toggled with a). Then I turn off the banner. I also add a mapping to start the explorer; the exclamation point means that if the current buffer has unsaved changes, the Explorer will split vertically instead of horizontally.

""" NetRW
let g:netrw_liststyle = 1 " Detail View
let g:netrw_sizestyle = "H" " Human-readable file sizes
let g:netrw_list_hide = '\(^\|\s\s\)\zs\.\S\+' " hide dotfiles
let g:netrw_hide = 1 " hide dotfiles by default
let g:netrw_banner = 0 " Turn off banner
""" Explore in vertical split
nnoremap <Leader>e :Explore! <enter>

General Mappings

To wrap-up the built-in functionality, I have my general mappings. Mapping a semicolon to the colon in normal mode is surprisingly useful. I use control-H and -L to cycle through my buffers, because that feels like moving left and right to me. I use comma-q to quit a buffer and comma-w to save. Finally, I use comma x to access the copy buffer, which allows me to copy and paste between vim and other programs. That last is the only mapping which I have set to work in all modes, and I use it all the time.

"" Mappings
nnoremap ; :
nnoremap <C-H> :bp <enter>
nnoremap <C-L> :bn <enter>
nnoremap <Leader>w :w <enter>
nnoremap <Leader>q :bd <enter>

noremap <Leader>x "+

Python Version

I use Python 3 more or less exclusively. Many of the libraries I use most are (finally) moving to require it, and I like it better anyway. So I have this little autocommand group to set my omnicompletion to Python 3:

"" Python Version
augroup python3
    au! BufEnter *.py setlocal omnifunc=python3complete#Complete
augroup END

Plugin Manager

Once upon a time, I installed plugins manually. Then I used my package manager and a script called vim-plugin-manager. Then Tim Pope wrote Pathogen, and like the rest of the world, I switched to it immediately. Then Vundle came along with its Git-driven management, and I happily used that until I started this project.

When I went to see what was out there, I found that Vundle was still a good option, but I was charmed by the simplicity of VimPlug, which didn’t need any rtp manipulation in my .vimrc and could do parallel installations and updates. I decided it was worth making the switch.

This breaks my rule a little bit about preferring built-in functionality; Vim 8 does have a built-in plugin manager of sorts. Unfortunately it would mean taking a step back: there’s no way to keep your plugins updated and I just don’t want to go back to doing it manually and fiddling with submodules in my vimfiles repository. So VimPlug it is! The entirety of my plugin installation section looks like this:

" Plugins 

"" Installation with VimPlug
if has("win32")
    call plug#begin('~/vimfiles/plugged')
else
    call plug#begin('~/.vim/plugged')
endif

""" Basics
Plug 'tpope/vim-sensible'
Plug 'sheerun/vim-polyglot'
Plug 'flazz/vim-colorschemes'

""" General Functionality
Plug 'lifepillar/vim-mucomplete'
Plug 'scrooloose/syntastic'
Plug 'sirver/ultisnips'
Plug 'honza/vim-snippets'
Plug 'tpope/vim-commentary'
Plug 'chiel92/vim-autoformat'

""" Particular Functionality
Plug 'junegunn/goyo.vim'
Plug 'junegunn/limelight.vim'
Plug 'vim-pandoc/vim-pandoc-syntax'
Plug 'godlygeek/tabular'

call plug#end()

I’ll walk through each of those in more detail and give the configuration I have for each. As you can see above, I group my plugins into three groups: basics, which include simple settings, filetype and syntax, and color schemes; general functionality plugins, which add features that are generally useful when editing code or writing text, and particular functionality plugins, when are only useful in particular situations.

Basics

I’ve already mentioned Tim Pope’s excellent Vim-Sensible plugin, which there’s really no downside to installing. It just gives you a lot of sane defaults, and the code is perfectly readable if you want the details.

Vim-Polyglot and Vim-Colorschemes are both omnibus packages. Essentially, they’re curated lists. At first this seemed like overkill to me—why not just install the ones I want? But then I remembered just how many times I’ve switched to a new language and found that either vim didn’t have a filetype for it, or that the user community had a few fixes for the built-in version of indentation or something. Vim-Polyglot collects all of the best of those, and that just saves me having to do it later. Similarly, Vim-Colorschemes has at least one color scheme you will like, even if you’re as picky as I am⁵. I turn on gui-style colors for the terminal and use the Darth style:

"" Colors
set termguicolors
colorscheme darth

General Functionality Plugins

"" Autocompletion
set completeopt=menuone,noinsert,noselect
set shortmess+=c " Turn off completion messages

inoremap <expr> <c-e> mucomplete#popup_exit("\<c-e>")
inoremap <expr> <c-y> mucomplete#popup_exit("\<c-y>")
inoremap <expr>  <cr> mucomplete#popup_exit("\<cr>")

let g:mucomplete#enable_auto_at_startup = 1 

call add(g:mucomplete#chains['default'], 'ulti')

"" Autoformat
au! BufWrite * :Autoformat
let g:autoformat_autoindent = 0
let g:autoformat_retab = 0
let g:autoformat_remove_trailing_spaces = 0

augroup markdown_flavor
    au! BufNewFile,BufFilePre,BufRead *.md 
                \ let b:markdown_flavor="markdown"
    au! BufNewFile,BufFilePre,BufRead *.markdown
                \ let b:markdown_flavor="markdown"
    au! BufNewFile,BufFilePre,BufRead */blog/*.markdown
                \ let b:markdown_flavor="markdown_github".
                \"+footnotes".
                \"+yaml_metadata_block".
                \"-hard_line_blocks"
augroup END

let g:formatdef_pandoc =
            \'"pandoc  --standalone --atx-headers --columns=79'.
            \' -f markdown -t ".b:markdown_flavor'
let g:formatters_markdown_pandoc = ['pandoc']

Particular Plugin Functionality

"" Goyo & Limelight
autocmd! User GoyoEnter Limelight
autocmd! User GoyoLeave Limelight!

"" Pandoc
augroup pandoc_syntax
    au! BufNewFile,BufFilePre,BufRead *.md set filetype=markdown.pandoc
    au! BufNewFile,BufFilePre,BufRead *.markdown set filetype=markdown.pandoc
augroup END

let g:pandoc#syntax#conceal#use = 0
let g:pandoc#syntax#codeblocks#embeds#langs = ['python', 'vim', 'make',
            \  'bash=sh', 'html', 'css', 'scss', 'javascript']