4. Getting started with the VimTeX plugin

Last modified: 8 June 2022

This is part four in a seven-part series explaining how to use the Vim or Neovim text editors to efficiently write LaTeX documents. This article describes the excellent VimTeX plugin, a modular Vim and Neovim plugin that implements a host of useful features for writing LaTeX files.

Contents of this article

Background knowledge: this article will make regular references to the file ftplugin/tex.vim, which we will use to implement LaTeX-specific Vim configuration through Vim’s filetype plugin system. To get the most out of this article, you should understand the purpose of the ftplugin/tex.vim file and have a basic understanding of Vim’s filetype plugin system. In case you are just dropping in now and these topics sound unfamiliar, consider first reading through the previous article in this series, which covers what you need to know.

The point of this article

This article gives an overview of the features VimTeX provides, offers some ideas of how to use these features from the practical perspective of a real-life user, and shows where to look in the documentation for details.

Given VimTeX’s superb documentation, what is the point of this guide? My reasoning is that many new users—I am often guilty of this too—quickly become overwhelmed when reading extensive plain-text documentation as a means of learning new software, and perhaps the Markdown syntax, animated GIFs, highlighted code blocks, and more personal tone in this article will make it easier for new users to digest what VimTeX offers.

My goal is certainly not to replace the VimTeX documentation, which remains essential reading for any serious user. Instead, I hope to quickly bring new users up to a level of comfort at which the documentation becomes useful rather than overwhelming, and to offer pointers as to where in the VimTeX documentation to look when interested in a given feature.

Getting started with VimTeX

Install VimTeX like any other Vim plugin using your plugin installation method of choice (reminder of series prerequisites). The requirements for using VimTeX are mostly straightforward, for example:

See :help vimtex-requirements for details on requirements for using VimTeX.

Note that you will need a LaTeX compilation program (e.g. latexmk and pdflatex) installed on your computer to be able use VimTeX’s compilation features. You also need a Vim version compiled with the +clientserver feature to use VimTeX’s inverse search feature with PDF readers (note that +clientserver ships by default with Neovim). I cover compilation and setting up a PDF reader in the next two articles in this series, so you can postpone these requirements until then.

Some things to keep in mind

As you get started with the VimTeX plugin, here are a few things to keep in mind:

Overview of features

The VimTeX plugin offers more than any one user will probably ever require; you can view a complete list of features at :help vimtex-features, or see an online version on the VimTeX GitHub page.

This article will cover the following features:

VimTeX also provides a compilation interface and PDF viewer support, which I have left out of this article and describe in two dedicated articles later in the series.

How to read VimTeX’s documentation of mappings

First, a quick crash course in a very useful part of the VimTeX documentation.

All of the mappings (i.e. keyboard shortcuts for commands and actions) provided by VimTeX are nicely described in a three-column list you can find at :help vimtex-default-mappings. You will probably return to this list regularly as you learn to use the plugin. Here is a representative example of what the list looks like:

---------------------------------------------------------------------
 LHS              RHS                                          MODE
---------------------------------------------------------------------
 <localleader>li  <Plug>(vimtex-info)                           n
 <localleader>ll  <Plug>(vimtex-compile)                        n
 csd              <Plug>(vimtex-delim-change-math)              n
 tse              <Plug>(vimtex-env-toggle-star)                n
 ac               <Plug>(vimtex-ac)                             xo
 id               <Plug>(vimtex-id)                             xo
 ae               <Plug>(vimtex-ae)                             xo

To have a clear mental image of what’s going on here, you should understand how Vim mappings work, what the <leader> and <localleader> keys do, and what the <Plug> keyword means. If you want to learn about these topics now, take a detour and read through the final article in this series, 7. A Vimscript Primer for Filetype-Specific Workflows.

For the present purposes, here is how to interpret the table:

The VimTeX documentation sections COMMANDS (accessed with :help vimtex-commands) and MAP DEFINITIONS (accessed with :help vimtex-mappings) list and explain the commands and mappings in the RHS of the above table. I recommend skimming through the table in :help vimtex-default-mappings, then referring to :help vimtex-commands or :help vimtex-mappings for more information about any mapping that catches your eye.

Doing practical stuff with VimTeX’s mappings

Following is a summary, with examples, of useful functionality provided by VimTeX that you should know exists. Again, nothing in this section is particularly original—you can find everything in the VimTeX documentation.

Customization is easy: Before listing the VimTeX actions, I want to point out that every shortcut used to access them can easily customized to anything you like. I show how to do this a few paragraphs below in the section Customization is easy. But first, let’s see some practical LaTeX wizardry using VimTeX!

Change and delete stuff

You can…

Toggle-style mappings

The following commands toggle back and forth between states of various LaTeX environments and commands. You can…

Motion mappings

All of the following motions accept a count and work in Vim’s normal, operator-pending, and visual modes. You can…

Customization is easy

After seeing the VimTeX actions and mappings, I want to show how to customize the default shortcut you trigger them with. To customize the shortcut for a VimTeX action or motion, you need to know three things:

  1. The motion’s <Plug> mapping, given above for each action and also shown in the three-column table in :help vimtex-default-mappings.

  2. The Vim mapping mode (e.g. normal, visual, operator-pending, etc.) the <Plug> mapping works in; again from the table at :help vimtex-default-mappings or earlier in this article.

  3. The action’s default shortcut (from :help vimtex-default-mappings or earlier in this article) and the custom shortcut you would like to use to replace it.

Example: Since that might sound abstract, here is a concrete example of setting a custom shortcut to trigger the “delete surrounding math” action. Following the steps listed above,

  1. The action’s <Plug> map is <Plug>(vimtex-env-delete-math)
  2. The action works in normal mode, so we will use nmap for remapping it (use xmap for visual mode, omap for operator-pending mode, etc.)
  3. We will replace the default mapping, ds$ (which makes semantic sense but is a bit difficult to type), with the more convenient dsm.

To implement this change, place the following code in your ftplugin/tex.vim (or similar):

" Use `dsm` to delete surrounding math (replacing the default shorcut `ds$`)
nmap dsm <Plug>(vimtex-env-delete-math)

That’s it! You could then use dsm in normal mode to delete surrounding math. (For a background of what’s going on here, you can consult the final article this series, 7. A Vimscript Primer for Filetype-Specific Workflows.)

The key when redefining default mappings is to use your own, personally-intuitive LHS mapping (e.g. dsm) with VimTeX’s default <Plug> mapping (e.g. <Plug>(vimtex-env-delete-math)). VimTeX won’t apply the default LHS shortcut to any <Plug> mapping you map to manually (this behavior is explained in :help vimtex-default-mappings).

Text objects

VimTeX provides a number of wildly useful LaTeX-specific text objects. If you don’t yet know what text objects are, stop what you’re doing and go learn about them. As suggested in :help vimtex-text-objects, a good place to start would be the Vim documentation section :help text-objects and the famous Stack Overflow answer Your problem with Vim is that you don’t grok vi.

VimTeX’s text objects are listed in the table in :help vimtex-default-mappings and described in more detail in :help vimtex-mappings; the text objects behave exactly like Vim’s built-in text objects (which are explained in :help text-objects) and work in both operator-pending and visual mode.

The section :help vimtex-text-objects gives a general overview of how text objects work, but does not actually list the text objects. For the curious, VimTeX’s mappings, including text objects, are defined in the VimTeX source code at around line 120 of vimtex/autoload/vimtex.vim in the function s:init_default_mappings() at the time of writing.

Table of VimTeX text objects

For convenience, here is a table of VimTeX’s text-objects, taken directly from :help vimtex-default-mappings:

Mapping Text object
ac, ic LaTeX commands
ad, id Paired delimiters
ae, ie LaTeX environments
a$, i$ Inline math
aP, iP Sections
am, im Items in itemize and enumerate environments

The ad and id delimiter text object covers all of (), [], {}, etc. and their \left \right, \big \big, etc. variants, which is very nice. Here is a visual mode example of the delimiter and environment text objects:

VimTeX's text objects

Example: Changing a default text object mapping

Every default mapping provided by VimTeX can be changed to anything you like, using the exact same procedure described a few sections above in Customization is easy. As an example to get you started with changing default mappings, VimTeX uses am and im for the item text objects (i.e. items in itemize or enumerate environments) and a$ and i$ for the math objects.

You might prefer to use (say) am/im for math (since $ is a bit difficult to reach) and ai/ii for items, and could implement this change by placing the following code in ftplugin/tex.vim (or similar):

" Use `am` and `im` for the inline math text object
omap am <Plug>(vimtex-a$)
xmap am <Plug>(vimtex-a$)
omap im <Plug>(vimtex-i$)
xmap im <Plug>(vimtex-i$)

" Use `ai` and `ii` for the item text object
omap ai <Plug>(vimtex-am)
xmap ai <Plug>(vimtex-am)
omap ii <Plug>(vimtex-im)
xmap ii <Plug>(vimtex-im)

You could then use the am and im mapping to access the math text object, or ai an ii to access items. Note that the mappings should be defined in both operator-pending and visual mode, so we use both omap and xmap (you would know this by checking the table at :help vimtex-default-mappings).

Example: Disabling all default mappings and selectively defining your own

VimTeX also makes it easy to disable all default mappings, then selectively enable only the mappings you want, using the LHS of your choice. You might do this, for example, to avoid cluttering the mapping namespace with mappings you won’t use. From :help vimtex-default-mappings:

If one prefers, one may disable all the default mappings through the option g:vimtex_mappings_enabled. Custom mappings for all desired features must then be defined through the listed RHS -maps or by mapping the available commands.

To disable all VimTeX default mappings, place g:vimtex_mappings_enabled = 0 in your ftplugin/tex.vim (or similar), then manually redefine only those mappings you want using the same mapping syntax shown above in the Example section on Changing a default text object mapping. In case that sounds abstract, here is an example to get you started:

" An example of disabling all default VimTeX mappings, then selectively
" defining your own. This code could go in ftplugin/tex.vim.

" Disable VimTeX's default mappings
let g:vimtex_mappings_enabled = 0

" Manually redefine only the mappings you wish to use
" --------------------------------------------- "
" Some text objects
omap ac <Plug>(vimtex-ac)
omap id <Plug>(vimtex-id)
omap ae <Plug>(vimtex-ae)
xmap ac <Plug>(vimtex-ac)
xmap id <Plug>(vimtex-id)
xmap ae <Plug>(vimtex-ae)

" Some motions
map %  <Plug>(vimtex-%)
map ]] <Plug>(vimtex-]])
map [[ <Plug>(vimtex-[[)

" A few commands
nmap <localleader>li <Plug>(vimtex-info)
nmap <localleader>ll <Plug>(vimtex-compile)

This example, together with the list of default mappings in :help vimtex-default-mappings, should be enough to get you on your way towards your own configuration.

Insert mode mappings

VimTeX provides a number of insert mode mappings, which are described in :help vimtex-imaps. VimTeX mappings provide a similar (but less feature-rich) functionality to snippets, described in an earlier article in this series. If you use a snippets plugin, you can probably safely disable VimTeX’s insert mode mappings without any loss of functionality.

VimTeX’s insert mode mappings are enabled by default; disable them by setting g:vimtex_imaps_enabled = 0 in your ftplugin/tex.vim file (configuring VimTeX’s option variables is covered in more detail in the Options section just below).

Although most users following this series will probably end up disabling VimTeX’s insert mode mappings, here are a few things to keep in mind:

Options

VimTeX’s options are used to manually enable, disable, or otherwise configure VimTeX features (e.g. the delimiter toggle list, the compilation method, the PDF reader, etc.). VimTeX’s options are controlled by setting the values of global Vim variables somewhere in your Vim runtimepath before VimTeX loads (a good place would be ftplugin/tex.vim). You disable VimTeX features by un-setting a Vim variable controlling the undesired feature. Upon loading, VimTeX reads the values of any option variables you set manually and updates its default behavior accordingly.

VimTeX’s options are documented at :help vimtex-options; the documentation is clear and largely self-explanatory, and you should skim through it to see which options are available.

Example: Disabling default features

The most common use case for VimTeX options is disabling default VimTeX features. Here is the general workflow:

  1. While skimming through the VimTeX documentation, identify a feature you wish to disable. (Most of VimTeX’s features are enabled by default, and it is up to the user to disable them.)
  2. From the documentation, identify the Vim variable controlling a VimTeX feature; the variable is usually clearly listed in the documentation.
  3. Set the appropriate variable value (usually this step amounts to setting a g:vimtex_*_enabled variable equal to zero) somewhere in your ftplugin/tex.vim file (or similar).

As a concrete example, one could disable VimTeX’s indent, insert mode mapping, completion, and syntax concealment features by placing the following code in ftplugin/tex.vim:

  " A few examples of disabling default VimTeX features.
  " The code could go in `ftplugin/tex.vim`.
  let g:vimtex_indent_enabled   = 0      " turn off VimTeX indentation
  let g:vimtex_imaps_enabled    = 0      " disable insert mode mappings (e.g. if you use UltiSnips)
  let g:vimtex_complete_enabled = 0      " turn off completion
  let g:vimtex_syntax_enabled   = 0      " disable syntax conceal

These are just examples to get you started; in practice, you would of course tweak the settings to your liking after identifying the appropriate variables in the VimTeX documentation.

Example: Changing the default delimiter toggle list

Here is another real-life example: to add \big \big to the delimiter toggle list used by VimTeX’s “toggle surrounding delimiter” feature (see the earlier section on Toggle-style mappings), add the following code to you ftplugin/tex.vim file (or similar):

" Example: adding `\big` to VimTeX's delimiter toggle list
let g:vimtex_delim_toggle_mod_list = [
  \ ['\left', '\right'],
  \ ['\big', '\big'],
  \]

The tsd <Plug>(vimtex-delim-toggle-modifier) mapping would then use both \left \right and \big \big. The VimTeX documentation explains configuring the delimiter list in more detail at :help g:vimtex_delim_toggle_mod_list.

Hopefully the above two examples give you a feel for setting VimTeX options; the VimTeX documentation should be able to take things from here.

Commands

The VimTeX plugin provides a number of user-defined commands, and these are listed and described in the documentation section :help vimtex-commands. The commands mostly cover compilation, PDF reader integration, and system and plugin status; we will return to VimTeX’s commands when explaining compilation and PDF reader integration in the next two articles in this series.

There is nothing much I have to say about the commands themselves that the documentation wouldn’t say better; I suggest you skim through :help vimtex-commands and see if anything strikes your fancy.

As a side note, most but not all VimTeX commands can be triggered by default using a shortcut in the LHS of the three-column list in :help vimtex-default-mappings. For those commands without a default shortcut mapping, defining one can be as simple as a single line of Vimscript. Here is an example, which you could place in ftplugin/tex.vim, that makes the key combination <leader>wc call the VimTeX command VimtexCountWords:

" Example: make `<leader>wc` call the command `VimtexCountWords`;
" you might place this code in ftplugin/tex.vim.
noremap <leader>wc <Cmd>VimtexCountWords<CR>

(This mapping uses the <Cmd> keyword, which is a Vimscript best practice when defining mappings that specifically call commands—see :help map-cmd for details.)

Syntax highlighting

VimTeX provides syntax highlighting that improves on Vim’s built-in syntax plugin for LaTeX. For most use cases VimTeX’s syntax features should “just work” out of the box, and you won’t need to do any configuration yourself (if you’re interested in details, see :help vimtex-syntax). I can think of three things worth mentioning:

Other features

Here are a few more features to look into to learn about once you master the basics:

Appendix: Troubleshooting failed VimTeX loading

If you are new to Vim, the VimTeX plugin loads without any problem, and you have no idea what I’m talking about here, don’t worry and skip it. The point is to make sure that VimTeX loads, and if VimTeX loads for you without issues, you’re good to go.

Warning aside, here is the potential problem: the VimTeX plugin respects (and will not override) a user-defined tex filetype plugin. You must be careful though—there is a risk of your tex filetype plugin overriding VimTeX! Namely, VimTeX will not load if you set the Vimscript variable let b:did_ftplugin = 1 in your user-defined tex plugin, for example with the common piece of boilerplate code shown below

" This common piece of boilerplate code would prevent VimTeX from loading if...
" ...placed in a user-defined LaTeX filetype plugin, e.g. `~/.vim/ftplugin/tex.vim`.
if exists("b:did_ftplugin")
  finish
endif
let b:did_ftplugin = 1
" Using a variable like `b:did_my_ftplugin` will solve the problem.

Here is the problem: VimTeX also uses the variable b:did_ftplugin to avoid loading twice in the same Vim buffer. User-defined filetype plugins load before VimTeX, so if you set let b:did_ftplugin = 1, then VimTeX will see b:did_ftplugin = 1 and not load (you can see this behavior for yourself in the VimTeX source code in the file vimtex/ftplugin/tex.vim).

If you want to use both VimTeX and your own tex filetype plugin and currently have let b:did_ftplugin = 1 in your own plugin, just change to a variable name like b:did_my_ftplugin instead, which won’t conflict with VimTeX’s use of b:did_ftplugin.

(The let b:did_ftplugin = 1 business is a standard safety mechanism described in the Vim documentation at :help ftplugin that gives the user control over loading filetype plugins.)

The original writing, images, and animations in this series are licensed under the Creative Commons Attribution-NonCommercial 4.0 International License.
CC BY-NC 4.0