Spell Check With Vim

I write each post for this blog in Vim. Writing in the terminal makes me feel like a programmer, even when I’m not specifically programming.

I spellcheck each post with Vim, too. Vim’s basic spellchecking tool is at least as good as the ’90s word processors I grew up with. It helps me catch almost ever typo.

In this post, I’d like to share my Vim spellcheck workflow.

Enable Spelling

Vim’s spelling help page is extensive, and can be viewed at:

:help spell

It suggests enabling spelling like this:

:setlocal spell spelllang=en_us

When you to this, you’ll see words that Vim considers misspelled highlighted in red.

I enable spellchecking always in these markdown files, via a group in my annotated .vimrc:

" ~/.vimrc

augroup filetype_docs
  autocmd!
  autocmd FileType markdown setlocal spell
augroup END

If you aren’t sure if spelling is enabled, check it with:

:set spell?

If this returns spell, spelling is enabled. nospell, disabled.

Fix Misspellings

Navigate between spelling mistakes with ]s and [s in normal mode.

To fix a misspelling, put your cursor over the word and type z= to see a list of suggested replacements. Each replacement has a number, and you can choose a replacement by typing its number:

Change "cryin" to:
 1 "Crying"
 2 "Cry in"
 3 "Cr yin"
 4 "Crayon"
 5 "Ryan"

Type “1” to choose “Crying.”

Teach Vim Words

Hang on now; I’m transcribing an Aerosmith song and I need my editor to stop complaining about “cryin.” That’s a word, as far as this blog is concerned.

This mismatch happens in programming with words like “auth” and “navbar”– these may not be words in the dictionary, but they’re part of my professional lexicon and I don’t need my editor telling me they are misspellings.

To fix this, put your normal mode cursor on “cryin” and type zg. This adds the word to an allow-list of words that are considered okay.

To undo this action use zw, which comments out the line in the dictionary file. You can also remove the entry by hand from the spell file (~/.vim/spell/en.utf-8.add for me).

Repeat Fixes

If you made a good fix with z=, you can repeat that replacement for all matches of the replaced word in the current window:

:spellr[epall]

Select First Suggestion

Often, the first suggestion Vim makes is the one that I choose. Consider a word like ‘Rubysit’, a transposition error of ‘Rubyist.’ I’ve added that word to my dictionary of course, and that’s what Vim spell is almost certainly going to suggest first to me. For errors like this, I’d like to skip the word picker.

To bypass the picker and apply the first suggestion, put your normal-mode cursor over the bad word and type 1z=.

Your Turn

There’s a lot more to Vim spell than I’ve covered today. To learn all about it, check out the help page.

How do you use Vim spelling?