Spell Checking with Vim: Tutorial and Best Practices

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. In this post, I’ll share how I spellcheck in Vim.

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 in red.

I enable spellchecking always in the markdown files I use to write this blog via a group in my .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, it’s 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 it Doesn’t Know

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 kind of mismatch happens in programming with words like “auth” and “navbar.” They may not be words in the dictionary, but they’re part of my work and I don’t benefit from my editor telling me they are misspellings. What to do?

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 in my native language).

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 the 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 the latter to my dictionary of course, and that’s what Vim spell is almost certainly going to recommend first to me. For repetitive typos like this, I’d like to skip the word picker and just apply the first suggestion.

To do so, 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.

• Vim