This is the first part of a few tutorials on using the LaTeX typesetting system with Neovim using the LazyVim setup. I highly recommend LazyVim because it has many cool plugins configured with nice defaults. Moreover, as we see in this tutorial, it lets you quickly have VimTeX and the TexLab LSP up and running in Neovim.
You can follow this step-by-step tutorial by implementing the steps starting from a fresh LazyVim installation (see http://www.lazyvim.org/installation). If you already use LazyVim, you might want to do the steps in this tutorial on a fresh, separate Neovim configuration directory before applying all the configurations in your daily-driver Neovim configuration.
For example, if you start with the starter project provided by LazyVim, you can clone it into a separate configuration directory:
1 |
git clone https://github.com/LazyVim/starter ~/.config/lazyvim-tex |
And then you start Neovim pointing to that configuration:
1 |
NVIM_APPNAME=lazyvim-tex nvim |
This way, your existing Neovim configuration won’t be touched, and you’ll be free to experiment with this new configuration.
In these tutorials, the path is always intended relative to the Neovim configuration path when referring to a configuration file. If you follow the above commands, for example, it will be relative to “~/.config/lazyvim-tex”.
I suggest you follow the tutorials by manually executing the configuration steps in a new, separate Neovim configuration.
The final result of this series of tutorials can be found here: https://github.com/LorenzoBettini/lazyvim-tex. Branches will denote the state of the repository according to a specific blog post part.
A few initial notes
The plugin VimTeX needs a LaTeX installation and a compiler; the default is “latexmk”.
In Arch Linux, you can install it like this:
1 |
sudo pacman -S texlive-binextra |
You must also ensure a working LaTeX installation with all the needed packages.
I’ll use Zathura and Sioyek as PDF viewers, automatically providing bi-directional linking (synchronization) between the LaTeX sources and the PDF.
In Arch Linux, you can install Zathura like this:
1 |
sudo pacman -S zathura-pdf-poppler |
For Sioyek, AUR packages are available.
I’ll use a light theme (“catpuccin-latte”) for Neovim instead of the default dark one in the screenshots.
The “localleader” will be remapped to “\”: VimTeX commands start with “l” and in LazyVim “<leader> l” (that is, “<space> l” is already mapped to “Lazy” commands). This remap is done automatically by the LazyVim “Tex Extra” I’ll use.
Let’s start
As a first LaTeX example, I’ll use this one from VimTeX: https://github.com/lervag/vimtex/blob/master/test/example-quick-start/main.tex. Download that file and put it somewhere in a subdirectory, e.g., “latex”. That LaTeX article also describes the main features of VimTeX and its commands and bindings.
Let’s open this file with the fresh Neovim distribution.
Let’s install the LazyVim “Tex Extra”. A LazyVim extra is meant to configure several plugins and configurations with a single mechanism. In this case, it will configure VimTex, the TexLab LSP, and other related plugins and keybindings.
You have some alternatives to enable an “Extra”, which is documented for each available “Extra”; for Java, see http://www.lazyvim.org/extras/lang/tex. I prefer to use the UI: Type “:LazyExtras” to show the LazyVim Extras UI:
The LazyExtras UI proposes some recommended extras based on the files you’ve just opened, so it should recommend “lang.tex”; if not, search for “lang.tex” and when you’re on that line, press “x” to install the extra.
You get the feedback about restarting Neovim so that VimTeX is installed.
Specifying an extra as we’ve just done creates a file in the configuration, “lazyvim.json”, with this content (the numbers for news and version might be different depending on when you follow this tutorial):
1 2 3 4 5 6 7 8 9 |
{ "extras": [ "lazyvim.plugins.extras.lang.tex" ], "news": { "NEWS.md": "..." }, "version": ... } |
The idea is to keep this file in the Git repository for your configuration as part of your dotfiles for Neovim.
Once you reopen the LaTeX file, you should get feedback about Mason downloading the “texlab” LSP; this is done only the first time.
Of course, you could force the installation of “texlab” beforehand by using the Mason UI, “:Mason”: select “texlab” and install it.
Alternatively, if you want a fully automated solution that, besides installing all the Neovim plugins, also automatically installs the TeXLab LSP, you can add this Lua specification in the Neovim configuration folder (the name does not matter; I call it “extend-lsp” to stress that it extends the Mason configuration of LazyVim, https://github.com/LazyVim/LazyVim/blob/main/lua/lazyvim/plugins/lsp/init.lua) “lua/plugins/extend-lsp.lua” with this content:
1 2 3 4 5 6 7 8 |
return { "williamboman/mason.nvim", opts = { ensure_installed = { "texlab", }, }, } |
Now, when you start Neovim, “texlab” will automatically install. You might want to check whether Mason has successfully downloaded and installed it or is still installing it through the Mason UI.
You can now try to edit the file using the content assist, providing completions and possible templates:
Let’s explore VimTex commands; remember that we’ll use “\” as the “localleader”. Which-key will show the available keybindings:
Let’s compile the LaTeX file with “\ l l”. This will start the compilation, which, depending on the size and complexity of the LaTeX document, takes a few seconds.
In the end, if there are no compilation errors, it automatically opens the default PDF viewer (I’m on KDE, and the default PDF viewer is Okular):
With “\ l l” we instructed VimTeX to watch for file changes (you can stop it with “\ l k”). VimTeX will automatically retrigger compilation and update the PDF document in the viewer as soon as we change the file and save it. For example, let’s add a sentence, save, and when we get feedback about the completed compilation, we should see the result in the PDF viewer:
Let’s add a LaTeX error, save, and get the list of reported errors (selecting any error will lead to the corresponding line in the source file):
Configure the PDF viewer
Let’s configure Zathura as the viewer.
Let’s add this line in the file “lua/config/options.lua”:
1 |
vim.g.vimtex_view_method = "zathura_simple" |
I’m using “zathura_simple” instead of “Zathura” because, as documented, the latter requires “xdotool”, which I don’t have. This way, we avoid the warning “Viewer cannot find Zathura window ID!”.
Let’s restart Neovim, reopen the LaTeX file, and select “\ l l”.
Now, it will open Zathura with the highlighted part corresponding to the cursor’s current position in the source file!
Let’s move the cursor in the source file to another line and press “\ l v”: the selection in the PDF is updated accordingly:
The other way round also works: from Zathura, use “Ctrl + click”, and the cursor in the source file will be updated to the corresponding line (in the screenshot below, I did “Ctrl + click” on the part of “toggles between”):
This synchronization is super useful when writing in LaTeX, isn’t it? 🙂
Alternatively, I also use Sioyek as a PDF viewer, which works on macOS as well. In this case, the option for the viewer must be changed accordingly:
1 |
vim.g.vimtex_view_method = "sioyek" |
In Sioyek, to return to the source file, enter “synctex” mode with “F4” and right-click with the mouse.
Other features
Let’s open the “Table of Contents” window with “\ l t”:
Note the helpful help contents and the “TODO” elements that were also reported.
Stay tuned for more blog posts on LaTeX and Neovim! 🙂