20.Spell Checker

I have a couple of problems with the spell check inside Neovim: a, pressing [s or ]s appears to skip apparent spell errors inside a Markdown list (ordered or unordered); and b, the inline code style appears to overwrite the error style, therefore you don't see that red wavy line beneath the miss-spelled words, if they are surrounded by a pair of backticks.

Tip 120. Spell Check Your Work

With the spell checker enabled, Vim flags words that are not in its spell file. We can quickly jump between spelling mistakes and have Vim suggest corrections.

Command	Effect
]s	Jump to next spelling error
[s	Jump to previous spelling error
z=	Suggest corrections for current word
zg	Add current word to spell file (as good word)
zw	Remove current word from spell file (as bad word)
zug	Revert zg or zw command for current word

Tip 121. Use Alternate Spelling Dictionaries

Out of the box, Vim’s spell checker supports regional variations of English. Find out how to specify the region and how to obtain spelling dictionaries for other languages.

Specify a Regional Variant of a Language

Obtain Spell Files for Other Languages

Tip 122. Add Words to the Spell File

Vim’s spelling dictionaries are not comprehensive, but we can augment them by adding words to a spell file.

Create a Spell File for Specialist Jargon

With the spellfile option, we can specify the path of the file where Vim tracks words added or removed using the zg and zw commands (see :h spellfile ).

Vim allows us to specify more than one spell file simultaneously, which means we can maintain multiple word lists.

When I’m ready to check the spelling in a chapter of this book, I source a file containing these lines of configuration:

setlocal spelllang=en_us
setlocal spellfile=~/.config/nvim/spell/en.utf-8.add
setlocal spellfile+=~/books/practical_vim/jargon.utf-8.add

For each word that the spell checker flags incorrectly, I now have a choice. I could press 2zg to add it to my list of Vim terminology, or 1zg to add it to the default word list.

In which directory do you want to write the spell file?

By default, when press zg on macOS

• Word 'Accor' added to ~/.local/share/nvim/site/spell/en.utf-8.add

By default, when press zg on Windows

• Word 'Neovim' added to ~\AppData\Local\nvim/spell/en.utf-8.add

What about the ~/.local/share/nvim/site/spell/en.utf-8.add.spl file?

To be answered...

Can I directly edit the en.utf-8.add file by adding or deleting words?

To be answered...

Should I store the spell file under the nvim configuration directory for portability considerations?

To be answered...

Fix Spelling Errors from Insert Mode

Yourr mum has a moustache.

Yourr mum has a moustache.

• <C-x>s
• <C-x><C-s>

When with set spelllang=en_us,cjk, why is the misspelled "Yourr" not caught as a spell error by Neovim?

When such spell errors are within a code block or a list, spell check appears to be ignored; when the same spell errors are in the natural context, it will be caught as normal.

This is indeed a default and intentional behavior in Neovim (and Vim) and can be changed with additional configuration.

1. Why it's the Default Behavior

Neovim's built-in spell checker is syntax-aware. It uses the file's syntax definitions to determine which parts of the text should be spell-checked and which should be ignored.

• Markdown Text: Regular paragraphs, headings, and lists are considered general text and are included in the spell check.
• Code Blocks: The default syntax file for Markdown is configured to exclude fenced code blocks (lines between triple backticks ```) from the spell-check region. This is done to prevent programming terms, variable names, and code syntax from being highlighted as spelling errors, which would be extremely noisy and disruptive.

2. How to Enable Spell Check in Markdown Code Blocks

You need to modify the syntax definition for Markdown files to explicitly include the code block region in the spell-check cluster. This is typically done in an autocommand or a filetype plugin for markdown (~/.config/nvim/after/ftplugin/markdown.vim or ~/.config/nvim/after/ftplugin/markdown.lua).

The Vimscript Solution (The most direct way)

You can use the :syntax command to manually add the code block region to the @Spell cluster.

Configuration File: ~/.config/nvim/after/ftplugin/markdown.vim

" This command modifies the 'markdownCodeBlock' syntax group
" to include the @Spell cluster, forcing spell-checking inside it.
syntax include @Spell markdownCodeBlock

In modern Neovim versions, especially if you are using Treesitter for syntax highlighting, the exact name of the syntax group might vary, but a common group that covers fenced code blocks is often something like markdownCodeBlock or markdownCode.

The Lua/Treesitter-Aware Approach

If you use a modern Neovim setup with Tree-sitter for markdown highlighting (which is common), the syntax groups are managed differently. A more robust solution might involve adjusting the spell-check scope for the buffer in Lua, or using a separate dedicated spell-checking plugin.

A simple Lua filetype configuration to set the buffer-local option and then include the code region could look like this (though the exact syntax group name may still need verification based on your setup):

Configuration File: ~/.config/nvim/after/ftplugin/markdown.lua

-- Enable local spell check for markdown files
vim.opt_local.spell = true
vim.opt_local.spelllang = { "en_us" }

-- Attempt to include the code block syntax group in the spell check
-- Note: 'markdownCodeBlock' is a common Vim/Treesitter name, but you may need to check your exact setup.
vim.cmd [[syntax include @Spell markdownCodeBlock]]

3. Alternative for Code (Plugin Solution)

If your goal is to have intelligent spell checking within code (e.g., checking function and variable names in any language), you should consider a dedicated plugin like cspell.nvim (which uses the cSpell command-line tool).

• Plugins like cspell.nvim are specifically designed to perform "code spell-checking."
• They can split camelCase or snake_case identifiers and check the individual words (my_long_variable_name would be checked as "my", "long", "variable", "name").
• This is generally a more powerful solution for code-related spell-checking than trying to override the default built-in spell checker's syntax exclusion.