Previously, I have written a post about 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 editting in Neovim. In this post, I would like to share how to configure Neovim for LaTeX editting 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 editting

Auto-completion

In writing LaTeX source code, auto-completion is curcial for fast editting 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.

References

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 env and no-star env, 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 defintion

First, ctags should be installed. Universal-ctags is a good choice and can be installed via chocolatey:

choco install universal-ctags

Then we need to install a neovim plugin which can manage the tags file automatically for us. Vim-gutentags is a good choice. For gutentags to work, the directory in which the tex source file resides must be version-controled. To create a git repo in this directory, use the following command:

git init

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.

References

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

References


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