How to spell check in Vim

The salsa verde post goes up on the Byte Burrito blog at noon. You wrote it in Vim, in salsa-verde.md, under the heading # New at Byte Burrito: salsa verde. It says the salsa is "definately tangy enough for everyone else", and further down it promises that anyone who orders a carnitas burrito will "recieve a free horchata". You'd rather Vim found those than a customer.

Type :set spell and press ↵, and every word Vim doesn't know gets marked. Neovim draws a wavy line under it. Vim in a terminal colours the word's background instead, and your colour scheme can change either. A sentence that starts without a capital gets a mark of a different colour, and so does a word spelled the way another country spells it. :set nospell takes the marks away, and :set spell! flips between the two.

Vim checks English to start with, and that list accepts both colour and color. Pick a country and the other spelling gets marked: :set spelllang=en_gb for British English, :set spelllang=en_us for American. en_ca, en_au and en_nz work too, from the same English list that comes with Vim and Neovim.

]s moves the cursor to the next misspelled word, and [s to the one before. Past the last one, ]s carries on from the top of the file and says search hit BOTTOM, continuing at TOP, so you can keep pressing it until you're back where you began.

On a marked word, z= lists Vim's guesses, numbered, under Change "recieve" to:. Type a number and press ↵, or press ↵ on its own to leave the word alone. When you trust the first guess, 1z= takes it without showing the list. If the same typo turns up again, reach it with ]s and . makes the same replacement there, and :spellrepall fixes every other copy of that misspelling in the window at once.

You can also fix a word while you're still typing it. In Insert mode, Ctrl-xs swaps the word before the cursor for Vim's first guess and opens a menu of the others. Ctrl-n and Ctrl-p step through it, and you carry on typing when it's right.

Most of the words ]s stops on in the salsa post aren't mistakes. tomatillos, carnitas and horchata are on the menu, and Vim's English list has never heard of them. With the cursor on one, zg adds it to your own word list (g for good), and the word stops being marked everywhere, in this file and every file you open after.

zw does the opposite, for a real word you never mean. The menu keeps offering Churros for desert, and Vim has no reason to object to desert. zw on it marks the word wrong from then on, and 1z= on it gives dessert.

Pressed zg on recieve by mistake? zug takes the word back out of your list, and it undoes a zw the same way.

This is one pass through the salsa post, from the heading down, with ]s between each stop.

Your words go in a plain text file, one per line: ~/.vim/spell/en.utf-8.add in Vim, ~/.config/nvim/spell/en.utf-8.add in Neovim. The name comes from the language without the country, so en_gb and en_us share one list, and Vim keeps a compiled copy, en.utf-8.add.spl, next to it. Put the .add file in your dotfiles and your words come with you to the next machine. If you edit it by hand, open it in Vim and run :mkspell! % so the compiled copy catches up.

If zg answers E764: Option 'spellfile' is not set, Vim found nowhere to write, which happens when ~/.vim doesn't exist yet. Type :!mkdir -p ~/.vim/spell and press ↵, then zg again.

You may want spelling only where you write sentences, in blog posts and commit messages, and not in every file you open. For that, add two lines to ~/.vimrc:

• filetype plugin indent on
• autocmd FileType markdown,gitcommit setlocal spell

The second line turns spelling on whenever a Markdown file or a Git commit message opens, and setlocal keeps it to that window. The first switches on file type detection, which Vim stops doing by itself as soon as you have a vimrc, and without it the autocmd never runs. Add set spelllang=en_gb there too, to keep your country's spelling.

Neovim works out file types already, so it needs one line in init.lua:

• vim.api.nvim_create_autocmd('FileType', { pattern = { 'markdown', 'gitcommit' }, command = 'setlocal spell' })

If you keep settings for each file type in their own files, after/ftplugin/markdown.vim under ~/.vim or ~/.config/nvim, holding the line setlocal spell, does the same for Markdown.

In code, with syntax highlighting on, Vim checks only the parts the language's syntax file marks for spelling. In a JavaScript file that means the comments, so a misspelled variable name goes unmarked.

The menu is half Spanish, so :set spelllang=en_gb,es checks both languages at once. Vim and Neovim come with the English list only, and the first time you ask for another one, both offer to download it. Say yes and the list goes in a spell folder of yours, and if you have more than one, Vim asks which. With none yet, Vim offers to create ~/.vim/spell and Neovim uses ~/.local/share/nvim/site/spell.

The download goes through netrw, the file browser that comes with both. Some Neovim file-tree plugins ask you to turn netrw off, and then nothing is offered and Spanish goes unchecked. You can fetch the file yourself instead, es.utf-8.spl from https://ftp.nluug.nl/pub/vim/runtime/spell/, into that folder.