Vim Spelling Guide

Contents

• Introduction
  • Toggle Spell Checking with a Keymap
  • Use Autocommand
• Specify Language and Region
• Highlight
• Navigate
• Correct spelling
  • Spell Suggestions
    • Suggestion Keybinding
    • Modify Suggestions
  • Abbreviations
• Spell File
  • Good and wrong words
• Conclusion

Introduction

Enable spell checking in Vim with :set spell or locally in the current buffer with :setlocal spell.

Do the same in Neovim with vim.o.spell = true

Disable spell checking with :set nospell

Note that Vim checks words for spelling, not grammar.

Toggle Spell Checking with a Keymap

You can bind keys to toggle between spell checking mode.

Example in Vim:

nnoremap <silent> <F2> :set spell!<CR>
inoremap <silent> <F2> <C-o>:set spell!<CR>

Example in Neovim:

map('n', '<Leader>=', ':set spell!<CR>', {desc='Spell check'})

Use Autocommand

You can create an Autocommand to enable spell checking in specified file types.

Example in Vim:

autocmd BufRead,BufNewFile *.txt,*.md,*.tex setlocal spell

Example in Neovim:

-- spellcheck
autocmd({'BufRead', 'BufNewFile'}, {
    pattern = { '*.txt', '*.md', '*.tex'},
    command = 'setlocal spell' } )

Specify Language and Region

Specify a comma separated word list for Vim to include in spell checking with :set spelllang or :set spl.

Examples:

Use International English:set spl=en

Use British English: :set spll=en_gb

Other English regions available: en_au, en_ca, en_nz, en_us.

Include German and Russian: :set spl=en,de,ru

Include East Asian characters: :set spl=en,cjk

Highlight

Vim highlight the following mistyped words:

1. Word not recognized (hl-SpellBad)
2. Word not capitalised with (hl-SpellCap)
3. Rare word with (hl-SpellRare)
4. Wrong spelling for selected region with (hl-SpellLocal)

Navigate

]s - go to next misspelled word after cursor.

[s - go to previous misspelled word before cursor.

]S and [S - ignores rare and non-region words.

You can use a count for them. For example, 3]s will go to the third misspelled word after cursor.

Correct spelling

Spell Suggestions

z= - show a list of word/correction suggestions for word under cursor. Press a number from the list to replace the word.

1z= - automatically correct word under cursor with the first suggestion.

CTRL-X s - show Insert Mode autocompletion of word suggestions.

After replacing a word with z= or CTRL-X s, replace all similar words using :spellr[epall].

Suggestion Keybinding

Below is an example of a genius keybinding in Neovim that I borrowed from this post.

Fix the most recent mistyped word pressing CTRL-Z in Insert mode:

inoremap <C-z> <C-g>u<Esc>[s1z=`]a<C-g>u

This jumps to the previous mistyped word [s, then replaces the word with the first suggestion with 1z=, then returns to initial cursor position with `]a. The <C-g>u enables to undo the correction.

The same keybinding in Neovim:

map('i', '<C-z>', '<C-g>u<Esc>[S1z=`]a<C-g>u', {desc='Fix spelling'})

Modify Suggestions

Vim shows a staggeringly long list of suggestions. Restrict the number of suggestions the spellsuggest or sps options.

Examples:

set sps=best,5 - Use best method and limit suggestions to 5.

set sps=fast,10 - Use fast method and limit suggestions to 10.

set sps=file:~/path/to/custom/suggestions,best - Specify a custom file for suggestions.

The file should list words in the following format: incorrect/correct. For example, misstake/mistake. Vim ignores lines without a /, and acts as comments.

set sps=expr:MySuggest() - Specify a custom function for suggestions.

The function includes a list of expressions, each with a sub-list of suggestions and score. Vim then uses the score to determine which suggestion to pick. The lower the score, the better. Check the official documentation for more.

Abbreviations

Some people prefer abbreviations to correct frequently mistyped words.

Example of abbreviations in Vim:

iabbrev manteinance maintenance
iabbrev adn and
iabbrev funtcion function
iabbrev retunr return

Spell File

Vim looks for spell files in the spell/ subdirectory of in runtimepath.

We can add words to the spellfile and an internal wordlist.

The Internal wordlist is local to buffers, and will clear when closed.

Good and wrong words

Add word as ‘good’ to the spellfile:
zg or :spe[llgood] <word>

Add word as ‘good’ to the internal wordlist:
zG or :spe[llgood]! <word>

Add word as ‘wrong’ to the spellfile:
zw or :spellw[rong] <word>

Add word as ‘wrong’ to the internal wordlist:
zW or :spellw[rong]! <word>

Add word as ‘rare’ to the spellfile:
:spellrare <word> or :spellr <word>

Undo previous operations:
zug, zuw, :spellundo <word>
zuG, zuW, :spellundo! <word>

Conclusion

Please consult the documentation for more (:help spell and :help dictionary).