Previously, I have written a post on how to write and compile LaTeX source code in Sublime Text. Now that I am familiar with Neovim and I want to do everything related to text editing in Neovim. In this post, I would like to share how to configure Neovim for LaTeX editing and previewing.

Pre-requisite

Before we begin, you should make sure that you have installed the following softwares and plugins.

  • TeX Distribution: TeX Live is preferred since it is bundled with the possible many tools you will ever need for writing LaTeX.
  • Auto-complete plugin: Since I use Neovim, so I recommend using deoplete.
  • Snippet Engine and snippet plugin: I recommend Ultisnips along with the many snippets provided by plugin vim-snippets.

Then we need to install the LaTeX plugin for Neovim. Vimtex is a great choice. To install it, we can use vim-plug:

Plug 'lervag/vimtex'

Faster LaTeX source file editing

Auto-completion

In writing LaTeX source code, auto-completion is crucial for fast editing and improves our efficiency dramatically. Vimtex supports completion for citations, labels (for figure, equation, table, section, etc.), commands, environments, packages and document classes and more. For more documentation on completion, see :h vimtex-completion.

Vimtex can work with several completion engines such as deoplete, YouCompleteMe, ncm2. Since I use deoplete for completion, I will just introduce how to configure it for deoplete1. To make vimtex work with deoplete, add the following setting to your init.vim:

" This is new style
call deoplete#custom#var('omni', 'input_patterns', {
      \ 'tex': g:vimtex#re#deoplete
      \})

After that you should be able to use auto-completion.

How to quickly insert an environment?

Vimtex supports autocompletion through autocompletion engines such as deoplete. After configuring vimtex to use deoplete, you should be able to use the snippet provided by Ultisnips.

Ultisnips is a snippet engine, which uses vim-snippets to provide the actual snippet for various file types. To insert an figure environment, type fig in insert mode and press Tab.

To insert an enumerate environment, type enum in insert mode and press Tab. The complete list of snippets provided by vim-snippets can be found here.

How to close an environment?

After typing \begin{ENV}, how do we automatically close it with \end{ENV}? With vimtex, you can press ]] in insert mode to auto-close an environment.

Useful mappings

Vimtex provides a few vim-surround like features for manipulating environment quickly.

  • cse: change an environment
  • dse: delete an environment
  • tse:toggle stared environment and no-star environment, e.g., change from equation* to equation and vice versa.
  • ]]: close an environment (only work in insert mode, in normal mode, it will bring cursor to next subsection instead). After you have typed begin{ENV}, use ]] to auto-close it with \end{ENV}

For more mappings, see :h vimtex-default-mappings.

Jumping between references and the definition

It would be nice if we can jump to the definition of a label with the native Vim shortcut [Ctrl-]](http://vimdoc.sourceforge.net/htmldoc/tagsrch.html#CTRL-]). You have to do several things.

First, you need to install a ctags executable. See here on how to install ctags.

Second, you need to install a plugin to manage tags file for you. vim-gutentags is a good option. It will update the tags file automatically once the source file has been changed. To make gutentags work, you need to tell it where your project root is. The easiest way is to make your project a git repository.

Open the TeX source file again, the tags file should be created automatically. If the cursor is in \ref{some_label}, you can press Ctrl + ] to go the position where some_label is defined. BTW, to jump back, you can use Ctrl-T.

Useful command

  • :VimtexInfo: show all relevant info about current LaTeX project.
  • :VimtexTocOpen: show table of contents window
  • :VimtexTocToggle: toggle table of contents window
  • :VimtexCompile: Compile the current LaTeX source file and opens the viewer after successful compilation.
  • :VimtexStop: Stop compilation for the current project.
  • :VimtexClean: clean auxiliary files generated in compliation process.

Other settings

PDF previewing

Vimtex supports several PDF viewer based on the platform. On Windows, SumatraPDF is a good choice. Below is the settings needed for SumatraPDF to work as the default viewer for the compiled PDF files.

" settings for sumatraPDF
let g:vimtex_view_general_viewer = 'SumatraPDF'
let g:vimtex_view_general_options
    \ = '-reuse-instance -forward-search @tex @line @pdf'
let g:vimtex_view_general_options_latexmk = '-reuse-instance'

After the above settings, if you use :VimtexCompile command, the compiled PDF will be opened in sumatraPDF automatically.

Linting and syntax checking

I use neomake for syntax checking. For LaTeX source file, neomake provides several makers:

Among the makers, lacheck and chktex are installed if you have installed Tex Live. Prolint can be installed via pip:

pip install proselint

Setting up table of contents

Vimtex can show a nice little table of contents window on the left side if you use command VimtexTocOpen. By default, the lables in each section is also shown, which makes the TOC clutter with texts. We can customize TOC with following settings:

" TOC settings
let g:vimtex_toc_config = {
      \ 'name' : 'TOC',
      \ 'layers' : ['content', 'todo', 'include'],
      \ 'resize' : 1,
      \ 'split_width' : 50,
      \ 'todo_sorted' : 0,
      \ 'show_help' : 1,
      \ 'show_numbers' : 1,
      \ 'mode' : 2,
      \}

For detailed meaning of the keys in the above dictionary, refer to :h g:vimtex_toc_config.

TeX directives

If you are compiling a LaTeX source file written in non-English character. You may want to use the TeX directive to specify the compiling program. Vimtex supports two TeX directives: TeX root and TeX program. TeX program directive is useful when we want to compile the LaTeX source code with xelatex instead of pdflatex. In order to compile your LaTeX source file with xelatex, add the following directive to the first line of the source code:

%!TeX program = xelatex

My complete settings for vimtex can be found here.

References


  1. For configuring vimtex to work with other completion engines, please refer to :h vimtex-complete-auto.