Vim For Technical Writers Using Markdown

Recently, I have started using Vim for writing in Markdown. For me, Vim is a lightweight editor with fewer distractions, compared to LibreOffice, Microsoft Word, PyCharm or VSCode.

I use the vim-markdown plugin. This gives me syntax highlighting and table of contents. The table of contents can be displayed by issuing the :Toc command. I can also insert a table of contents for the document that I am writing by issuing the :InsertToc command. Take a look at the vim-markdown repository for further information.

How To Display A Visual Right Margin?

Within my vimrc I have set colorcolumn=80 to display a visual margin at the 80th column. This is also useful when writing source code.

How To Format Paragraph Width?

Some useful shortcut keys for formatting the width of paragraphs:

• vap: Visually select the paragraph block (excluding white-space) for the cursor.
• gqap: Autoformat the paragraph block to the correct width for the cursor.

How To Preview Markdown?

I use the vim-livedown plugin to preview Markdown files. When the Markdown file is updated, the preview in the browser updates.

The plugin requires nodejs with livedown installed globally. This can be setup as follows:

• yarn: yarn global add livedown
• npm: npm -g install livedown

I have configured a keyboard shortcut in my ~/.vimrc file to preview.

nmap gm :LivedownPreview

When I press gm, the Markdown file is rendered in the default browser.

Further configuration details can be found here

Spell Checker

I use the built-in Vim spell checker to highlight words that are not in the global and regional dictionaries. In the screenshot below spelling errors are highlight in red.

How To Perform A Spell Check?

For all open buffers the spell checker can be enabled with :set spell.

To activate spelling for the active buffer, use :setlocal spell.

It is also possible to use the spelllang parameter to specify the dictionary language. For example, :set spell spelllang=en_gb or :setlocal spell spelllang=en_gb.

How To Navigate Spelling Errors?

Use [s to move to the previous word and ]s to move to the next.

How To Add A Word To The Dictionary?

Move the cursor to the word and type zg

How To Remove A Word From The Dictionary?

Move the cursor to the word and type zw

How To Display A List of Suggestions?

Move the cursor to the word and type z=

How To Style Spelling Errors?

Highlight styles can be set for the following:

• SpellBad: Words not recognised by the spell checker
• SpellCap: Words that should start with a capital letter
• SpellLocal: Words recognised by spell checker as specific to the locale language
• SpellRare: Words recognised by spell checker as rarely used

For example consider the following highlight command:

h1 SpellBad cterm=underline,bold ctermfg=red

This will style unrecognised words as red, bold and underlined.

For further information visit the highlight-args help topic:

:h highlight-args

I have setup such styles in ~/.vim/after/ftplugin/markdown.vim and enabled the spell checker for the local buffer. These are configured after Markdown files are loaded via the file type plugin, ftplugin.

How To Get Further Help?

Use Vim help, :help spell

Grammar Checker

After some initial investigation, there looks to be two plugins provided for grammar checking:

• vim-grammarous
• vim-LanguageTool

Both use a Java library, LanguageTool, to perform grammar checking. Unfortunately, at the time of writing, LanguageTool 6.0 has introduced a breaking change that affects both plugins. The current solution is to install the older 5.9 version of LanguageTool.

I initially tried installing and configuring vim-grammarous plugin and experienced failure to start languagetool, with exit code status -1? The documentation was also sparse. For this reason, I started using the vim-LanguageTool plugin.

I have configured vim-LanguageTool as follows:

Plug 'dpelle/vim-LanguageTool'

let g:languagetool_jar='/mnt/hdd/lib/languagetool/LanguageTool-5.9/languagetool-commandline.jar'
let g:languagetool_lang='en-GB'

N.B. I downloaded LanguageTool 5.9 and updated the languagetool_jar setting to reference version 5.9.

How To Perform A Grammar Check?

:LanguageToolCheck will issue the Java languagetool command to check the contents of the current buffer. The errors will be listed in a new vim scratch window. The errors are also available in the location window.

Pressing the ENTER key on each highlighted error will navigate to the corresponding line in the buffer

How To Use The Location Window?

How To Display The Errors In The Location Window?

The errors are also populated in the vim locations list window. This can be displayed by issuing the command, :lopen. To close the location list window issue the command, :lclose.

How To Display Grammar Errors Only In The Location Window?

In your ~/.vimrc file add the following configuration option:

let g:languagetool_win_height=-1

How To Navigate Grammar Errors In The Location Window?

The following commands can be used to navigate the grammar errors in the location list window:

• :lfirst jumps to the first error
• :llast jumps to the last error
• :lprev jumps to the previous error
• :lnext jumps to the next error

How to Clear Grammar Error Highlighted In Body Text?

Issue the :LanguageToolClear command.

How To Get Further Help?

• Use vim help, help: LanguageTool.
• Visit the GitHub repo to find out further details of usage. I tend to also browse the Issues of the repository to gain additional insights.

How To Render A Minimal Display?

To render a minimal display, similar to the screenshot below, I use the Goyo and Limelight plugins. The Goyo plugin provides a minimal display, hiding the NERDTreeToggle sidebar, the Airline status bar etc. The Limelight plugin highlights the paragraph where the cursor is currently positioned.

I activate and deactivate the Limelight plugin synchronously with the Goyo plugin.

Plug 'junegunn/limelight.vim', { 'for': 'markdown' }

" activate limelight plugin when goyo plugin activates
autocmd! User GoyoEnter Limelight

" activate limelight plugin when goyo plugin deactivates
autocmd! User GoyoLeave Limelight!

Conclusion

This post has summarised the following vim features that I have found useful so far, when technical writing with Markdown:

• Visual display of right margin
• Autoformat paragraph to width
• Preview markdown
• Spell checking
• Grammar checking
• Navigate table of contents
• Toggle a minimal display

Evidently, there are many other features that I have yet to discover. Furthermore, some features have not been covered here. This includes find and replace in addition to document navigation. There are many keyboard shortcuts provided by vim to facilitate these operations. An article that provides a good explanation can be found here.

Hopefully this post will be of some use to other technical writers considering using vim and Markdown.