Building on Vim’s spell-check and thesaurus/dictionary completion

Features of this plugin:

• Specify the languages to be used in spell-check
• Specify a list of thesauruses for synonym completion
• Specify a list of dictionaries for word completion
• Specify a list of spellfiles for custom word-check additions
• Opt-in key mappings for Normal mode thesaurus and dictionary completion
• Buffer-scoped configuration (leaves your global settings alone)

Though principally used as a editor for code, Vim flirts with those of us editing documentation and prose by providing spell-check as well as completion capabilities using both dictionary and thesaurus files.

While we can configure these settings in our .vimrc files, we often need more granular control, where defaults are leveraged and configuration is applied by file type to the current buffer. This plugin fills that gap.

You can install using your favorite Vim package manager. (E.g., Pathogen, Vundle, or Plug.) If you are using a recent version of vim or neovim, you can also use native package support. (See :help packages.)

Because spell-check, thesaurus, etc. isn’t needed for all file types, you can configure it per file type in your .vimrc:

set nocompatible
filetype plugin on       " may already be in your .vimrc

augroup lexical
  autocmd!
  autocmd FileType markdown,mkd call lexical#init()
  autocmd FileType textile call lexical#init()
  autocmd FileType text call lexical#init({ 'spell': 0 })
augroup END

In the last autocmd statement above, dictionaries and thesauruses are configured for the text file type, but spell-check is disabled by default.

lexical enables spell-check by default for buffers in which it is initialized. You can change that default setting in your .vimrc:

let g:lexical#spell = 1         " 0=disabled, 1=enabled

Vim’s global spelllang (note three ls) may already specify a default language. You can query it with a simple command:

:echo &spelllang
=> ‘en’

If desired, you can be more specific, overriding the global spelllang in your .vimrc:

let g:lexical#spelllang = ['en_us','en_ca',]

Available spell files can be found at ftp.vim.org. Vim will attempt to download those which are not installed locally. For more detail see

:help spellfile.vim

If you don’t have one already, download a thesaurus, such as Grady Ward’s Moby Thesaurus at Zeke's moby thesaurus, or on Project Gutenberg and extract the mthesaur.txt file. By default lexical will look for it at the following path:

let g:lexical#thesaurus = ['~/.vim/thesaurus/mthesaur.txt',]

You can specify multiple paths to thesauruses in the list.

On Unix-based systems (including OS X) the dictionary will default to:

let g:lexical#dictionary = ['/usr/share/dict/words',]

You can specify multiple paths to dictionaries in the list.

On Unix-based systems (including OS X) the spellfile will default to:

let g:lexical#spellfile = ['~/.vim/spell/en.utf-8.add',]

You can specify a single path for spellfile in the list.

Vim offers many standard key mappings for spell-checking and completion.

These are the Normal mode commands:

• ]s - Move to next misspelled word after the cursor.
• [s - Like ]s but search backwards
• ]S - Like ]s but only stop at bad words, not at rare words or words for another region.
• [S - Like ]S but search backwards.

With the following key mappings you can use Visual mode selection to select the characters (including whitespace). Otherwise the word under the cursor is used.

• zg - Mark as a good word

• zw - Like zg but mark the word as a wrong (bad) word.

• zug - Unmark as good word

• zuw - Unmark as wrong (bad) word

• z= - For the word under/after the cursor suggest correctly spelled words

• 1z= - Use the first suggestion, without prompting

• . - Redo - repeat last word replacement

• :spellr - Repeat the replacement done by z= for all matches with the replaced word in the current window

For spelling suggestions while in Insert mode:

• «CTRL-X» «CTRL-S» (or «CTRL-X» «s» for terminal users) - suggest spelling, using «CTRL-P» and «CTRL-N» to navigate.

For a convenient pop-up list of suggestions from Normal mode, you can map an available key of your choice in your .vimrc:

let g:lexical#spell_key = '<leader>s'

This buffer-scoped mapping is strictly opt-in. No key is mapped by default.

For thesaurus lookup while in Insert mode:

• «CTRL-X» «CTRL-T» - thesaurus lookup, using «CTRL-P» and «CTRL-N» to navigate.

For convenient Normal mode thesaurus lookup from the cursor position, you can map an available key of your choice in your .vimrc:

let g:lexical#thesaurus_key = '<leader>t'

This buffer-scoped mapping is strictly opt-in. No key is mapped by default.

For dictionary completion while in Insert mode:

• «CTRL-X» «CTRL-K» - dictionary completion, using «CTRL-P» and «CTRL-N» to navigate.

For convenient Normal mode dictionary lookup from the cursor position, you can map an available key of your choice in your .vimrc:

let g:lexical#dictionary_key = '<leader>k'

This buffer-scoped mapping is strictly opt-in. No key is mapped by default.

Sometimes you need a highly-customized environment for spell-check and completion. You can define your own commands in your .vimrc to meet that need. For example:

command! -nargs=0 LexMed call lexical#init({
                    \ 'spell': 1,
                    \ 'spelllang':  ['en', 'medical'],
                    \ 'dictionary': ['~/.vim/dictionary/medical_terms.txt',
                    \                '/usr/share/dict/words',
                    \               ],
                    \ 'thesaurus':  ['~/.vim/dictionary/medical_synonyms.txt',
                    \                '~/.vim/thesaurus/mthesaur.txt',
                    \               ],
                    \ 'spellfile':  ['~/.vim/spell/en.add'],
                    \ })

Then to quickly configure Vim for the current buffer, enter the command:

:LexMed

Where you are providing an explicit value, it will use that. Where you do not, it will fall back to your specified defaults or global settings.

The ervandew/supertab plugin will make these Insert mode completions available via the «tab» key.

If you find this plugin useful, you may want to check out these others originally by @reedes:

• vim-colors-pencil - color scheme for Vim inspired by IA Writer
• vim-litecorrect - lightweight auto-correction for vim
• vim-pencil - rethinking Vim as a tool for writers
• vim-textobj-quote - extends Vim to support typographic (‘curly’) quotes
• vim-textobj-sentence - improving on Vim's native sentence motion command
• vim-thematic - modify Vim’s appearance to suit your task and environment
• vim-wheel - screen-anchored cursor movement for Vim
• vim-wordy - uncovering usage problems in writing
• vim-wordchipper - power tool for shredding text in Insert mode

If you’ve spotted a problem or have an idea on improving this plugin, please post it to the GitHub project issue page.