(This is part one in a seven-part series on efficiently writing LaTeX documents.)
This article covers prerequisite knowledge for following along with the series, and was last modified on 20 July 2023.
Unfortunately, some prerequisite knowledge is unavoidable here, and I cover suggested prerequisites below (but always with a suggestion or mini-tutorial for getting up to speed). I believe you should be comfortable with the material in this article to get the most out of this series.
Prerequisite: you know what LaTeX is, have a working LaTeX distribution installed locally on your computer, and know how to use it, at least for creating basic documents.
Among other things, this means you should have the
latexmk programs installed on your system and available from a command line.
See the LaTeX project’s official installation instructions for installing LaTeX on various operating systems.
I recommend the tutorial at learnlatex.org as a starting point for learning LaTeX. Another decent option, despite the clickbait title, is Overleaf’s Learn LaTeX in 30 minutes. Note that you can find hundreds of other LaTeX guides on the Web, but this can be just as overwhelming as it is helpful. Be wary of poorly written or non-comprehensive tutorials, of which there are unfortunately plenty. The LaTeX project’s list of helpful links is a good place to find high-quality documentation and tutorials.
Prerequisite: you know what Vim is, have a working local installation of Vim/Neovim (or gVim/MacVim) on your computer, and know how to use it, at least for basic text editing (for example at the level of
At the risk of belaboring the obvious, this means you must have either the
nvim programs (or their GUI variants) installed and available on a command line.
Installation: Vim should come installed on most of the Unix-based systems this series is written for. Unfortunately the official instructions for installing Vim aren’t particularly inviting to beginners; for installation I suggest using Homebrew on macOS or consulting your distribution’s package manager on Linux.
And here are the official instructions for installing Neovim (which are much friendlier to beginners than Vim’s instructions). If you are choosing between Vim and Neovim specifically for the purpose of this series, I encourage you to choose Neovim: connecting Neovim to your PDF reader will be easier because of Neovim’s implementation of the remote procedure call protocol.
To get started with Vim/Neovim, try the interactive Vim tutorial (usually called the “Vim tutor”) that ships with Vim. You access the Vim tutor differently depending on your choice of Vim and Neovim.
nvimin a terminal. Then, from inside Neovim, type
:Tutorand press the Enter key to open the Vim tutor.
After (or in place of) the Vim tutor, consider reading through Learn Vim the Smart Way.
Prerequisite: if you use Neovim, you should know how to navigate the small differences between Neovim and Vim, for example Neovim’s
init.vim file replacing Vim’s
vimrc or the user’s Neovim configuration files living at
~/.config/nvim as opposed Vim’s
(Nontrivial differences, such as the server configuration required to set up inverse search with a PDF reader, are explained separately for both editors.)
:help vim-differencesor read the equivalent online version.
Prerequisite: you have installed Vim plugins before,
have a preferred plugin installation method (e.g. Vim 8+/Neovim’s built-in plugin system,
and will know what to do when told to install a Vim plugin.
For most users, I suggest using the well-regarded Vim-Plug plugin to manage your plugins (yes, this is a plugin that manages other plugins). The Vim-Plug GitHub page contains everything you need to get started.
If you prefer to manage your plugins manually, without third-party tools, use Vim/Neovim’s built-in plugin management system.
The relevant documentation lives at
:help packages but is unnecessarily complicated for a beginner’s purposes.
When getting started with the built-in plugin system, it is enough to perform the following:
packinside your root Vim configuration folder (i.e. create
~/.vim/pack/if using Vim and
~/.config/nvim/pack/if using Neovim).
pack/, create an arbitrary number of directories used to organize your plugins by category (e.g. create
pack/file-specific/, etc.). These names can be anything you like and give you the freedom to organize your plugins as you see fit. You probably just want to start with one plugin directory, e.g.
pack/plugins/, and create more if needed as you plugin collection grows.
start/(you will end up with e.g.
Since that might sound abstract, an example shell session used to install the VimTeX, UltiSnips, and Vim-Dispatch plugins (all used later in this series) using Vim/Neovim’s built-in plugin system would look like this:
# Change directories to the root Vim config directory cd ~/.vim # for Vim cd ~/.config/nvim # for Neovim # Create the required package directory structure mkdir -p pack/plugins/start cd pack/plugins/start # Clone the plugins' GitHub repos from inside `start/` git clone https://github.com/lervag/vimtex git clone https://github.com/SirVer/ultisnips git clone https://github.com/tpope/vim-dispatch
For orientation, the resulting file structure would be:
~/.vim/ └── pack/ └── plugins/ └── start/ ├── vimtex/ ├── ultisnips/ └── vim-dispatch/
The VimTeX, UltiSnips, and Vim-Dispatch plugins would then automatically load whenever Vim starts up.
If you install a plugin manually, its documentation will not be automatically available with Vim’s
To generate the plugin documentation, first ensure the plugin has a
doc directory, which is where documentation should be stored.
If a plugin
doc directory exists, you can generate its documentation with the Vim command:
You can also just use
:helptags ALL to generate documentation for all plugins with a
:help helptags for background.
Prerequisite: You should be comfortable using Vim/Neovim’s excellent built-in documentation, which you access with the
The Vim documentation is hyperlinked, and if you have syntax highlighting enabled, clickable hyperlinks to help chapters and sections should be clearly highlighted. The following two key combinations will help you navigate the Vim help files:
<Ctrl>](i.e. the control key and the right square bracket) with your cursor over a highlighted documentation section to jump to that section.
<Ctrl>o(the control key and the lowercase
o) to jump backward through your navigation history (e.g. to return to your original position before pressing
For more information, read
:help 01.1, which explains the basics of the Vim documentation, and
:help notation, which explains the notation used in the Vim documentation.
If you’re only interested in the snippet and VimTeX articles you can ignore this prerequisite; it applies mainly to PDF reader integration.
Prerequisite: To follow this series’s guides on PDF reader integration, you should be using Linux, macOS, or some other Unix variant.
If you use Windows, I suggest you follow along with the series as is—aside from the PDF reader article, most of the series will be directly applicable and you should still find plenty of helpful techniques and ideas. But you will need to find another resource for PDF reader integration on Windows—I suggest the VimTeX documentation.
If you use some exotic flavor of Unix, I assume you know enough of what you are doing to adapt this series’s Linux-based suggestions to your platform.
This is relevant only if you plan on using UltiSnips for snippets. You can ignore this Python dependency if you plan on using Luasnip as a snippet plugin (described later in the series).
Prerequisite: If you’ll use UltiSnips for snippets, you need a working Python 3+ installation and access to
pip/pip3 to install Python packages.
I suggest installing Python using your distribution’s package manager on Linux and using Homebrew on macOS.
Both of these options should give you a reliable, up-to-date version of Python that includes
If you discover that you have multiple, conflicting installations of Python on your system (this is risk on macOS in particular, which ships an outdated version by default), refer to one of the many guides on the Internet for cleaning up a Python 3 installation on your operating system.
In any case, you should end up with the
pip3 commands available from a command line.
Prerequisite: You are comfortable with the concept of calling simple command line programs from a terminal emulator, for example using
pdflatex myfile.tex to compile the LaTeX file
python3 myscript.py to run a Python script, or even something as simple as
echo "Hello world!" to write text to standard output.
Prerequisite: you have a preferred method for installing new software onto your computer and know yow to use it.
Prerequisite: You are familiar with the more common abbreviations and macros used in shell scripting.
The abbreviations you should know for this series are:
~(the tilde) is shorthand for the home directory
.is shorthand for the current working directory
..is shorthand for one directory above the current working directory
*is the match-all wildcard character used in glob patterns.
Prerequisite: You know what “e.g.” and “i.e.” mean—I will use both throughout this series. (While these abbreviations might be obvious to some people, they could very well be exotic to others, for example non-native English speakers or anyone previously unfamiliar with technical or academic writing.)
“e.g.” means “for example”; it is an abbreviation of the Latin phrase exemplī grātiā, which means “for the sake of an example”. For more information consult Wiktionary or the Internet.
The VimTeX function
1if the cursor is inside a LaTeX math zone (e.g. inside an
equationenvironment or between inline math
$ $symbols) and
Equivalent meaning, using “for example”:
The VimTeX function
1if the cursor is inside a LaTeX math zone (for example inside an
equationenvironment or between inline math
$ $symbols) and
“i.e.” means “that is” and is usually used as a clarification of a previous statement; it is an abbreviation of the Latin phrase id est, which, surprise surprise, means “that is”. For more information consult Wiktionary or search the Internet.
The VimTeX shortcuts
]*let you move between the boundaries of LaTeX comments (i.e. any text beginning with
Equivalent meaning, using “that is”:
The VimTeX shortcuts
]*let you move between the boundaries of LaTeX comments (that is any text beginning with
The original writing, images, and animations in this series are licensed under the Creative Commons Attribution-NonCommercial-ShareAlike 4.0 International License.