Introduction

As a Neovim user who has used Sublime Text for code editing for some time, I miss the experience I get when dealing with Markdown files with the help plugins such as MarkdownEditing and MarkdownPreview. In this post, I would like to share my settings for Markdown writing inside Neovim to get similar writing experience, even better!

Markdown editing

When we are editing Markdown source files, it is nice to have some code snippets to promote efficiency. Fortunately, UltiSnips combined with vim-snippets 1 provides a lot of useful snippets for Markdown files.

The two plugins can be install by vim-plug:

Plug 'SirVer/ultisnips'
Plug 'honza/vim-snippets'

We need to set up UltiSnips to use it. The following is an example setting:

" Trigger configuration. Do not use <tab> if you use https://github.com/Valloric/YouCompleteMe.
let g:UltiSnipsExpandTrigger="<tab>"  " use <Tab> trigger autocompletion
let g:UltiSnipsJumpForwardTrigger="<c-f>"
let g:UltiSnipsJumpBackwardTrigger="<c-b>"

In the above setting, we use <Tab> to trigger the snippet auto-completion, which means that after entering the snippet keyword for a particular snippet, using <Tab> will expand the keyword to the full snippet template. For example, if we type link and then press <Tab>, it will be expanded to the following form:

[Text](http://www.url.com)

the cursor will be placed at Text, with Text being selected and waiting for you to enter the real link text. The setting UltiSnipsJumpForwardTrigger and UltiSnipsJumpBackTrigger set up the shortcut key to go to next and previous text area of a snippet, making the snippet editting more convenient. Take the above inline link snippet for an example. Suppose we want to add an inline link to Neovim offical website (the address is https://neovim.io/), we can follow the steps below:

  1. Enter link and press <Tab> to get the link template.
  2. Start typing Google and Text will be replaced by Google.
  3. Press <Ctrl-F>. www.url.com will be selected.
  4. Start typeing www.google.com.

There are many more snippets you can use. Some of the commonly used snippet keywords are listed below:

  • Header:
    • Level 1: sec
    • Level 2: ssec
    • Level 3: sssec
    • Level 4: par
    • Level 5: spar
  • Links:
    • Inline link: link
    • Reference link: refl
    • Image link: img
  • Code:
    • Code block: cbl
    • Inlinde code: ilc
  • Text rendering:
    • Italic text: *
    • Bold text: **
    • Italic and bold text: ***
  • General:
    • date: date
    • time: time
    • date and exact time: datetime
    • date in ISO format: diso

Distraction-free writing

When we are writing Markdown files, we may wish to focus on the task and temporarily disable the distraction elements in Neovim. The plugin goyo is designed specifically for that purpose. You can install it with vim-plug:

Plug 'junegunn/goyo.vim'

After installing this plugin, you can use Goyo command toggle between the normal mode and distraction-free mode.

The author also suggests installing limelight, which will dim all lines except the current line when turned on.

First, install it with vim-plug:

Plug 'junegunn/limelight.vim'

After install, you can use Limelight to activate it. To deactivate, use Limelight!.

You can also integrate goyo and limelight together with the following setting:

autocmd! User GoyoEnter Limelight
autocmd! User GoyoLeave Limelight!

when you turn on/off goyo, limelight will also be turn on/off.

Markdown syntax highlighting

Code highlighting is also important, which helps us to see the structure of the source code. The first plugin we should install is vim-markdown. You can install it with vim-plug:

" tabular plugin is used to format tables
Plug 'godlygeek/tabular'
" JSON front matter highlight plugin
Plug 'elzr/vim-json'
Plug 'plasticboy/vim-markdown'

Vim-markdown provides a lot of functionalities such as folding, conceal etc. Here, we mainly use its syntax highlighting feature. Below are some settings for vim-markdown:

" disable header folding
let g:vim_markdown_folding_disabled = 1

" do not use conceal feature, the implementation is not so good
let g:vim_markdown_conceal = 0

" disable math tex conceal feature
let g:tex_conceal = ""
let g:vim_markdown_math = 1

" support front matter of various format
let g:vim_markdown_frontmatter = 1  " for YAML format
let g:vim_markdown_toml_frontmatter = 1  " for TOML format
let g:vim_markdown_json_frontmatter = 1  " for JSON format

This plugin also provides a few shortcut and command:

  • Shortcut:
    • ]]: go to next header
    • [[: go to previous header
  • Command:
    • Toc: create a vertical window of table of contents
    • TableFormat: format the table under current cursor

For more settings about these plugins, please consult their documentations.

Another good Markdown syntax plugin I recommend is vim-pandoc-syntax. It provides more syntax highlight and better conceal features. First, install it with vim-plug:

Plug 'vim-pandoc/vim-pandoc-syntax'

It is designed to work with vim-pandoc. To use it as a standalone plugin, we should add the following settings in our Neovim configuration file:

augroup pandoc_syntax
    au! BufNewFile,BufFilePre,BufRead *.md set filetype=markdown.pandoc
augroup END

After all this settings, you Markdown file will be like what is shown in the following image:

Final effect after configuration

Markdown previewing

There are several Markdown previewer for Neovim on GitHub. I have tried previm and markdown-preview.nvim, both which have cross-platform support for Nvim (Windows, Linux and MacOS are supported). After some trail, I think markdown-preview is superior in terms of speed, functionality provided and rendering result. It is easy to install with vim-plug:

" if you don't have nodejs and yarn, use pre build
Plug 'iamcco/markdown-preview.nvim', { 'do': { -> mkdp#util#install() }}

Here is my setting for this plugin:

" do not close the preview tab when switching to other buffers
let g:mkdp_auto_close = 0

To start previewing a markdown file, use MarkdowPreview command. Your default browser will be opened automatically. You can also add a custom key mapping for this command:

nnoremap <M-m> :MarkdownPreview<CR>

For other custom settings, see its documentation.

Summary

In this blog post, I introduced the plugins and settings I use for Markdown editing, syntax highlighting and previewing. The end result is the smooth writing experience I get.


  1. UltiSnips is the snippet engine, while vim-snippets provides the actual snippet.