*vimtex.txt* A modern Vim/neovim filetype and syntax plugin for LaTeX files. *VimTeX* *Vimtex* *vimtex* Author: Karl Yngve Lervåg License: MIT license {{{ Copyright (c) 2021 Karl Yngve Lervåg Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions: The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software. The software is provided "as is", without warranty of any kind, express or implied, including but not limited to the warranties of merchantability, fitness for a particular purpose and noninfringement. In no event shall the authors or copyright holders be liable for any claim, damages or other liability, whether in an action of contract, tort or otherwise, arising from, out of or in connection with the software or the use or other dealings in the software. }}} ============================================================================== CONTENTS *vimtex-contents* Introduction |vimtex-introduction| Comment on internal tex plugin |vimtex-comment-internal| Feature overview |vimtex-features| Requirements |vimtex-requirements| Support for multi-file projects |vimtex-multi-file| Support for TeX specifiers |vimtex-tex-directives| Package detection |vimtex-package-detection| Integration with other plugins |vimtex-and-friends| Usage |vimtex-usage| Default mappings |vimtex-default-mappings| Options |vimtex-options| Commands |vimtex-commands| Map definitions |vimtex-mappings| Insert mode mappings |vimtex-imaps| Events |vimtex-events| Text objects |vimtex-text-objects| Completion |vimtex-completion| Complete citations |vimtex-complete-cites| Complete labels |vimtex-complete-labels| Complete commands |vimtex-complete-commands| Complete environments |vimtex-complete-environments| Complete file names |vimtex-complete-filenames| Complete glossary entries |vimtex-complete-glossary| Complete packages |vimtex-complete-packages| Complete documentclasses |vimtex-complete-classes| Complete bibliographystyles |vimtex-complete-bibstyle| Autocomplete |vimtex-complete-auto| coc.nvim |vimtex-complete-coc.nvim| deoplete |vimtex-complete-deoplete| Neocomplete |vimtex-complete-neocomplete| ncm2 |vimtex-complete-ncm2| nvim-completion-manager |vimtex-complete-ncm| YouCompleteMe |vimtex-complete-youcompleteme| VimCompletesMe |vimtex-complete-vcm| nvim-cmp |vimtex-complete-nvim-cmp| nvim-compe |vimtex-complete-nvim-compe| MUcomplete |vimtex-complete-mucomplete| Folding |vimtex-folding| Indentation |vimtex-indent| Syntax highlighting |vimtex-syntax| Syntax core specification |vimtex-syntax-core| Syntax package specification |vimtex-syntax-packages| Syntax conceal |vimtex-syntax-conceal| Syntax group reference |vimtex-syntax-reference| Navigation |vimtex-navigation| Include expression (gf command) |vimtex-includeexpr| Table of contents |vimtex-toc| Custom mappings |vimtex-toc-custom-maps| Denite/Unite source |vimtex-denite| / |vimtex-unite| fzf.vim integration |vimtex-fzf| Compilation |vimtex-compiler| Latexmk |vimtex-compiler-latexmk| Latexrun |vimtex-compiler-latexrun| Tectonic |vimtex-compiler-tectonic| Arara |vimtex-compiler-arara| Generic |vimtex-compiler-generic| Syntax Checking (Linting) |vimtex-lint| Grammar Checking |vimtex-grammar| textidote |vimtex-grammar-textidote| vlty |vimtex-grammar-vlty| View |vimtex-view| Viewer configuration |vimtex-view-configuration| Evince |vimtex-view-evince| MuPDF |vimtex-view-mupdf| Okular |vimtex-view-okular| qpdfview |vimtex-view-qpdfview| Sioyek |vimtex-view-sioyek| Skim |vimtex-view-skim| SumatraPDF |vimtex-view-sumatrapdf| TeXShop |vimtex-view-texshop| Zathura |vimtex-view-zathura| Zathura (simple) |vimtex-view-zathura-simple| Synctex |vimtex-synctex| Forward search |vimtex-synctex-forward-search| Inverse search |vimtex-synctex-inverse-search| LaTeX Documentation |vimtex-latexdoc| Context menu |vimtex-context-menu| Citation context |vimtex-context-citation| Code structure |vimtex-code| API |vimtex-code-api| FAQ |vimtex-faq| Troubleshooting |vimtex-troubleshooting| Credits |vimtex-credits| Changelog |vimtex-changelog| ============================================================================== INTRODUCTION *vimtex-introduction* VimTeX provides convenient functionality for editing LaTeX documents. The main goal of VimTeX is to be simple, functional, and to be easy to customize and evolve. The documentation is understandably too long for a full read through. It is recommended that new users read or skim the entire introduction, as it should give a clear idea of what VimTeX is and is not. The remaining part of the documentation should then be considered a reference for the various parts of the plugin. ------------------------------------------------------------------------------ COMMENT ON INTERNAL TEX PLUGIN *vimtex-comment-internal* Vim ships with pretty decent LaTeX support out of the box. In particular, it provides syntax highlighting (|ft-tex-syntax|), indentation (see the source file $VIMRUNTIME/indent/tex.vim for the documentation), and some sensible options (|ft-tex-plugin|). *vimtex-tex-flavor* When VimTeX is active, it will override the internal TeX plugin for the filetype `tex` (|ft-tex-plugin|), both for syntax highlighting and for filetype specific features. To prevent the unexpected behaviour where `.tex` files by default will be recognized as the filetype `plaintex` (|ft-plaintex-syntax|) for e.g. empty documents, VimTeX overrides the filetype detection for `.tex`. The user may prevent this overriding by specifying the |g:tex_flavor| option something different than `'latex'`. ----------------------------------------------------------------------------- FEATURE OVERVIEW *vimtex-features* - Document compilation with `latexmk`, `latexrun`, `tectonic` or `arara` - LaTeX log parsing for quickfix entries using - internal method - `pplatex` - Compilation of selected part of document - Support for several PDF viewers with forward search - `MuPDF` - `Zathura` - `Okular` - `qpdfview` - `SumatraPDF` - Other viewers are supported through a general interface - Completion of - citations - labels - commands - file names for figures, input/include, includepdf, includestandalone - glossary entries - package and documentclass names based on available `.sty` and `.cls` files - Document navigation through - table of contents - proper settings for |'include'|, |'includeexpr'|, |'suffixesadd'| and |'define'|, which among other things - allow |include-search| and |definition-search| - give enhanced |gf| command - Easy access to (online) documentation of packages - Word count (through `texcount`) - Motions *vimtex-motions* - Move between section boundaries with `[[`, `[]`, `][`, and `]]` - Move between environment boundaries with `[m`, `[M`, `]m`, and `]M` - Move between math environment boundaries with `[n`, `[N`, `]n`, and `]N` - Move between frame environment boundaries with `[r`, `[R`, `]r`, and `]R` - Move between comment boundaries with `[*` and `]*` - Move between matching delimiters with `%` - Text objects - `ic` `ac` Commands - `id` `ad` Delimiters - `ie` `ae` LaTeX environments - `i$` `a$` Math environments - `iP` `aP` Sections - `im` `am` Items - Other mappings - Delete the surrounding command, environment or delimiter with `dsc`/`dse`/`ds$`/`dsd` - Change the surrounding command, environment or delimiter with `csc`/`cse`/`cs$`/`csd` - Toggle starred command or environment with `tsc`/`tse` - Toggle inline and displaymath with `ts$` - Toggle between e.g. `()` and `\left(\right)` with `tsd`/`tsD` - Toggle (inline) fractions with `tsf` - Toggle line-break macro `\\` with `tsb` - Close the current environment/delimiter in insert mode with `]]` - Add `\left ... \right)` modifiers to surrounding delimiters with `` - Insert new command with `` - Convenient insert mode mappings for faster typing of e.g. maths - Context menu on citations (e.g. `\cite{...}`) mapped to `` - Folding - Indentation - Syntax highlighting - A consistent core syntax specification - General syntax highlighting for several popular LaTeX packages - Nested syntax highlighting for several popular LaTeX packages - Highlight matching delimiters - Support for multi-file project packages - `import` - `subfiles` ------------------------------------------------------------------------------ REQUIREMENTS *vimtex-requirements* The following is a list of specific requirements for running VimTeX and some of its key features. Windows users should also read |vimtex-faq-windows|. Vim version ~ *vimtex_version_check* VimTeX requires Vim version 8.2.3995 or neovim version 0.9.5. It will not load for older versions, unless one adds >vim let g:vimtex_version_check = 0 < to one's `vimrc` file. This might work, but issues due to older versions than the mentioned here will be ignored. Vim configuration ~ VimTeX requires |:filetype-plugin-on| and optionally |:filetype-indent-on|. There are several features in VimTeX that depend on the syntax parsing used for syntax highlighting. Examples include functions like |vimtex#syntax#in_mathzone| and text objects like |(vimtex-i$)|. This is important to be aware of especially for neovim users who are interested in Tree-sitter. If you use Tree-sitter for syntax highlighting and thus disable the normal Vim syntax feature, then you will also lose the VimTeX features that depend on the built-in syntax parser. For more info, see |vimtex-faq-treesitter|. Some of the VimTeX scripts contain UTF-8 characters, and as such, it is necessary to have the 'encoding' option set to utf8. This is not necessary in neovim, only in Vim. Add the following to your vimrc file: >vim set encoding=utf8 Compiler backend ~ VimTeX uses `latexmk`, `latexrun`, `tectonic` or `arara` to compile the LaTeX document. `latexmk`: http://users.phys.psu.edu/~collins/software/latexmk-jcc "a perl script for running LaTeX the correct number of times to resolve cross references, etc; it also runs auxiliary programs (e.g. bibtex). It has a number of other useful capabilities, for example to start a previewer and then run latex whenever the source files are updated, so that the previewer gives an up-to-date view of the document. The script runs on both UNIX and MS-WINDOWS (XP, etc)." [Copied from the latexmk page.] (|vimtex-compiler-latexmk|) `latexrun`: https://github.com/aclements/latexrun Similar to `latexmk` in that it runs the desired LaTeX engine an appropriate number of times, including `bibtex`/`biber`. However, it differs in philosophy in that it only does the build part. It does not support continuous builds, nor automatic starting of the viewer. However, it does parse the output log in order to provide a more concise list of relevant warnings and error messages (this has currently not been adapted to VimTeX, as of yet). (|vimtex-compiler-latexrun|) `tectonic`: https://tectonic-typesetting.github.io/ `tectonic` is a complete, self-contained TeX/LaTeX engine, powered by XeTeX and TeXLive. It doesn't support continuous build like `latexmk` but it presents other worth mentioning features such as automatic support file downloading along with reproducible builds and full Unicode and OpenType fonts support thanks to the power of XeTeX. (|vimtex-compiler-tectonic|) `arara`: https://github.com/cereda/arara `arara` is a TeX automation tool similar to the above mentioned tools, but where the compilation behaviour is typically defined in the preamble of the document. (|vimtex-compiler-arara|) Clientserver ~ *vimtex-clientserver* Vim requires |+clientserver| in order to allow inverse search from the PDF viewer to Vim (see |vimtex-synctex-inverse-search|). The clientserver is used by VimTeX. Thus, if one uses Vim one must ensure that it starts a server. Neovim does not have this requirement. A server will be started automatically if Vim is running on Windows or if it is running in a GUI (gVim). If you use Vim under a terminal in Linux or MacOS, a server will not be started by default. Also, MacVim users should be aware of some differences from regular Vim and should therefore read |macvim-clientserver| carefully. You can use |remote_startserver()| to start a server from your `vimrc` file. The following vimrc configuration snippet will ensure that Vim starts with a server, if possible: >vim if empty(v:servername) && exists('*remote_startserver') call remote_startserver('VIM') endif < Alternatively, Vim can be started with the command line option `--servername`, e.g. `vim --servername VIM` . The simplest way to ensure this is to add an alias to your `.bashrc` (or similar), that is, add: >bash alias vim='vim --servername VIM' < One can use |serverlist()| to check whether a server was successfully started, e.g. with `:echo serverlist()`. Neovim does not implement the same clientserver feature. Instead, it implements the MessagePack-RPC protocol (see |RPC|). VimTeX relies on this protocol in the same fashion as the clientserver. Both Vim and neovim have the |v:servername| variable that contains the name/location of the server with which we need to communicate. ------------------------------------------------------------------------------ SUPPORT FOR MULTI-FILE PROJECTS *vimtex-multi-file* VimTeX supports most multi-file documents and has several methods to locate the `main` document. Locating this file is very important, because the main file is the one that must be compiled. The default method for locating the main file uses a directory-scan algorithm that searches for a main LaTeX file, see method 6 below. It is expected to work in the vast majority of cases. There are several alternative methods for specifying the main file that can be more flexible and are relevant for certain work flows and use cases. These methods all require some explicit declaration of the main file and are therefore tried prior to the directory scan. The complete list of methods in the order of priority is as follows and are then described in more detail: 1. Buffer variable 2. TeX root directive 3. Subfiles package 4. File `.latexmain` specifier 5. Local `latexmkrc` file specifier (from `@default_files` option) 6. Directory scan *b:vimtex_main* Buffer variable ~ The main file may be specified through the buffer variable `b:vimtex_main`. To take effect, it has to be set prior to loading the buffer. If set after the buffer is already loaded, |:VimtexReloadState| (by default bound to |lX|) can be used to make VimTeX aware of its new value. A convenient way to use this feature is to add an |BufReadPre| |autocmd| in one's |vimrc|. An example is warranted: >vim augroup VimTeX autocmd! autocmd BufReadPre /path/to/project/*.tex \ let b:vimtex_main = '/path/to/project/main.tex' augroup END < Note: When writing such rules, one should be aware that the `*` is not the same as regular globbing because it also includes directory separators. Also, one should use `/` on every OS. See |file-pattern| for more info on the |autocmd| file pattern syntax. Note: Users may be interested in the concept of project specific vim configuration. This is supported in Vim, see 'exrc' and 'secure'. There are also several plugins to help work with project specific settings, such as: * https://github.com/embear/vim-localvimrc * https://github.com/tpope/vim-projectionist * https://github.com/jenterkin/vim-autosource * https://github.com/ii14/exrc.vim * https://github.com/MarcWeber/vim-addon-local-vimrc/ * https://github.com/MunifTanjim/exrc.nvim (neovim only) * See also: https://superuser.com/questions/598947/setting-vim-options-only-for-files-in-a-certain-directory-tree/598970#598970 *vimtex-tex-root* TeX root directive ~ It is also possible to specify the main TeX file with a comment in one of the first five lines of the current file. This is often referred to as a TeX directive, see |vimtex-tex-directives| for more info. The syntax is best described by some examples: >latex %! TEX root = /path/to/my-main.tex % ! TeX root = ../*.tex %!Tex Root=**/main.tex %! TeX root: ../main.tex < As can be seen, the words "tex root" are recognized regardless of casing and the spaces are ignored. Also, both a colon and an equal sign can be used. VimTeX parses this directive during initialization. Thus, users should be aware that they need to reload (with |:VimtexReload|) or restart Vim/neovim if they change the TeX root directive. Note: It is allowed to use a globbing pattern (see |wildcards|). If there are multiple matches, then VimTeX will ask for input when the buffer is opened. *vimtex-subfiles* *vimtex-import* Subfiles package ~ VimTeX also supports the `import` [0] and the `subfiles` [1] packages that can be used to make it easier to work with multi-file projects. If one uses the `subfiles` package, the |:VimtexToggleMain| command is particularly useful. Also note the option |g:vimtex_subfile_start_local|, which can be used to automatically start in the local mode when opening a subfile document. With `subfiles`, included files will typically look like this: >latex \documentclass[]{subfiles} \begin{document} ... \end{document} < Here `` is the path to the main file. It must be specified as relative to the particular subfile. So, given the structure: > main.tex sub/sub.tex < The header in `sub.tex` should be `\documentclass[../main.tex]{subfiles}`. Absolute paths like `/home/user/main.tex` are also allowed and should work as expected. [0]: https://www.ctan.org/pkg/import [1]: https://www.ctan.org/pkg/subfiles File .latexmain specifier ~ In some cases, it might be preferable to specify the main file by creating an indicator file. The indicator file should be an empty file, and the name must be the name of the desired main file with `.latexmain` appended. An example should make this clear: > path/file.tex path/file.tex.latexmain path/sections/file1.tex path/sections/file2.tex < Here `path/file.tex.latexmain` indicates for `file1.tex` and `file2.tex` that `path/file.tex` is the main LaTeX file. Local latexmkrc file specifier ~ It is possible to specify to latexmk which files to compile with the `@default_files` option in the `latexmkrc` configuration file. VimTeX supports reading this option in any LOCAL `latexmkrc` or `.latexmkrc` file. Note: `@default_files` is a list of files, VimTeX will use the first entry that is found. Directory scan ~ If the above methods don't give an appropriate candidate for a main file of the present file, then a search for a suitable main file from the current directory and upwards is started. A candidate `.tex` file qualifies as a main file if the following three requirements are all satisfied: 1. It includes the present file, either directly or indirectly. 2. The expanded content contains a `\documentclass` line near the top. 3. The expanded content contains `\begin{document}`. Notice that the main file itself does not need to contain the `\documentclass` line and `\begin{docment}`, since these can stem from included `.tex` files. The option |g:vimtex_include_indicators| is used by the parser to specify commands that include `.tex` files for the recursive expansion. In cases where automatic detection of the main file through the directory scan fails, one may explicitly set up method 1 to 5 instead. The |vimtex-tex-root| is usually a good alternative. Note: Recursive directory descents are not performed to find the main file. That is, if the current file is `./B/chapter.tex` then `./A/main.tex` will not be found as the main file, because the descent to subdirectory `./A/` is not performed. ------------------------------------------------------------------------------ SUPPORT FOR TEX DIRECTIVES *vimtex-tex-directives* VimTeX supports two of the commonly used TeX directives [0]: the TeX root and the TeX program directive. The TeX root directive was already described above, see |vimtex-tex-root|. *vimtex-tex-program* The TeX program directive works by specifying the TeX compiler program in a comment in one of the first lines of the main project file. It is parsed only when it is required by a compiler backend. The syntax is best explained with an example: >latex %! TeX program = lualatex %! TEX TS-program = xelatex The left-hand side must contain the text "tex program" or "tex ts-program" and as with |vimtex-tex-root|, the words are recognized regardless of casing and the spaces are ignored. The right-hand side must correspond to a key in the |g:vimtex_compiler_latexmk_engines| or |g:vimtex_compiler_latexrun_engines| dictionaries. See also [0,1]. [0]: https://tex.stackexchange.com/q/78101/34697 [1]: https://github.com/lervag/vimtex/issues/713 ------------------------------------------------------------------------------ PACKAGE DETECTION *vimtex-package-detection* VimTeX maintains a list of latex packages that are required by the current project. This list is used by VimTeX for instance to determine which commands to suggest during command completion (see |vimtex-complete-commands|) and which packages to look up documentation for (see |vimtex-doc-package|). The list can be viewed with |:VimtexInfo|. The package list is determined in two ways: 1. If a `.fls` file exists having the name of the main file, it is scanned. This file is created by `latex` (or `pdflatex`, `xelatex`, ...) if it is run with the `-recorder` option (which is set by default when using latexmk, unless overridden in an initialization file). Parsing the `.fls` file is done both at VimTeX initialization and after each successful compilation, if possible. Note: Parsing after successful compilations requires that one uses a) continuous compilation with callbacks (see the `callback` option for |g:vimtex_compiler_latexmk|), or b) single-shot compilation. 2. Otherwise, the preamble is parsed for `\usepackage` statements. This is slower and less accurate than `.fls` file parsing. Therefore, it is only done during VimTeX initialization. If desired, one may manually reload VimTeX to parse the preamble again during an editing session. See |:VimtexReload| and |(vimtex-reload)| (by default mapped to `lx`). ------------------------------------------------------------------------------ INTEGRATION WITH OTHER PLUGINS *vimtex-and-friends* VimTeX provides a lot of convenient and useful features for working with LaTeX files. However, there are several features that one might expect to be part of VimTeX, but that are left out because they are better served by other plugins. Let's call them "friends". The following is an overview of some such features. We also try to give hints and suggestions for how to best integrate with VimTeX experience, if that is applicable. * Linting and syntax checking |vimtex-af-linting| * Snippets/Templates |vimtex-af-snippets| * Tag navigation |vimtex-af-tag-nav| * Manipulate surrounding cmds/delims/envs |vimtex-af-surround| * Enhanced matching and highlighting of delimiters |vimtex-af-enhanced-matchparen| * Formatting |vimtex-af-formatting| * Filetype plugin for bib files |vimtex-af-ftplugin-bib| * Language servers (texlab & ltex) |vimtex-af-lsp| Linting and syntax checking ~ *vimtex-af-linting* VimTeX has some support for linting through the |:compiler| command, see |vimtex-lint|. There exists several more dedicated, automatic linting plugins. The following plugins have support for (La)TeX syntax checking through `lacheck` [0], `chktex` [1], and `proselint` [2]. `ale` https://github.com/dense-analysis/ale `neomake` https://github.com/neomake/neomake `syntastic` https://github.com/vim-syntastic/syntastic `neomake` also supports `rubberinfo` [3]. One may also be interested in `blacktex` [4], which may be used to clean up/fix LaTeX code. [0]: https://www.ctan.org/pkg/lacheck [1]: http://www.nongnu.org/chktex/ [2]: http://proselint.com/ [3]: https://www.systutorials.com/docs/linux/man/1-rubber-info/ [4]: https://github.com/nschloe/blacktex Snippets/Templates ~ *vimtex-af-snippets* Snippets and/or templates are provided by for instance `neosnippet` and `UltiSnips`. See |vimtex-neosnippet| and |vimtex-UltiSnips| for more info. Tag navigation ~ *vimtex-af-tag-nav* One may navigate by tags with the |CTRL-]| mapping, e.g. from `\eqref{eq:example}` to the corresponding `\label{eq:example}`. However, this requires that a tag file has been generated with |ctags|. I recommend that one uses the maintained version of ctags [0]. In addition, I recommend that one uses a plugin that automatically generates the tag files as necessary, e.g. |gutentags| [1]. See |vimtex-faq-tags| and |vimtex-faq-tags-bibtex| for concrete examples. [0]: https://ctags.io/ [1]: https://github.com/ludovicchabant/vim-gutentags Manipulate surrounding commands/delimiters/environments ~ *vimtex-af-surround* VimTeX provides mappings that change, delete and toggle commands, delimiters and environments (see the `ds`, `cs` and `ts` family of mappings listed under |vimtex-default-mappings|). These mappings are inspired by the great `surround.vim` [0] (|surround.txt|) by Tim Pope, which provides mappings to manipulate surrounding delimiters such as `''`, `""`, `()`, `[]`, `{}`, and `<>`. As such, the mappings from VimTeX should work well together with, and as an extension of, `surround.vim`. Consider also the customization described under |vimtex-faq-surround|. The mappings may be repeated with the dot (|.|) command. See also |g:vimtex_delim_list| if you are interested in customizing the delimiter pairs that are recognized. A different possibility is to use `vim-sandwich` [1] (|sandwich.txt|) by Machakann, which may be considered a generalisation of `surround.vim` in that it can handle much more complex sets of delimiters. `vim-sandwich` is relatively easy to expand with custom surroundings and has built in support for LaTeX-specific surroundings such as quotations and math delimiters. For a list of supported delimiters, see |sandwich-filetype-recipes|. `vim-sandwich` supports `vim-repeat` [2] in addition to `visualrepeat.vim` [3]. Note: The default mappings of `vim-sandwich` differ from those of `surround.vim`, in that they use `s` as the prefix. E.g., to add surroundings, one uses `sa{motion/textobject}{type-of-surrounding}` instead of `ys{motion/textobject}{type-of-surrounding}`. If one prefers the map variants from `surround.vim`, these are also available as an option, see |sandwich-miscellaneous|. And it is also easy to define custom mappings, if one prefers that. Note: `vim-sandwich` actually consists of three plugins that work together. One should make sure to read the docs for all of them: |sandwich.txt|, |operator-sandwich.txt|, and |textobj-sandwich.txt|. [0]: https://github.com/tpope/vim-surround [1]: https://github.com/machakann/vim-sandwich [2]: https://github.com/tpope/vim-repeat [3]: http://www.vim.org/scripts/script.php?script_id=3848 Enhanced matching and highlighting of delimiters ~ *vimtex-af-enhanced-matchparen* VimTeX highlights and allows navigation between matching pairs of delimiters including those in math mode, such as `\bigl(` and `\bigr)`, and the `\begin` and `\end` tags of environments. However, the implementation may be slow (see also |vimtex-faq-slow-matchparen|, and so one may use |g:vimtex_matchparen_enabled| to disable the highlighting). Alternatively, one may use the plugin |match-up| [0], which offers enhanced |matchparen| highlighting and `matchit.zip` style motions and |text-objects| for a variety of file types. For LaTeX documents, it: - Extends highlighting and the `%` motion to a number of middle delimiters including - `\bigm` and `\middle` marked delimiters - `\item`s in `itemize` and `enumerate` environments - `\toprule`, `\midrule`, `\bottomrule` in the `tabular` environment. - `\if`, `\else` and `\endif` Note: VimTeX does not support highlighting the middle delimiters. - Adds motions, `g%`, `[%`, and `]%` and text objects, `a%` and `i%` which move between matching delimiters and operate on delimited text. For example, with match-up enabled, >latex \left( \frac{a}{b} \middle| q \right) < the motion `%` will cycle through `\left(`, `\middle|`, and `\right)`, whereas with VimTeX only `\left(` and `\right)` will be matched. The motion `g%` will do the same, except in reverse. To enable the plugin match-up after installation, add the following to your vimrc: >vim let g:matchup_override_vimtex = 1 < Matching may become computationally intensive for complex LaTeX documents. If you experience slowdowns while moving the cursor, the following option is recommended to delay highlighting slightly while navigating: >vim let g:matchup_matchparen_deferred = 1 < Note: The exact set of delimiters recognized may differ between match-up and VimTeX. For example, the mappings `da%` and `dad` will not in general be identical, particularly if you have customized VimTeX's delimiters. [0]: https://github.com/andymass/vim-matchup Formatting ~ *vimtex-af-formatting* VimTeX has a custom |formatexpr| that may be enabled with the option |g:vimtex_format_enabled|. However, there are a lot of different styles for formatting LaTeX manuscripts. These are typically much more relevant when writing in collaboration with others. A good reference on this topic is [0], and note in particular the box "Directives for using LaTeX with version control systems". The most basic style is to hard wrap lines at a given column, e.g. 80 columns, and this is exactly the type of formatting that is supported by VimTeX. However, this is usually not very friendly when collaborating with others, as it tends to mess up diffs between versions of the document. Instead, one might want to consider one of these: a) keeping each sentence on a line (use soft wrapping) b) add additional indentation for split sentences [1] c) use semantic line feeds [2] In order to make it easier to use one of these styles of formatting, one may want to use an external formatter: - latexindent.pl [3] - vim-bucky [4] (note: this is an alpha version as of October 2018) - semantic-linebreaker [5] (note: this is a web-based tool) Further, there are a range of Vim plugins that can be used to format your document with external tools. Some of these also allow autoformatting of some kind. In no particular order: - neoformat [6] - vim-codefmt [7] - vim-autoformat [8] - ale [9] - vim-sentence-chopper [10] [0]: https://en.wikibooks.org/wiki/LaTeX/Collaborative_Writing_of_LaTeX_Documents [1]: http://dustycloud.org/blog/vcs-friendly-patchable-document-line-wrapping/ [2]: https://rhodesmill.org/brandon/2012/one-sentence-per-line/ [3]: https://github.com/cmhughes/latexindent.pl [4]: https://github.com/dbmrq/vim-bucky [5]: https://github.com/waldyrious/semantic-linebreaker [6]: https://github.com/sbdchd/neoformat [7]: https://github.com/google/vim-codefmt [8]: https://github.com/Chiel92/vim-autoformat [9]: https://github.com/dense-analysis/ale [10]: https://github.com/Konfekt/vim-sentence-chopper Filetype plugin for bib files ~ *vimtex-af-ftplugin-bib* VimTeX is not a full filetype plugin for bibliography files (`.bib`). However, it does alter the 'comments' and 'commentstring' options and provide basic indentation and folding; see |g:vimtex_indent_bib_enabled| and |g:vimtex_fold_bib_enabled|, respectively. Here are a couple of other related Vim plugins and external tools that might be of interest: - `bibtool` An external tool for formatting, sorting, filtering, merging, and more of `.bib` files. http://www.gerd-neugebauer.de/software/TeX/BibTool/ - `GooseBib` Some simple command-line tools to clean-up / modify BibTeX files. https://github.com/tdegeus/GooseBib - `bibtex-tidy` Another tool for formatting and cleaning `.bib` files. https://flamingtempura.github.io/bibtex-tidy/ - `tbibtools` A set of ruby-based bibtex-related utilities for sorting, reformatting, listing contents, and so on. Has optional Vim integration. https://www.vim.org/scripts/script.php?script_id=1915 See also https://github.com/lervag/vimtex/issues/1293 for some related discussions. Language servers ~ *vimtex-af-lsp* In recent years, language servers (LSPs) [0] have become very popular. There is a language server for LaTeX and bibtex called texlab [1]. It may be interesting both as an alternative to VimTeX and/or an addition. There is currently no known conflict between texlab and VimTeX, although there is some feature overlap. E.g., both texlab and VimTeX provides advanced completion in various contexts. As texlab is written in Rust and runs in a separate thread, it is no surprise that it will have a clear performance advantage. However, VimTeX does use caches to speed up completion which should in most cases work well. To use texlab, one must use an LSP client, e.g. |vim-lsp| [2], neovim's built-in LSP client [3], or |coc-nvim| [4, 5]. See also this VimTeX issue [6] for more information. In addition to texlab, there is also a dedicated grammar and spell checking language server called LTeX [7]. It relies on LanguageTool and supports both LaTeX and other markup languages. It may be a useful tool to use in conjunction with VimTeX as an alternative to |vimtex-grammar|. [0]: https://langserver.org/ [1]: https://github.com/latex-lsp/texlab [2]: https://github.com/prabirshrestha/vim-lsp [3]: https://github.com/neovim/nvim-lspconfig/blob/master/doc/server_configurations.md#texlab [4]: https://github.com/neoclide/coc.nvim [5]: https://github.com/fannheyward/coc-texlab [6]: https://github.com/lervag/vimtex/issues/1371 [7]: https://valentjn.github.io/ltex/index.html ============================================================================== USAGE *vimtex-usage* Default mappings |vimtex-default-mappings| Options |vimtex-options| Commands |vimtex-commands| Map definitions |vimtex-mappings| Insert mode mappings |vimtex-imaps| Events |vimtex-events| ------------------------------------------------------------------------------ DEFAULT MAPPINGS *vimtex-default-mappings* VimTeX is designed to be controlled by a selection of mappings. Note, though, that most of the mappings are also available as commands, see |vimtex-commands|. Many of the mappings use `l` as a common prefix, where the default || is `\`. Thus, `ll` will for most people mean `\ll`. The prefix may be changed with |g:vimtex_mappings_prefix|. The right-hand sides are provided as -mappings, see |using-|. For any given map, the default mapping will only be created if it does not already exist. This means that if a user defines a custom mapping, e.g. with >vim nmap li (vimtex-info) then the corresponding default left-hand side will not be mapped. 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. In the below list of mappings, LHS is the default mapping, RHS is the corresponding -maps, and MODE indicates in which vim mode the mappings are valid. See |map-modes| for an explanation of the various modes. The indicator refers to the prefix of the corresponding map command, e.g. `n` refers to an |nmap|, `nx` refers to both |nmap| and |xmap|, and so on. In addition to the mappings listed below, VimTeX provides convenient insert mode mappings to make it easier and faster to type mathematical equations. This feature is explained in more detail later, see |vimtex-imaps|. --------------------------------------------------------------------- ~ LHS RHS MODE ~ --------------------------------------------------------------------- ~ li |(vimtex-info)| `n` lI |(vimtex-info-full)| `n` lt |(vimtex-toc-open)| `n` lT |(vimtex-toc-toggle)| `n` lq |(vimtex-log)| `n` lv |(vimtex-view)| `n` lr |(vimtex-reverse-search)| `n` ll |(vimtex-compile)| `n` lL |(vimtex-compile-selected)| `nx` lk |(vimtex-stop)| `n` lK |(vimtex-stop-all)| `n` le |(vimtex-errors)| `n` lo |(vimtex-compile-output)| `n` lg |(vimtex-status)| `n` lG |(vimtex-status-all)| `n` lc |(vimtex-clean)| `n` lC |(vimtex-clean-full)| `n` lm |(vimtex-imaps-list)| `n` lx |(vimtex-reload)| `n` lX |(vimtex-reload-state)| `n` ls |(vimtex-toggle-main)| `n` la |(vimtex-context-menu)| `n` dse |(vimtex-env-delete)| `n` dsc |(vimtex-cmd-delete)| `n` ds$ |(vimtex-env-delete-math)| `n` dsd |(vimtex-delim-delete)| `n` cse |(vimtex-env-change)| `n` csc |(vimtex-cmd-change)| `n` cs$ |(vimtex-env-change-math)| `n` csd |(vimtex-delim-change-math)| `n` tsf |(vimtex-cmd-toggle-frac)| `nx` tsc |(vimtex-cmd-toggle-star)| `n` tse |(vimtex-env-toggle-star)| `n` ts$ |(vimtex-env-toggle-math)| `n` tsb |(vimtex-env-toggle-break)| `n` |(vimtex-env-surround-line)| `n` |(vimtex-env-surround-operator)| `n` |(vimtex-env-surround-visual)| `x` tsd |(vimtex-delim-toggle-modifier)| `nx` tsD |(vimtex-delim-toggle-modifier-reverse)| `nx` |(vimtex-cmd-create)| `nxi` ]] |(vimtex-delim-close)| `i` |(vimtex-delim-add-modifiers)| `n` ac |(vimtex-ac)| `xo` ic |(vimtex-ic)| `xo` ad |(vimtex-ad)| `xo` id |(vimtex-id)| `xo` ae |(vimtex-ae)| `xo` ie |(vimtex-ie)| `xo` a$ |(vimtex-a$)| `xo` i$ |(vimtex-i$)| `xo` aP |(vimtex-aP)| `xo` iP |(vimtex-iP)| `xo` am |(vimtex-am)| `xo` im |(vimtex-im)| `xo` % |(vimtex-%)| `nxo` ]] |(vimtex-]])| `nxo` ][ |(vimtex-][)| `nxo` [] |(vimtex-[])| `nxo` [[ |(vimtex-[[)| `nxo` ]m |(vimtex-]m)| `nxo` ]M |(vimtex-]M)| `nxo` [m |(vimtex-[m)| `nxo` [M |(vimtex-[M)| `nxo` ]n |(vimtex-]n)| `nxo` ]N |(vimtex-]N)| `nxo` [n |(vimtex-[n)| `nxo` [N |(vimtex-[N)| `nxo` ]r |(vimtex-]r)| `nxo` ]R |(vimtex-]R)| `nxo` [r |(vimtex-[r)| `nxo` [R |(vimtex-[R)| `nxo` ]/ |(vimtex-]/| `nxo` ]* |(vimtex-]star| `nxo` [/ |(vimtex-[/| `nxo` [* |(vimtex-[star| `nxo` K |(vimtex-doc-package)| `n` --------------------------------------------------------------------- ~ ------------------------------------------------------------------------------ OPTIONS *vimtex-options* *g:vimtex_enabled* Set to 0 to disable VimTeX. Default value: Undefined. *g:vimtex_cache_root* Specify the cache directory for VimTeX. Default value: `'$XDG_CACHE_HOME/vimtex'` if `$XDG_CACHE_HOME` is defined `'~/.cache/vimtex'` otherwise *g:vimtex_cache_persistent* Specify whether to use persistent caching. Default value: 1 *g:vimtex_compiler_enabled* Use this option to disable/enable the `compiler` interface, see |vimtex-compiler|. Default value: 1 *g:vimtex_compiler_silent* Set this to 1 or |v:true| to silence the compiler messages during start, stop, and callbacks. Default: 0 *g:vimtex_compiler_method* This option sets the compiler method. There are two ways to configure this option: i) Explicity as a string. ii) Dynamically through a function. In the first variant, you can choose from the following list of compiler methods: Value Documentation Configuration ~ `latexmk` |vimtex-compiler-latexmk| |g:vimtex_compiler_latexmk| `latexrun` |vimtex-compiler-latexrun| |g:vimtex_compiler_latexrun| `tectonic` |vimtex-compiler-tectonic| |g:vimtex_compiler_tectonic| `arara` |vimtex-compiler-arara| |g:vimtex_compiler_arara| `generic` |vimtex-compiler-generic| |g:vimtex_compiler_generic| In the second variant, the option must be specified as the name of a function or a |Funcref|. Using a |Funcref| is only possible with Lua in Neovim. The function is passed the path to the main TeX file as a single string argument and must return the desired method as a string. The method must be one from the above list of available methods. Using a function allows a lot of flexibility in the choice of compiler method. For instance, one could use `arara` for files that have `arara` specifications at the top and fall back to `latexmk` for other files: >vim function! SetCompilerMethod(mainfile) if filereadable(a:mainfile) for line in readfile(a:mainfile, '', 5) if line =~# '^%\s*arara' return 'arara' endif endfor endif return 'latexmk' endfunction let g:vimtex_compiler_method = 'SetCompilerMethod' < Default value: `'latexmk'` *g:vimtex_compiler_clean_paths* A list of additional path expressions for generated files that you want to be cleaned by `:VimtexClean`. Note that this is NOT relevant for the compiler backends |vimtex-compiler-latexmk| and |vimtex-compiler-latexrun|. These backends provide their own clean implementations. Each expression is a glob expression (see |glob()| and |wildcards|) and each path is assumed rooted to the project root. For instance, to clean any generated `_minted` paths (including directories), you could use something like this: >vim let g:vimtex_compiler_clean_paths = ['_minted*'] < Warning: Each resolved path will be deleted with |delete()| with the `"rf"` flag! Note: For `latexmk`, a similar feature is available with `$clean_ext`; see the documentation https://texdoc.org/serve/latexmk/0. Default value: `[]` *g:vimtex_compiler_latexmk* This dictionary allows customization of the |vimtex-compiler-latexmk| compiler. The values set by the user will take precedence over the default values. Default value: >vim let g:vimtex_compiler_latexmk = { \ 'aux_dir' : '', \ 'out_dir' : '', \ 'callback' : 1, \ 'continuous' : 1, \ 'executable' : 'latexmk', \ 'hooks' : [], \ 'options' : [ \ '-verbose', \ '-file-line-error', \ '-synctex=1', \ '-interaction=nonstopmode', \ ], \} < The default value shows which entries may be changed. Here the different keys are explained in more detail: aux_dir ~ This option sets the directory for auxiliary output files. It corresponds to the `$aux_dir` option of `latexmk`. If the path is a relative path, then it is considered relative to the main project file. The value of this option should be either: 1) a string that represents a path, or 2) a |Funcref| with a single dictionary argument "file_info": > file_info = { root = … target = … target_basename = … target_name = … jobname = … } < This makes it possible to specify a dynamic `aux_dir`. It may be easier to understand from an example: >vim let g:vimtex_compiler_latexmk = {'aux_dir': {_ -> expand("%:t:r")}} < With the above setting, the `aux_dir` is set to the base name of the current file. E.g., If you do `vim test.tex`, the value becomes `test`. The specified auxiliary directory is created if it does not exist. Note 1: This option only works with `latexmk` version 4.27 and later. Note 2: If `$aux_dir` is added to `.latexmkrc`, then the `.latexmkrc` setting will have priority. Note 3: If |$VIMTEX_OUTPUT_DIRECTORY| is defined, it will have the highest priority. Note 4: The `-emulate_aux` option will be automatically passed to `latexmk` if this option is not empty. out_dir ~ This option sets the directory for the compilation output files. It corresponds to the `$out_dir` option in `latexmk`. If the path is a relative path, then it is considered relative to the main project file. The value is either a string or a |Funcref|, similar to the above described `aux_dir` key. The specified output directory is created if it does not exist. Note 1: This option only works with `latexmk` version 4.27 and later. Note 2: If `$out_dir` is added to `.latexmkrc`, then the `.latexmkrc` setting will have priority. Note 3: If |$VIMTEX_OUTPUT_DIRECTORY| is defined, it will have the highest priority. callback ~ If enabled, this option tells `latexmk` to run |vimtex#compiler#callback| after compilation is finished. continuous ~ If enabled, `latexmk` will run in continuous mode, i.e. with the `-pvc` argument. This means that the document is compiled automatically by `latexmk` every time a related file has been changed, until the processes is stopped. If disabled, `latexmk` will run single shot compilations. Note: The events |VimtexEventCompileStarted| and |VimtexEventCompileStopped| are only relevant when this option is enabled. executable ~ The name/path to the `latexmk` executable. hooks ~ A list of |Funcref|s. If running in continuous mode, each hook will be called for each line of output from `latexmk`, with that line as argument. E.g., to show information about the compilation run numbers, one could do this: >vim function! Callback(msg) let l:m = matchlist(a:msg, '\vRun number (\d+) of rule ''(.*)''') if !empty(l:m) echomsg l:m[2] . ' (' . l:m[1] . ')' endif endfunction let g:vimtex_compiler_latexmk = { 'hooks': [function('Callback')] } < options ~ This is a list of options that are passed to `latexmk`. The default options should work well for most people. Note: Options like `-pdf` or `-lualatex` should NOT be added to this list. These are options used to specify the LaTeX processor/engine, see instead |g:vimtex_compiler_latexmk_engines|. Note: Options may also be specified indirectly to `latexmk` through both a global and a project specific `.latexmkrc` file. One should know, though, that options specified on the command line has priority, and so if one wants to override one of the above default options, then one has to set this key to a list that contains the desired options. *g:vimtex_compiler_latexmk_engines* Defines a map between TeX program directive (|vimtex-tex-program|) and compiler engine. This is used by |vimtex-compiler-latexmk| to define the LaTeX program. The `_` key defines the default engine. Note: If the TeX program directive is not specified within the main project file, and if `$pdf_mode` is added to a project-specific `.latexmkrc` file, then the compiler engine will be deduced from the value of `$pdf_mode`. The supported values of `$pdf_mode` are 1 (pdflatex), 4 (lualatex) and 5 (xelatex). See the latexmk documentation for details. Default value: >vim let g:vimtex_compiler_latexmk_engines = { \ '_' : '-pdf', \ 'pdfdvi' : '-pdfdvi', \ 'pdfps' : '-pdfps', \ 'pdflatex' : '-pdf', \ 'luatex' : '-lualatex', \ 'lualatex' : '-lualatex', \ 'xelatex' : '-xelatex', \ 'context (pdftex)' : '-pdf -pdflatex=texexec', \ 'context (luatex)' : '-pdf -pdflatex=context', \ 'context (xetex)' : '-pdf -pdflatex=''texexec --xtx''', \} *g:vimtex_compiler_latexrun* This dictionary allows customization of the |vimtex-compiler-latexrun| compiler. The values set by the user will take precedence over the default values. Default value: >vim let g:vimtex_compiler_latexrun = { \ 'out_dir' : '', \ 'options' : [ \ '-verbose-cmds', \ '--latex-args="-synctex=1"', \ ], \} < The default value shows which entries may be changed. Here the different keys are explained in more detail: out_dir ~ See `out_dir` key of |g:vimtex_compiler_latexmk|. options ~ This is a list of options that are passed to `latexrun`. The default options should work well for most people. Note: By default, the option `-pdf` is also supplied to indicate the LaTeX engine. This may be changed on a per project basis with TeX directives, see |vimtex-tex-program| or the two compiler-specific options |g:vimtex_compiler_latexmk_engines| and |g:vimtex_compiler_latexrun_engines|. The latter two options may also be used to change the default engine. *g:vimtex_compiler_latexrun_engines* Defines a map between TeX program directive (|vimtex-tex-program|) and compiler engine, i.e. as should be specified to the `--latex-cmd` argument to `latexrun`. This is used by |vimtex-compiler-latexrun| to define the LaTeX program. The `_` key defines the default engine. Default value: >vim let g:vimtex_compiler_latexrun_engines = { \ '_' : 'pdflatex', \ 'pdflatex' : 'pdflatex', \ 'lualatex' : 'lualatex', \ 'xelatex' : 'xelatex', \} *g:vimtex_compiler_tectonic* This dictionary allows customization of the |vimtex-compiler-tectonic| compiler. The values set by the user will take precedence over the default values. Default value: >vim let g:vimtex_compiler_tectonic = { \ 'out_dir' : '', \ 'hooks' : [], \ 'options' : [ \ '--keep-logs', \ '--synctex' \ ], \} < The default value shows which entries may be changed. Here the different keys are explained in more detail: out_dir ~ See `out_dir` key of |g:vimtex_compiler_latexmk|. hooks ~ Same as |g:vimtex_compiler_latexmk| / `hooks`. options ~ This is a list of options that are passed to `tectonic`. The default options should work well for most people. For anyone who wishes to modify these, please note: - Don't use `--outdir` or `-o` here. Use the `out_dir` option instead. - Without `--keep-logs` (or `--keep-intermediates` or `-k)`, you won't see errors/warnings in the quickfix list when compilations finish. - By default, `tectonic` cleans all auxiliary files (such as `.aux`, `.toc`, etc.). If you omit the `--keep-logs` (or similar) options that specify to keep these files, |:VimtexClean| and |(vimtex-clean)| won't delete anything (as there is nothing to delete). *g:vimtex_compiler_arara* This dictionary allows customization of the |vimtex-compiler-arara| compiler. The values set by the user will take precedence over the default values. Default value: >vim let g:vimtex_compiler_arara = { \ 'options' : ['--log'], \ 'hooks' : [], \} < The default value shows which entries may be changed. Here the different keys are explained in more detail: options ~ This is a list of options that are passed to `arara`. The default options should work well for most people. hooks ~ Same as |g:vimtex_compiler_latexmk| / `hooks`. *g:vimtex_compiler_generic* This dictionary allows customization of the |vimtex-compiler-generic| compiler. This compiler is, as the name hints, generic. It allows to specify a custom command to run for compilation. As for the other compilers, the configuration values set by the user will take precedence over the default values. Default value: >vim let g:vimtex_compiler_generic = { \ 'command' : '', \ 'hooks' : [], \} < The default value shows which entries may be changed. Here the different keys are explained in more detail: command ~ This is the command to run to start compilation. This can be any command, and the command is run from the project root. hooks ~ Same as |g:vimtex_compiler_latexmk| / `hooks`. *g:vimtex_complete_enabled* Use this option to disable/enable VimTeX completion. Default value: 1 *g:vimtex_complete_smart_case* If enabled, then VimTeX will filter case sensitive if there is a capital letter in the completion input. This is only relevant if |g:vimtex_complete_ignore_case| is also enabled. Default value: Same as your 'smartcase' value *g:vimtex_complete_ignore_case* If enabled, then VimTeX will filter case insensitive. Default value: Same as your 'ignorecase' value *g:vimtex_complete_close_braces* This option controls whether to append a closing brace after a label or a citation has been completed. Default value: 0 *g:vimtex_parser_bib_backend* This option sets the desired default backend for parsing bibliographies. This is used e.g. for gathering completion candidates. Possible values: `bibtex`: The fastest, but most "hacky" solution. Still, time has proved that this works well! `vim`: The slowest but perhaps most robust solution, as it does not require any external utilities. `lua`: A Lua implementation of the Vim backend. About as fast as the `bibtex` parser, but this only works on Neovim. `bibparse`: Also fast, but might be more robust. Note: bibparse is an executable provided by the Perl package Text-BibTeX [0]. It should not be confused with the similarly named Python project [1]. The latter is deprecated in favor of GooseBib [2]. The Python projects bibparse and GooseBib are both based on the Python library `bibtexparser`. [0]: https://metacpan.org/dist/Text-BibTeX [1]: https://github.com/tdegeus/bibparse [2]: https://github.com/tdegeus/GooseBib `bibtexparser`: Also fast and possibly more robust. See the project Github page for more details: https://github.com/sciunto-org/python-bibtexparser Note: This requires that Python 3 is available to Vim/neovim (see |if_pyth| and |py3|) and that the `bibtexparser` Python module is installed and available. Some people may want to conditionally change this option if a backend is available. For example: >vim if executable('bibparse') let g:vimtex_parser_bib_backend = 'bibparse' endif < Default value: Vim: `bibtex` Neovim: `lua` *g:vimtex_parser_cmd_separator_check* This option specifies the policy for deciding whether successive groups of `[opt]` and `{arg}` following a `\command` should be recognized as arguments to that `\command`. In fact, parsing a LaTeX command without additional knowledge is a hard problem. When we read `\foo{bar}{baz}` — is `{baz}` going to be consumed as an argument to `\foo`? The only way to know this is to read the definition of the `\foo` command/macro. A pragmatic choice when we write a parser, therefore, is to rely on some heuristics and common practises. This will never be perfect, but it can be good enough for practical use. In VimTeX, the core heuristics are that a command will look like this: > \foo[[opt]{arg}]... \begin{name}[[opt]{arg}]... < The parser greedily swallows as many groups of `[opt]` and `{arg}` as possible as long as the function specified via this option returns true for the text between successive such groups. The default function will allow a line break and possibly white space on the preceding line before a new group. E.g.: >latex % command number of args % ------- -------------- \foo{bar}{baz} % 2 \foo{bar} {baz} % 1 \foo{bar} {baz} % 2 \foo{bar} {baz} % 2 \foo{bar}__ {baz} % 1 (_ indicates spaces) < The option should be either the name of the function (a string) or a |Funcref|. The function takes a single argument, which is the string between successive `[opt]` and `{arg}` groups. It should return |v:true| if the parser should continue and |v:false| if the parser should stop. A user may want to change this behaviour e.g. to specify that all whitespace should be allowed, including and up to a single newline: >vim function! MyCmdSeparatorRule(separator_string) return a:separator_string =~# '^\_s\+$' \ && count(a:separator_string, "\n") < 2 endfunction let g:vimtex_parser_cmd_separator_check = 'MyCmdSeparatorRule' < Note: This option is relevant for any feature that relies on the parsing of a command. This includes, but is not limited to the |(vimtex-ac)| text object (|vimtex-text-objects|). Note: |Funcref|s are only possible when it is used with neovim Lua configuration, because in Vimscript, variable names must be capitalized in order to point to |Funcref|s. Default: `'vimtex#cmd#parser_separator_check'` *g:vimtex_bibliography_commands* A list of command names for commands that include bibliography files. Each list entry is interpreted as a pattern (very magic, see |/\v|) to match a particular command name. This option may be useful if one defines custom commands that includes bibliography files. Default value: > ['%(no)?bibliography', 'add%(bibresource|globalbib|sectionbib)'] *g:vimtex_complete_bib* This option is a dictionary for controlling the citation completion. The keys each control a different thing as explained below. simple ~ Default value: 0 If zero, then the cite completion is "smart", i.e. not simple. This behaviour is described in more detail in |vimtex-complete-cites|. Note: It is usually better to use the "simple" mode if you use an autocomplete plugin (|vimtex-complete-auto|). *g:vimtex_complete_bib.match_str_fmt* match_str_fmt ~ Default value: `'@key [@type] @author_all (@year), "@title"'` The format used for the match string for bib completion candidates. That is, the string that the smart mode candidate matching is matched against. See |vimtex-complete-cites| for more info. The following keys may be used to define the string: > @author_all Full author list @author_short Shortened author list @key The bibtex key @title Title @type Type of entry @year Publication year < Since the author list can be large, the `@author_all` is truncated to 20 characters. This can be modified with the `auth_len` key (see below). menu_fmt ~ Default value: `'[@type] @author_short (@year), "@title"'` The format used for the `menu` entry for bib completion candidates (see |complete-items|). If the key is set to an empty string, then the `menu` entry is not added to the completion candidates. See the description of `match_str_fmt` for the allowed keys. info_fmt ~ Default value: `"TITLE: @title\nAUTHOR: @author_all\nYEAR: @year"` The format used for the `info` entry for bib completion candidates (see |complete-items|). See the description of `match_str_fmt` for the allowed keys. abbr_fmt ~ Default value: `''` The format used for the `abbr` entry for bib completion candidates (see |complete-items|). See the description of `match_str_fmt` for the allowed keys. auth_len ~ Default value: 20 Truncation length for author list with the `@author_all` format key in the format strings for `match_str_fmt`, `menu_fmt`, and `abbr_fmt`. custom_patterns ~ Default value: [] List of custom trigger patterns that may be used to allow completion for e.g. custom macros. If one wants to overwrite one of the keys, e.g. the `simple` entry, one can do: >vim let g:vimtex_complete_bib = { 'simple': 1 } < This does not modify the other keys and their default values. *g:vimtex_complete_ref* This option is a dictionary for controlling the label completion. The keys each control a different thing: custom_patterns ~ Default value: [] List of custom trigger patterns that may be used to allow completion for e.g. custom macros. For example, if one has defined the command `\figref`, one could add following custom pattern >vim let g:vimtex_complete_ref = { \ 'custom_patterns': ['\\figref\*\?{[^}]*$'] \ } *g:vimtex_context_pdf_viewer* Specify PDF viewer to use to open PDF files with the |vimtex-context-menu|, for instance for citations with the `file` key (see |vimtex-context-citation|). The default value is based on the |vimtex-view| and is determined as follows: * If |g:vimtex_view_method| is not `general`, then the specified viewer is used. However, the viewer will by default start without any of the regular options. * Else fall back to the value of |g:vimtex_view_general_viewer|. *g:vimtex_delim_list* A dictionary that defines the pairs of delimiters that are recognized by VimTeX for various commands and functions. The dictionary contains 5 sub dictionaries: `env_tex` Pairs of environment delimiters in normal TeX mode `env_math` Pairs of special math environment delimiters `delim_tex` Pairs of delimiters in normal TeX mode `delim_math` Pairs of delimiters in math mode `mods` Pairs of modifiers for math mode delimiters Each entry is a dictionary with the following format: > { \ 'name' : [ \ ['\(', '\)'], \ ['\[', '\]'], \ ['$$', '$$'], \ ['$', '$'], \ ], \ 're' : [ \ ['\\(', '\\)'], \ ['\\\@vim let g:vimtex_delim_list = { \ 'mods' : { \ 'name' : [ "..." ], \ } \} < Here the `re` entry was not provided, in which case it will be automatically generated based on the `name` entry. The remaining four entries will remain the default value. Some people may be interested in adding support for e.g. german or french quotation marks. These may be added by extending the default `delim_tex` entries, like this: >vim let g:vimtex_delim_list = { \ 'delim_tex' : { \ 'name' : [ \ ['[', ']'], \ ['{', '}'], \ ['\glq', '\grq'], \ ['\glqq', '\grqq'], \ ['\flq', '\frq'], \ ['\flqq', '\frqq'], \ ] \ } \} < *g:vimtex#delim#lists* *g:vimtex#delim#re* Note: This option is parsed on plugin initialization into a new variable, |g:vimtex#delim#lists| where the `re` entries are added and that also contains some combinations such as `tex_all`, `delim_all`, and `all`. Further, the option is also used as a basis for the variable |g:vimtex#delim#re|, which contains full regexes for matching opening and/or closing delimiters of the desired type. Default value: See `s:init_delim_lists()` in `/autoload/vimtex/delim.vim`. *g:vimtex_delim_toggle_mod_list* Defines a list of delimiter modifiers to toggle through using the maps: |(vimtex-delim-toggle-modifier)| |(vimtex-delim-toggle-modifier-reverse)| The list must be a subset of the `mods` entry of |g:vimtex_delim_list|, otherwise the toggle will not work properly. Thus, if one wants to toggle non-standard delimiters, then one must also update the above option. Example 1: to toggle between no modifiers, the `\left/\right` pair, and the `\mleft/\mright` pair, one may use the following options: >vim let g:vimtex_delim_list = {'mods' : {}} let g:vimtex_delim_list.mods.name = [ \ ['\left', '\right'], \ ['\mleft', '\mright'], \ ['\bigl', '\bigr'], \ ['\Bigl', '\Bigr'], \ ['\biggl', '\biggr'], \ ['\Biggl', '\Biggr'], \ ['\big', '\big'], \ ['\Big', '\Big'], \ ['\bigg', '\bigg'], \ ['\Bigg', '\Bigg'], \] let g:vimtex_delim_toggle_mod_list = [ \ ['\left', '\right'], \ ['\mleft', '\mright'], \] < Example 2: to step through no modifiers, and the pairs `\bigl/\bigr`, `\Bigl/\Bigr`, `\biggl/\biggr`, and `\Biggl/\Biggr`, one may use: >vim let g:vimtex_delim_toggle_mod_list = [ \ ['\bigl', '\bigr'], \ ['\Bigl', '\Bigr'], \ ['\biggl', '\biggr'], \ ['\Biggl', '\Biggr'], \] < Default value: `[['\left', '\right']]` *g:vimtex_delim_timeout* *g:vimtex_delim_insert_timeout* Timeout (in milliseconds) when searching for matching delimiters. It is used for the {timeout} argument of |search()|-like function calls. If the option is increased it will make the matching more accurate, at the expense of potential lags. The default value should work well for most people. Default values: 300, 60 (respectively) *g:vimtex_delim_stopline* A tolerance for the number of lines to search for matching delimiters in each direction. It is used in an expression for the {stopline} argument of |search()| function calls. If the option is increased it will make the matching more accurate, at the expense of potential lags. The default value should work well for most people. Default value: 500 *g:vimtex_doc_enabled* Use this option to disable features related to |vimtex-latexdoc|. Default value: 1 *g:vimtex_doc_confirm_single* When enabled (set to 1 or |v:true|), then VimTeX will open the specified documentation only after a confirmation prompt such as: > Open documentation for usepackage: foobar? [y]es/[n]o < Thus, one may disable this option (set to 0 or |v:false|) to avoid the confirmation and open directly. Note that this is only relevant when there is only a single recognized documentation source. Default value: |v:true| *g:vimtex_doc_handlers* With this option, one may specify a list of custom documentation handlers. The following pre-made handlers are available: `'vimtex#doc#handler#texdoc'` Open documentation with local `texdoc`. Fallback Open documentation online through http://texdoc.net/pkg/packagename. To use the local `texdoc`, set: >vim let g:vimtex_doc_handlers = ['vimtex#doc#handlers#texdoc'] < A handler is a function that takes a single |Dict| argument with the following keys: type ~ One of `documentclass`, `usepackage`, `command` or `word`. candidates ~ A list of detected packages (for the types `command` and `usepackage`, this list may be larger than 1. selected ~ The currently selected entry. This is the package name that will ultimately be passed to the lookup function. name ~ If the type is `command`, this is the name of the command. Else it is not defined. Each handler in the list will be tried until a handler provides a return value of 1 or |v:true|. One may thus add handlers that only makes minor modifications of the context and passes it on to the next handler. The context may have multiple candidates and the handlers are applied before any internal selection is made. Thus the `selected` key may be not defined. This allows the handler to perform the selection itself. One may manually call the selection function `vimtex#doc#make_selection` to get a simple selection menu. The following shows a generic example of how to write a custom handler: >vim let g:vimtex_doc_handlers = ['MyHandler'] function! MyHandler(context) call vimtex#doc#make_selection(a:context) if empty(a:context.selected) | return 0 | endif execute '!myhandler' a:context.selected '&' return 1 endfunction < Default value: [] *g:vimtex_echo_verbose_input* For the set of operator mappings that change a surrounding type [0], VimTeX by default prints some information about what you are doing while waiting for user input. For advanced/experienced users, one will not need this info and can get a slightly cleaner UI by disabling this feature (set the option 0). Default value: 1 [0]: This affects the following mappings: |(vimtex-env-change)| (default map: `cse`) |(vimtex-env-change-math)| (default map: `cs$`) |(vimtex-cmd-change)| (default map: `csc`) |(vimtex-delim-change-math)| (default map: `csd`) *g:vimtex_env_change_autofill* If enabled, the current environment value is used as a default input for |(vimtex-env-change)| and |(vimtex-env-change-math)|. Some users may find this useful in order to quickly change from things like `align` to `aligned`. Note: If enabled, one may erase the autofilled content with |c_CTRL-U| (i.e. ``). Default: 0 *g:vimtex_env_toggle_math_map* Specify toggle map for |(vimtex-env-toggle-math)|. You can use this to change the desired toggle sequence. Default value: >vim let g:vimtex_env_toggle_math_map = { \ '$': '\[', \ '\[': 'equation', \ '$$': '\[', \ '\(': '$', \} *g:vimtex_fold_enabled* Use this option to enable folding, which means VimTeX will enable the following options for LaTeX files: >vim setlocal foldmethod=expr setlocal foldexpr=vimtex#fold#level(v:lnum) setlocal foldtext=vimtex#fold#text() < More detailed info can be found in the section |vimtex-folding|. Default value: 0 *g:vimtex_fold_manual* With this option enabled, VimTeX uses |fold-manual| as the main |foldmethod|. It still uses the |foldexpr| function to compute the fold levels, but it only computes the fold levels on demand, see |:VimtexRefreshFolds| and |vimtex-zx|. The reasoning behind this option is that the |fold-expr| method of folding may sometimes be slow, e.g. for long lines and large files. |fold-manual| is very fast. An alternative to this method of speeding up is to use a dedicated plugin for optimizing the fold functionality, see e.g. https://github.com/Konfekt/FastFold. Default value: 0 *g:vimtex_fold_levelmarker* Use custom section symbol for folding. Default value: `'*'` *g:vimtex_fold_types* *g:vimtex_fold_types_defaults* This is a dictionary where each key configures the corresponding fold type. One may disable the fold types by setting the key `enabled` to 0. If a type can be configured with a list of patterns or similar, the patterns assume that one uses very magic regexes (see |\v|). Each entry in |g:vimtex_fold_types| is combined with the corresponding entry of |g:vimtex_fold_types_defaults|. If there are conflicting entries, then |g:vimtex_fold_types| take precedence. This way, it is easy to customize various fold types without touching those that can stay with default configuration. The available fold types (and keys) are listed below, and the default configurations are listed at the bottom. Fold the preamble. Fold sections and parts of documents. Can be configured with the following extra keys: - `parse_levels`: Whether to use detailed parsing to set fold text levels similar to how they are displayed in |vimtex-toc|. Disabled by default, because it uses more resources and may be slow. - `sections`: List of sections that should be folded. - `parts`: List of parts that should be folded. When a LaTeX document is opened, the document is parsed in order to define the highest fold level based on which parts (such as frontmatter, backmatter, and appendix) and section types (parts, chapter, section, etc.) are present. This parsing is done automatically every time the folds are recomputed, if there are any changes to the file. The fold function also recognizes "fake" sections. That is, it parses comments similar to: > % Fakepart title % Fakechapter title % Fakesection title % Fakesubsection title < The fake sections are folded at the same level as the corresponding "real" sections. The fold title is the provided title with the `Fake...` part prepended. Fold `\begin{comments} ... \end{comments}` and disable folding inside the environment. Fold multiline comments. This is disabled by default. Fold on vim-style markers inside comments, that is, pairs of e.g. `{{{` and `}}}` (the default markers). |regex| patterns for the opening and closing markers may be customized with the keys: - `open` - `close` Note: Patterns are only searched inside comments! Fold environments. Can be further configured with a blacklist and whitelist of environments to be folded. Note: The `document` environment will never be folded. This fold type allows to fold the `\begin` command if it contains a long optional argument. Consider the following example: > \begin{axis}[ ---> \begin{axis}[...] width=6cm, height=8cm, ..., ] < Here the `axis` environment must not be otherwise folded through the fold type. `\item` blocks in itemize like environments. The recognized environments are the same as specified by |g:vimtex_indent_lists|. Fold long commands with a single argument. E.g.: > \hypersetup{ ---> \hypersetup{...} option 1, ..., option n } < Fold commands that opens with a single long optional argument that is followed by a short "real" argument. E.g.: > \usepackage[ ---> \usepackage[...]{name} option 1, ..., option n ]{name} < Fold commands that start with a short regular argument and continue with long optional and/or regular arguments. E.g.: > \newcommand{\xx}[3]{ ---> \newcommand{\xx} ... Hello #1, #2, and #3. } < Folding of the `\addplot` series of commands from the `pgfplots` package. E.g.: > \addplot+[] table[] { ---> \addplot+[] table[] {...}; table data }; < As an example, the following configuration will disable folding of the preamble, as well as the `figure` and `table` environments. >vim let g:vimtex_fold_types = { \ 'preamble' : {'enabled' : 0}, \ 'envs' : { \ 'blacklist' : ['figure', 'table'], \ }, \} < Default value: >vim let g:vimtex_fold_types = {} let g:vimtex_fold_types_defaults = { \ 'preamble' : {}, \ 'items' : {}, \ 'comment_pkg' : {}, \ 'comments' : {'enabled' : 0}, \ 'envs' : { \ 'blacklist' : [], \ 'whitelist' : [], \ }, \ 'env_options' : {}, \ 'markers' : {}, \ 'sections' : { \ 'parse_levels' : 0, \ 'sections' : [ \ '%(add)?part', \ '%(chapter|addchap)', \ '%(section|addsec)', \ 'subsection', \ 'subsubsection', \ ], \ 'parts' : [ \ 'appendix', \ 'frontmatter', \ 'mainmatter', \ 'backmatter', \ ], \ }, \ 'cmd_single' : { \ 'cmds' : [ \ 'hypersetup', \ 'tikzset', \ 'pgfplotstableread', \ 'lstset', \ ], \ }, \ 'cmd_single_opt' : { \ 'cmds' : [ \ 'usepackage', \ 'includepdf', \ ], \ }, \ 'cmd_multi' : { \ 'cmds' : [ \ '%(re)?new%(command|environment)', \ 'providecommand', \ 'presetkeys', \ 'Declare%(Multi|Auto)?CiteCommand', \ 'Declare%(Index)?%(Field|List|Name)%(Format|Alias)', \ ], \ }, \ 'cmd_addplot' : { \ 'cmds' : [ \ 'addplot[+3]?', \ ], \ }, \} *g:vimtex_fold_bib_enabled* Use this option to enable/disable folding in `.bib` files. When enabled, VimTeX will set the following options for `.bib` files: >vim setlocal foldmethod=expr setlocal foldexpr=vimtex#fold#bib#level(v:lnum) setlocal foldtext=vimtex#fold#bib#text() < Note: The default value is the same as |g:vimtex_fold_enabled|. Thus, it suffices to enabled folds for tex files to also enable for bib files. But if you want to enable in tex files but keep bib folding disabled, then you must set this option to 0 or |v:false|. Default value: |g:vimtex_fold_enabled| *g:vimtex_fold_bib_max_key_width* This option is used to specify a length to truncate identifiers (e.g. `@article{Key}`) to, in the foldtext for bib files. The default of 0 indicates no truncation, i.e. VimTeX will parse the bib file to determine the longest such identifier and align all foldtext titles such that they come after the identifiers. If you have a handful of cite keys that are exceptionally long, setting this manually may be useful as it makes sure that there is some space for the titles in the foldtext. Default value: 0 *g:vimtex_format_enabled* If enabled, VimTeX uses a custom |formatexpr| that should handle inline comments and environments. That is, if it is enabled, comments at end of lines will not be joined with the |gq| command, and environments like `equation` will not be joined/changed. Default value: 0 *g:vimtex_format_border_begin* *g:vimtex_format_border_end* Regular expressions that define the "borders" of a region that should be formatted. The defaults should be more or less OK for most people, but some people may be interested in adjusting to handle more complex LaTeX code. Default value: See source in `/autoload/vimtex/options.vim` *g:vimtex_grammar_textidote* This option is used to configure the `textidote` grammar and document checker, see |vimtex-grammar-textidote|. It is a dictionary with the following keys jar ~ The path to `textidote.jar`. This key must be defined if you want to use the TeXtidote wrapper! Please note that if one installs `textidote` with a package manager e.g. in some common Linux distributions, the `.jar` file might be missing. If so, it should be possible to download it manually. args ~ Specify arguments to be passed to the TeXtidote grammar checker. Default: >vim let g:vimtex_grammar_textidote = { \ 'jar': '', \ 'args': '', \} *g:vimtex_grammar_vlty* This option is used to configure the `vlty` grammar checker. This checker relies on the Python package `YaLafi` in combination with the proofreading software `LanguageTool` (see |vimtex-grammar-vlty| for more details). The option is a dictionary with the following keys : lt_directory ~ Path to the `LanguageTool` software, if installed manually. lt_command ~ Name of `LanguageTool` executable, if installed via package manager. Note that this has precedence over `lt_directory`! lt_disable ~ lt_enable ~ lt_disablecategories ~ lt_enablecategories ~ Options for `LanguageTool` that control application of rules and rule categories. For more info, see: http://wiki.languagetool.org/command-line-options server ~ Specify whether an HTTP server should be used. This may be faster for short texts. Possible values are: `no` Do not use a server. `my` Use a local `LanguageTool` server. If not yet running, it is started. `lt` Contact the Web server provided by `LanguageTool`. In this case, no local installation is necessary. Please see the following page for conditions and restrictions: https://dev.languagetool.org/public-http-api shell_options ~ Pass additional options to `YaLafi`, e.g., `--equation-punctuation displ`; for more info, see: https://github.com/torik42/YaLafi show_suggestions ~ If set to 1, then `LanguageTool's` replacement suggestions are included in the |quickfix| or |location-list| messages. encoding ~ Encoding of the (La)TeX source file. For default value `auto`, the encoding is taken from |fileencoding| or |encoding|. Default: >vim let g:vimtex_grammar_vlty = { \ 'lt_directory': '~/lib/LanguageTool', \ 'lt_command': '', \ 'lt_disable': 'WHITESPACE_RULE', \ 'lt_enable': '', \ 'lt_disablecategories': '', \ 'lt_enablecategories': '', \ 'server': 'no', \ 'shell_options': '', \ 'show_suggestions': 0, \ 'encoding': 'auto', \} *g:vimtex_imaps_enabled* Use this option to disable/enable the insert mode mappings. Default value: 1 *g:vimtex_imaps_leader* The default leader key for insert mode mappings. Default value: "`" *g:vimtex_imaps_disabled* A list of mappings to disable. That is, any left-hand side that matches a string in this list will not be mapped to its corresponding right-hand side. This may be used to selectively disable one or more from the default list of mappings. Default value: [] *g:vimtex_imaps_list* The list of mappings to generate on start up. The list of activated mappings can be viewed with |:VimtexImapsList|. Default value: See `/autoload/vimtex/options.vim` (it's a long list) *g:vimtex_include_indicators* VimTeX will recognize included files for a lot of different purposes. Most of these come from e.g. `\input{file}` or `\include{file}`. This option allows to add more commands that are used to include files, e.g. custom macros. Note: This option is read during initialization of VimTeX, and so it must be set early. I.e., it can not be set in `after/ftplugin/tex.vim`. Default value: `['input', 'include', 'includeonly']` *g:vimtex_include_search_enabled* VimTeX sets 'includeexpr' to recognize included files. If a file isn't found in the current directory, VimTeX uses `kpsewhich` to search for it in the system TeX distribution. If the 'complete' option includes "i", invoking keyword completion with |i_CTRL-N| will search included files for completion possibilities. In this case, there may be a lot of calls to `kpsewhich` while scanning for included files during the first invocation of keyword completion, and this may introduce a significant delay. Subsequent keyword completions should be faster, as the calls to `kpsewhich` are cached. This option allows to disable searching for included files with `kpsewhich`, and with that prevent the above explained delay. Default value: 1 *g:vimtex_indent_enabled* Use this option to disable/enable VimTeX indentation. Default value: 1 *g:vimtex_indent_bib_enabled* Use this option to disable/enable VimTeX indentation of bibliography files. Default value: 1 *g:vimtex_indent_conditionals* This is a dictionary that defines regexes for indenting conditionals. Set it to an empty dictionary to disable this type of indentation. Default value: >vim let g:vimtex_indent_conditionals = { \ 'open': '\v%(\\newif)@|field|name|numequal|thenelse|toggle)@!', \ 'else': '\\else\>', \ 'close': '\\fi\>', \} *g:vimtex_indent_delims* A dictionary that specifies how to indent delimiters. The dictionary has four keys: open ~ List of regexes for opening delimiters that should add indents. close ~ List of regexes for closing delimiters that should reduce indents. close_indented ~ Set this to 1 if you want the line with the closing delimiter to stay indented. include_modified_math ~ Set this to 0 if you do not want modified math delimiters such as `\left(` and `\right)` to add/reduce indents. Note: VimTeX does not allow indents for parentheses only in math mode or any similar kind of context aware delimiter indents. Note: If one of the keys of the dictionary is not specified, the default value is assumed. Default value: >vim let g:vimtex_indent_delims = { \ 'open' : ['{'], \ 'close' : ['}'], \ 'close_indented' : 0, \ 'include_modified_math' : 1, \} *g:vimtex_indent_ignored_envs* List of environments that should not add/reduce indentation. Note: Each item is interpreted as a regular expression that is combined into very magic regexes like `\v<%(document|...)>`, see |/\v|. Default value: ['document'] *g:vimtex_indent_lists* List of environments that act like lists with `\item` entries. Note: Each item is interpreted as a regular expression that is combined into regexes like `\\begin{\%(itemize|description|...\)`. Default value: [ \ 'itemize', \ 'description', \ 'enumerate', \ 'thebibliography', \] *g:vimtex_indent_on_ampersands* By default, VimTeX will align on `leading` ampersands e.g. in math aligned environments or in tabular environments. If this feature is not wanted it may be disabled through this option. Note: To get a more advanced tabular like alignment feature, you may be interested in something like |vim-easy-align|: https://github.com/junegunn/vim-easy-align Default value: 1 *g:vimtex_indent_tikz_commands* Use this option to disable/enable VimTeX indentation of multi-line commands in TikZ pictures. Default value: 1 *g:vimtex_mappings_enabled* Control whether or not to load the default mappings. Default value: 1 *g:vimtex_mappings_disable* A dictionary that can be used to disable specific mappings. The dictionary keys are the mapping modes, and the values are lists of default mappings that should be disabled. The following example will ensure that the default `tse` and `tsd` mappings are disabled: >vim let g:vimtex_mappings_disable = { \ 'n': ['tse', 'tsd'], \ 'x': ['tsd'], \} < Default value: {} *g:vimtex_mappings_override_existing* Control behaviour on mapping conflicts, in particular whether or not to override pre-existing mappings. By default, VimTeX does not override existing mappings. If this option is enabled, then VimTeX will override existing mappings on conflict. Default value: 0 *g:vimtex_mappings_prefix* The default prefix for `` based mappings. Default value: `'l'` *g:vimtex_matchparen_enabled* Enable highlighting of matching delimiters. Note: This is an improved version of |matchparen|. It should be possible to keep |matchparen| activated, which matches delimiters listed in 'matchpairs'. The VimTeX specific version will also match LaTeX specific delimiters, which is not possible with |matchparen|. Note: If you think this feature is slow, see |vimtex-faq-slow-matchparen|. Default value: 1 *g:vimtex_motion_enabled* This option enables the motion mappings, see |vimtex-motions|. It also enables the highlighting of matching delimiters. Default value: 1 *g:vimtex_lint_chktex_ignore_warnings* A string variable of options to pass for `chktex` to specify to ignore certain warning messages. Default value: `'-n1 -n3 -n8 -n25 -n36'` *g:vimtex_lint_chktex_parameters* A string variable of parameters to pass to `chktex`. VimTeX will look for a configuration file at `$XDG_CONFIG_HOME/chktexrc`, or `$HOME/.config/chktexrc` if `$XDG_CONFIG_HOME` is undefined. If this file exists, it is specified by default with `--localrc=...`. Default value: `'--localrc=PATH/chktexrc'` or `''` (see above) *g:vimtex_log_ignore* A list of regexes to filter info, warning, and error messages. If a logged message matches any of the regexes in this list, the message will not be printed to screen. Note: All messages may still be viewed with |:VimtexLog|. Default: [] *g:vimtex_log_verbose* Whether or not to print messages to screen. Should generally be on, but may be turned off e.g. for debugging or testing purposes. Default: 1 *g:vimtex_quickfix_enabled* Use this option to disable/enable the quickfix integration. Default value: 1 *g:vimtex_quickfix_method* This option sets the quickfix method. The following methods are available: latexlog ~ This is the standard method which parses the normal LaTeX output. pplatex ~ Uses `pplatex` (https://github.com/stefanhepp/pplatex) to parse the LaTeX output file. `pplatex` is a command line utility used to prettify the output of the LaTeX compiler. pulp ~ Uses `pulp` (https://github.com/dmwit/pulp) to parse the LaTeX output file, similar to `pplatex`. Note: `pplatex` and `pulp` require that `-file-line-error` is NOT passed to the LaTeX compiler. |g:vimtex_compiler_latexmk| will be updated automatically if one uses `latexmk` through VimTeX. However, if one uses other compiler methods, either through VimTeX (see |g:vimtex_compiler_method|) or externally, this requirement must be ensured by the user. Default value: `'latexlog'` *g:vimtex_quickfix_blgparser* This option controls the parsing of `blg` log files (created by bibtex or biber) for warnings and errors. The option is a dictionary with the following keys: disable ~ Disable the parsing of `blg` entries. Default value: {} *g:vimtex_quickfix_autojump* This option controls if vim should automatically jump to the first error whenever the |quickfix| window is opened. Note: This option does not go well with continuous compilation and callbacks, since the callbacks will open the quickfix window if there are errors. Thus I recommend to keep it disabled for continuous compilation, and rather enable it if one prefers single shot compilations. Default value: 0 *g:vimtex_quickfix_ignore_filters* This option allows to provide a list of |regular-expression|s for filtering out undesired errors and warnings. This works regardless of which quickfix method is enabled. The following example will ignore any messages that match "Marginpar on page": >vim " Disable custom warnings based on regexp let g:vimtex_quickfix_ignore_filters = [ \ 'Marginpar on page', \] < Default: [] *g:vimtex_quickfix_mode* This option controls the behaviour of the |quickfix| window in case errors and/or warnings are found. The recognized options are: Value Effect ~ 0 The quickfix window is never opened/closed automatically. 1 The quickfix window is opened automatically when there are errors, and it becomes the active window. 2 The quickfix window is opened automatically when there are errors, but it does not become the active window. Note: The quickfix window will only be opened automatically if the compiler is set to `continuous` mode and has `callbacks` enabled, or if `continuous` mode is disabled. Default value: 2 *g:vimtex_quickfix_autoclose_after_keystrokes* If set to value greater than zero, then the quickfix window will close after this number of motions (i.e. |CursorMoved| and |CursorMovedI| events). This is most useful if one sets |g:vimtex_quickfix_mode| to 2, in which case this option allows one to continue editing and removing the distraction of the quickfix window automatically. Note: The count is reset when the quickfix window is entered. Default value: 0 *g:vimtex_quickfix_open_on_warning* Control whether or not to automatically open the |quickfix| window in case there are warning messages and no error messages. Default value: 1 *g:vimtex_subfile_start_local* This option allows to specify that one should start with the local file for subfile'd documents instead of the main project file. See |vimtex-subfiles| for further info. Default value: 0. *g:vimtex_syntax_enabled* Use this option to disable/enable syntax highlighting as provided by VimTeX. Default value: 1. *g:vimtex_syntax_conceal* A dictionary for specifying which core conceal features to activate. This mostly implies concealing particular elements with a replacement unicode character. For more info, see |vimtex-syntax-conceal|. To disable all conceal features in one go, use |g:vimtex_syntax_conceal_disable|. The following keys are available: accents ~ Conceal accented characters, e.g. `\^a` --> `â`. ligatures ~ Conceal ligatures such as `\aa` --> `å` and `''` --> `“`. cites ~ Conceal LaTeX cite commands such as `\citet[...]{ref00}`. The conceal style is specified by |g:vimtex_syntax_conceal_cites|. fancy ~ Some extra fancy replacements, e.g. `\item` --> ○. spacing ~ Conceal spacing commands such as `\quad` and `\hspace{1em}` in both normal mode and math mode. greek ~ Replace TeX greek letter commands into the equivalent unicode greek letter. math_bounds ~ Conceal the TeX math bounds characters: pairs of `$` and `$$`, `\(` ... `\)`, and `\[` ... `\]`. math_delimiters ~ Replace possibly modified math delimiters with a single unicode letter. Modified means delimiters prepended with e.g. `\left` or `\bigl`. As an example, this will perform the replacement `\Biggl\langle ... \Biggr\rangle` --> `〈 ... 〉` math_fracs ~ Replace some simple fractions like `\frac 1 2` --> ½. math_super_sub ~ Replace simple math super and sub operators, e.g. `x^2` --> `x²`. math_symbols ~ Replace various math symbol commands to an equivalent unicode character. This includes quite a lot of replacements, so be warned! sections ~ Conceal `\(sub)*section` commands. The titles are replaced with Markdown style ATX headers, e.g.: `\section{Test}` --> `# Test` `\subsection{Test}` --> `## Test` styles ~ Conceal the LaTeX command "boundaries" for italicized and bolded style commands, i.e. `\emph`, `\textit`, and `\textbf`. This means that one will see something like: `\emph{text here}` --> `text here` Default value: >vim let g:vimtex_syntax_conceal = { \ 'accents': 1, \ 'ligatures': 1, \ 'cites': 1, \ 'fancy': 1, \ 'spacing': 1, \ 'greek': 1, \ 'math_bounds': 1, \ 'math_delimiters': 1, \ 'math_fracs': 1, \ 'math_super_sub': 1, \ 'math_symbols': 1, \ 'sections': 0, \ 'styles': 1, \} *g:vimtex_syntax_conceal_disable* This option allows to disable all conceal features at once. For more fine tuned control, use |g:vimtex_syntax_conceal| and |g:vimtex_syntax_packages|. Default value: 0 *g:vimtex_syntax_conceal_cites* A simple dictionary to control how citation conceal should work. It has three keys: type ~ Specify the type of concealment. There are two options, and the difference is best explained by example: Value LaTeX Concealed ----- ----- --------- `'icon'` `\cite{Knuth1981}` `📖` `'brackets'` `\cite{Knuth1981}` `[Knuth1981]` icon ~ Specify an icon for `icon` conceal. This must be a single (possibly multibyte) character. verbose ~ Specify how much to conceal in bracket mode (`type` set to `'bracket'`). The following table shows how the concealed result depending on the `'verbose'` value for `\cite[Figure 1]{Knuth1981}`: Value Concealed ----- --------- |v:true| `[Figure 1][Knuth1981]` |v:false| `[Knuth1981]` Default value: >vim let g:vimtex_syntax_conceal_cites = { \ 'type': 'brackets', \ 'icon': '📖', \ 'verbose': v:true, \} *g:vimtex_syntax_custom_cmds* A list of "simple" commands for which to apply custom styling. This includes bolded or italicized text arguments, conceals, or similar - see the below keys. Each command is expected to be of the following type: > \cmdname[optional]{argument} < It is important to be aware that these customizations will be applied on top of the existing syntax rules. These may therefore override both the core syntax rules and extensions from syntax packages. Each element in the list must be a dictionary with the following keys: name ~ Default: Undefined (REQUIRED) The command to highlight (`cmdname`). This is also for defining the syntax group names. cmdre ~ Default: Undefined If this is defined, then it is used instead of `name` for matching the `cmdname` part. It is interpreted as a regular expression with "very magic" mode activated (see |/\v|). mathmode ~ Default: |v:false| If true, then the command is a math mode command. conceal ~ Default: |v:false| If true, the `\cmdname` part and delimiters `{` and `}` are concealed. concealchar ~ Default: Undefined Specify a conceal character for the `\cmdname` part. With this, one can easily create simple rules to display e.g. `\R` as `ℝ` (see config example below). opt ~ Default: |v:true| If true, assumes `\cmdname` can be followed by an `[optional]` group. optconceal ~ Default: Same as `conceal` key If true, the option group `[optional]` is concealed. arg ~ Default: |v:true| If true, assumes `\cmdname` can be followed by an `{argument}` group. argstyle ~ Default: Undefined. Can be set to apply styling to the command argument by linking the argument syntax group to one of the `texStyle` highlight groups (see Table 5 in |vimtex-syntax-reference|). The following options are available: * `bold` * `ital` * `under` * `boldital` * `boldunder` * `italunder` * `bolditalunder` Note: Fine grained control is of course also possible. Each defined command gets one or more match groups, e.g. if you create a custom command named `foo`, then it will usually have these groups: `texCmdCFoo`, `texCFooOpt`, `texCFooArg`. One may then customize the highlights as explained in |vimtex-syntax-core|. argspell ~ Default: |v:true| Specify this as |v:false| or 0 to disable spell checking of the command argument. arggreedy ~ Default: |v:false| If |v:true| or 1, the syntax rule will "eat" as many arguments as possible: `\cmdname[opt]{arg1}{arg2}...{argn}` nextgroup ~ Default: Undefined This is a string that, if defined and not empty, specifies a comma-separated list of possible next syntax groups. hlgroup ~ Default: Undefined A string that can be used to indicate the target highlight group of the command (`\cmdname`). A couple of examples may be helpful: The first in the following list shows how to use bolded style on a custom vector macro such as `\vct{v}`. The second example shows how to conceal `\R` with `ℝ`. The third example shows how one may use the `nextgroup` key, and the fourth shows how to define a command whose argument should not be spell checked. >vim let g:vimtex_syntax_custom_cmds = [ \ {'name': 'vct', 'mathmode': 1, 'argstyle': 'bold'}, \ {'name': 'R', 'mathmode': 1, 'concealchar': 'ℝ'}, \ {'name': 'mathnote', 'mathmode': 1, 'nextgroup': 'texMathTextArg'}, \ {'name': 'nospell', 'argspell': 0}, \] < Default value: [] *g:vimtex_syntax_custom_cmds_with_concealed_delims* This option works exactly as |g:vimtex_syntax_custom_cmds|, except it is used specifically to add conceals with custom replacement characters for single- and double-argument commands, e.g. > \cmd1{argument} \cmd2 {argument1} {argument2} < Each element in the list must be a dictionary with the following keys. Most of these keys are documented here: |g:vimtex_syntax_custom_cmds|. Only the unique keys are described in full here. name ~ Default: Undefined (REQUIRED) nargs ~ Default: 1 Specify whether the command has 1 or 2 arguments. cchar_open ~ Default: Undefined Specify single letter replacement for the head (`\cmdname{`). If left undefined, the head is fully concealed. cchar_mid ~ Default: Undefined Note: Only relevant if `nargs` = 2 Specify single letter replacement for the mid (`}{`). If left undefined, the mid is fully concealed. cchar_close ~ Default: Undefined Specify single letter replacement for the tail (`}`). If left undefined, the tail is fully concealed. cmdre ~ Default: Undefined mathmode ~ Default: |v:false| argstyle ~ Default: Undefined. argspell ~ Default: |v:true| hlgroup ~ Default: Undefined An example may be elucidating. Given the following configuration: >vim let g:vimtex_syntax_custom_cmds_with_concealed_delims = [ \ {'name': 'ket', \ 'mathmode': 1, \ 'cchar_open': '|', \ 'cchar_close': '>'}, \ {'name': 'binom', \ 'nargs': 2, \ 'mathmode': 1, \ 'cchar_open': '(', \ 'cchar_mid': '|', \ 'cchar_close': ')'}, \] < We should now see the following effect in a document: >latex $\ket{x}$ and $\binom{n}{k}$ % will now look like this: |x> and (n|k) < Default value: [] *g:vimtex_syntax_custom_envs* A list of environments for which to apply custom styling. This allows to define custom math environments or to specify custom environments for which to load nested syntaxes. The latter is relevant e.g. if you use the `\lstnewenvironment` from the `listings` package. Each environment is expected to look like this: >latex \begin{env_name}[optional argument] … \end{env_name} < It is important to be aware that these customizations will be applied on top of the existing syntax rules. They may therefore override both the core syntax rules and extensions from syntax packages. Each element in the list must be a dictionary with the following keys: name ~ Default: Undefined (REQUIRED) The name of the environment to highlight (`env_name`). The string is used as a regular expression. region ~ Default: `tex{Name}Zone` The syntax group used to match the defined region. Note: If `math` is |v:true|, then the region will always be set to `texMathZoneEnv`. math ~ Default: |v:false| If true, then the environment is a math region. starred ~ Default: |v:false| Whether the corresponding starred environment should also be matched. transparent ~ Default: |v:false| If the matched syntax region should be transparent: |syn-transparent|. opts ~ Default: Undefined A string with additional options that will be passed to the `syntax region` command (see |syn-region|). contains ~ Default: Undefined A comma-separated string of syntax groups that should be contained in within the matched region (see |syn-contains|). nested ~ Default: Undefined This can be either a string or a dictionary: |String|: specify nested syntax to load inside the environment |Dictionary|: specify "predicated" nested syntaxes (more flexible) The dictionary uses the target syntax as the key and the "predicate" as the value. This predicate is a string that must be contained within the optional argument. See below for an example. Notice that one should also be aware of |g:vimtex_syntax_nested|. The following example creates three rules. The first creates the environment `MyMathEnv` that opens a new math environment. The second creates a `python_code` environment that applies nested Python syntax rules in the environment region. The third rule creates a `code` environment that will open nested syntax regions if the optional group contains the specified predicate strings. >vim let g:vimtex_syntax_custom_envs = [ \ { \ 'name': 'MyMathEnv', \ 'math': v:true \ }, \ { \ 'name': 'python_code', \ 'region': 'texPythonCodeZone', \ 'nested': 'python', \ }, \ { \ 'name': 'code', \ 'region': 'texCodeZone', \ 'nested': { \ 'python': 'language=python', \ 'c': 'language=C', \ 'rust': 'language=rust', \ }, \ }, \] < Default value: [] *g:vimtex_syntax_match_unicode* Whether to highlight unicode characters. If enabled, it will match unicode greek letters as `texCmdGreek` and a lot of other unicode symbols as `texMathSymbol`. Default value: |v:true| *g:vimtex_syntax_nested* A dictionary for configuring nested syntaxes. The following keys are available for configuration: aliases ~ Holds a dictionary of aliases, such as mapping `C` to `c`. This is useful e.g. because the Vim syntax files are case sensitive. ignored ~ Holds a dictionary of ignore lists for each language. This is useful to ignore some groups that may conflict in e.g. the `\begin{...}` or `\end{...}` part of the nested syntax regions. Default value: >vim let g:vimtex_syntax_nested = { \ 'aliases' : { \ 'C' : 'c', \ 'csharp' : 'cs', \ }, \ 'ignored' : { \ 'sh' : ['shSpecial'], \ 'bash' : ['shSpecial'], \ 'cs' : [ \ 'csBraces', \ ], \ 'python' : [ \ 'pythonEscape', \ 'pythonBEscape', \ 'pythonBytesEscape', \ ], \ 'java' : [ \ 'javaError', \ ], \ 'haskell' : [ \ 'hsVarSym', \ ], \ } \} *g:vimtex_syntax_nospell_comments* Set to 1 to disable spell checking in comments. Default value: 0 *g:vimtex_syntax_packages* A dictionary for package specific syntax configuration. Each key represent a single package and the values are themselves configuration dictionaries. All packages share the following options: `load` Specify when to load the package syntax addon. 0 = disable this syntax package 1 = enable this syntax package if it is detected (DEFAULT) 2 = always enable this syntax package The following is a list of packages with additional options or packages that deviate from the above specified defaults. Notice that conceal options are affected by |g:vimtex_syntax_conceal_disable|. amsmath ~ `load` is 2 by default `conceal` whether to enable conceal; enabled by default babel ~ `conceal` whether to enable conceal; enabled by default fontawesome5 ~ `conceal` whether to enable conceal; enabled by default. Notice that the only point of this package is to apply conceals to fontawesome commands. Thus, disabling conceal here is equivalent to disabling the package. hyperref ~ `conceal` whether to enable conceal; enabled by default robust_externalize ~ `presets` list of presets and target syntaxes for things like `\begin{CacheMeCode}{bash} ... \end{CacheMeCode}. Default: >vim let g:vimtex_syntax_packages = { \ 'amsmath': {'conceal': 1, 'load': 2}, \ 'babel': {'conceal': 1}, \ 'hyperref': {'conceal': 1}, \ 'fontawesome5': {'conceal': 1}, \ 'robust_externalize': { \ 'presets': [ \ ['bash', 'bash'], \ ['python', 'python'], \ ['gnuplot', 'gnuplot'], \ ['tikz', '@texClusterTikz'], \ ['latex', 'TOP'], \ ], \ }, \} *g:vimtex_texcount_custom_arg* Option that makes it possible to add custom arguments to `texcount` for |:VimtexCountWords| and |:VimtexCountLetters|. Default value: `''` *g:vimtex_text_obj_enabled* Use this option to disable the text object mappings. Default value: 1 *g:vimtex_text_obj_linewise_operators* List of operators that will act linewise on the delimiter text objects (i.e. `ie/ae`, `i$/a$`, and `id/ad`). Note, for inline regions the operators will not act linewise, since that would lead to side effects. Default value: `['d', 'y']` *g:vimtex_text_obj_variant* Select text object variants for command and environment text objects. The choice is either VimTeX or |targets.vim|. Possible configuration options are: 1. `'auto'` (select `'targets'` if |targets.vim| is installed) 2. `'vimtex'` 3. `'targets'` When using `'targets'`, the following additional text object kinds are available: - Prefix `I` and `A` instead of `i` and `a` for excluding inner whitespace or including outer whitespace, respectively. - Modifier `n` and `l` for next or previous (mnemonic: last). For more details, see `doc/targets-textobj-cheatsheet.md`. Default value: `'auto'` *g:vimtex_toggle_fractions* Specify rules for toggling fractions with |(vimtex-cmd-toggle-frac)|, which is mapped to `tsf` by default. Default value: >vim let g:vimtex_toggle_fractions = { \ 'INLINE': 'frac', \ 'frac': 'INLINE', \ 'dfrac': 'INLINE', \} *g:vimtex_toc_enabled* Use this option to disable/enable table of contents (ToC). Default value: 1 *g:vimtex_toc_config* This is a dictionary that can be used to configure the ToC. Each key specifies a configuration option that can be changed. For configuration of specific matchers, see |g:vimtex_toc_config_matchers|. In the following, the possible configuration keys are explained briefly and the default values are indicated. `name` : `Table of contents (VimTeX)` The name of the ToC buffer. `mode` : 1 The ToC display mode, one of: 1: Separate window. 2: Separate window and location list. 3: Location list (and don't open it). 4: Location list (and open it). `fold_enable` : 0 Whether to enable folding in the ToC window. `fold_level_start` : -1 The starting fold level. The value -1 indicates that the start level is the same as the `tocdepth` value. `hide_line_numbers` : 1 If enabled, then line numbers will be hidden in the ToC window by setting |nonumber| and |norelativenumber| locally. `hotkeys_enabled` : 0 Set to 1 to enable individual hotkeys for ToC entries. `hotkeys` : `abcdegijklmnopuvxyz` A string of keys that are used to create individual hotkeys. `hotkeys_leader` : `;` The hotkey leader. Set to empty string to disable the leader. `indent_levels` : 0 Set to 1 to indent the section levels in the ToC window. `layers` : Undefined `layer_status` : Dictionary > { 'content': 1, 'label': 1, 'todo': 1, 'include': 1 } < The initial state of the layers (1 for active, 0 for inactive). The `layers` key may be used as a shorthand: it accepts a list of layers that should be active. `layer_keys` : Dictionary > { 'content': 'C', 'label': 'L', 'todo': 'T', 'include': 'I'} < Specify hotkeys for enabling/disabling the different layers. `resize` : 0 Whether or not to automatically resize vim when index windows are opened. Note: This option makes sense if the index window is vertically split. `refresh_always` : 1 Set to 0 to manually refresh ToC entries. This may be useful for very large projects where generating the ToC entries becomes slow. It may be useful to combine manually refreshing with a |BufWritePost| autocommand, e.g.: >vim augroup VimTeX autocmd! autocmd BufWritePost *.tex call vimtex#toc#refresh() augroup END < Or, if preferred, one may use a mapping such as: >vim nnoremap lf :call vimtex#toc#refresh() < `show_help` : 1 Whether to display help text on top when the ToC is opened. If this is disabled, we only show "Press h to toggle help text.". `show_numbers` : 1 Set whether or not to show section numbers in ToC. `split_pos` : `vert leftabove` Define where index windows should be opened. This is a string that contains either the word "full" to open in the current window, or a position command. Use |:vert| if a vertical split is desired, and one of |:leftabove|, |:rightbelow|, |:topleft|, and |:botright| to specify the desired split position. `split_width` : 30 For vertically split windows: Set width of index window. `tocdepth` : 3 Define the depth of section levels to display. This attempts to mimic the corresponding latex variable `tocdepth`. For more info, see: https://en.wikibooks.org/w/index.php?title=LaTeX/Document_Structure Note: This will also change the width of the number column according to the space needed to show the section numbers. `todo_sorted` : 1 Whether or not to sort the TODOs at the top of the ToC window. *g:vimtex_toc_config_matchers* This is a dictionary that can be used to configure the built-in ToC matchers. See below for a specification of the ToC matcher "objects" and the various keys that can be defined/changed (|toc_matcher_specification|). To configure/alter a built-in matcher, one can do this: >vim let g:vimtex_toc_config_matchers = { \ 'MATCHER1': {OPTIONS}, \ 'MATCHER2': {OPTIONS}, \} < The available options are described in |toc_matcher_specification|. Please note that the built-in matchers should generally just work well for most people. However, this option allows at least two useful things: to disable a built-in matcher and to change the priority of a built-in matcher. The following is a full example that shows how this could be used: >vim let g:vimtex_toc_config_matchers = { \ 'beamer_frame': {'disable': 1}, \ 'todo_fixme': {'priority': -1}, \ 'index': {'title': 'MyFancy Index Title'}, \} < Note: The available built-in matchers are defined in separate files under `/autoload/vimtex/parser/toc/*.vim`. Default value: {} *toc_matcher_specification* A ToC matcher is defined as a |Dictionary| where the possible keys are specified below. In order to write a matcher, one should also be aware of the `context` argument that is passed to the matcher functions, as well as the specification of the `toc entry` return value. However, since this kind of customization is advanced I refer users to the source file for further specification of these objects. In particular, see the function `s:toc.parse(...)` in `/autoload/vimtex/toc.vim`. re ~ Type: |String| Required: `yes` This specifies a regular expression that should match the current line for the desired ToC entry. prefilter_re ~ Type: |String| Required: `maybe` (this or `prefilter_cmds` should be specified) This specifies a regular expression that must match the current line for the desired ToC entry. This is used as a prefilter to make things faster, and it does not need to be a perfect match. The `re` key may often be a complex and therefore slow regular expression. This key should represent a simple and fast regular expression that may match more than the desired entry. prefilter_cmds ~ Type: List of |String| Required: `maybe` (this or `prefilter_re` should be specified) This is similar to `prefilter_re`, except it specifies a list of command names (regular expressions). For instance, it should contain `todo` for a ToC matcher for `\todo` commands. priority ~ Type: |expr-number| (default: 0) Required: `no` Priority is used for sorting the ToC matchers. High priority matchers will be tried first, and only one matcher will match a given line. Note that the built-in matchers have priority values between 0 and 2. in_preamble ~ Type: 0 or 1 (default: 0) Required: `no` If the entry may appear in the preamble. in_content ~ Type: 0 or 1 (default: 1) Required: `no` If the entry may appear in the main content. title ~ Type: |String| Required: `no` If the matcher does not have a `get_entry` key, then it will use a simple, general matcher function to generate the entry. In this case, the `title` key should be specified to give the title of the ToC entry. get_entry ~ Type: |Dictionary-function| Arguments: `context` Returns: `toc entry` Required: `no` This is the general way to define ToC entries. It allows to define the ToC entry based on the context. See `/autoload/vimtex/parser/toc.vim` for examples on how to use this. continue ~ Type: |Dictionary-function| Arguments: `context` Returns: `toc entry` Required: `no` Some entries may be specified over several lines, in which case this key becomes necessary in combination with the `get_entry` key. See the built in `s:matcher_section` matcher for an example on how to use this. name ~ Type: |String| Required: `no` Mostly for making it easier to debug a specific matcher. Without a name, the matcher will be registered with a semi random numbered name like `custom1`. disable ~ Type: |Boolean| (default: |v:false|) Required: `no` If true, then the matcher will be disabled. *g:vimtex_toc_custom_matchers* This option is a list of custom ToC matchers, see |toc_matcher_specification|. As an example, one can use this option to add ToC entries for a custom environment. Say you have defined an environment `mycustomenv`, then instances of this environment could be added to the ToC with the following configuration: >vim let g:vimtex_toc_custom_matchers = [ \ { 'title' : 'My Custom Environment', \ 're' : '\v^\s*\\begin\{mycustomenv\}' } \] < Default value: [] *g:vimtex_toc_todo_labels* Dictionary of keywords that should be recognized in comments for the todo layer. The values represent the labels used in the ToC. Default value: `{'TODO': 'TODO: ', 'FIXME': 'FIXME: '}` *g:vimtex_toc_show_preamble* Whether to include the preamble in the ToC. Default value: 1 *g:vimtex_ui_method* A dictionary that specifies the backend for various input methods. The method names are the keys of the dictionary and the backend choices are the values. The available methods: confirm: Confirm dialogues (e.g. before opening documentation) input: Input dialogues (e.g. for |(vimtex-cmd-change)|) select: Selection dialogues (e.g. to select when there are multiple choices for documentation) The available backends: nvim: Popup menu created with neovim APIs. vim: Currently there is no Vim-specific implementation. Setting the backend to "vim" will currently fallback to "legacy". legacy: Legacy backends that are created by |:echo|ing the menus and using |input()| and similar for getting input. Default: >vim " On neovim let g:vimtex_ui_method = { \ 'confirm': 'nvim', \ 'input': 'nvim', \ 'select': 'nvim', \} " Otherwise let g:vimtex_ui_method = { \ 'confirm': 'legacy', \ 'input': 'legacy', \ 'select': 'legacy', \} *g:vimtex_view_enabled* Use this option to disable/enable the VimTeX viewer interface. Default value: 1 *g:vimtex_view_automatic* If enabled, the viewer should open automatically when compilation has started in `continuous` mode and if `callback` is enabled, or if `continuous` mode is disabled. This should work for the following compilers: * |vimtex-compiler-latexmk| * |vimtex-compiler-latexrun| * |vimtex-compiler-arara| * |vimtex-compiler-tectonic| Default value: 1 *g:vimtex_view_use_temp_files* When enabled, this option specifies to copy the `.pdf` and `.synctex.gz` files after successful compilation. The viewer will use the copies, which helps to avoid issues such that as the pdf becoming unavailable during compilation. The copies are named similar to the original files with a `_` prefix. Note: This option is only relevant for the `latexmk` compiler backend. `latexrun` already ensures that the output file is updated only after the compilation is completed. Default value: |v:false| *g:vimtex_view_forward_search_on_start* If disabled, the first invocation of the viewer will not perform a forward search to the current cursor position. Note: This option is only relevant when |g:vimtex_view_method| is set to either `mupdf`, `zathura`. See also the specific viewer sections for more info: |vimtex-view-mupdf|, |vimtex-view-zathura|. Default value: 1 *g:vimtex_view_reverse_search_edit_cmd* When working in a multi-file project, initiating inverse search (see |vimtex-synctex-inverse-search|) may require opening a file that is not currently open in a window. This option controls the command that is used to open files as a result of an inverse search. Examples: * `edit` open buffer in current window * `tabedit` open buffer in new tab page * `split` split current window to open buffer Default value: `edit` *g:vimtex_view_method* Set the viewer method. By default, a generic viewer is used through the general view method (e.g. `xdg-open` on Linux). Possible values: * `'general'` * `'mupdf'` |vimtex-view-mupdf| * `'skim'` |vimtex-view-skim| * `'zathura'` |vimtex-view-zathura| * `'zathura_simple'` |vimtex-view-zathura-simple| See |vimtex-view-configuration| for more information on various popular viewers and on how to configure them. Default: `general` *g:vimtex_view_general_options* Set options for the specified general viewer, see |vimtex-view-general|. The options are parsed to substitute the following keywords: `@pdf` Path to pdf file `@tex` Path to tex file `@line` Current line number `@col` Current column number Default value: `'@pdf'` *g:vimtex_view_mupdf_options* *g:vimtex_view_zathura_options* Set options for mupdf and Zathura, respectively. See also: * |vimtex-view-mupdf| * |vimtex-view-zathura| * |vimtex-view-zathura-simple| Default value: `''` *g:vimtex_view_general_viewer* Use generic viewer application, see |vimtex-view-general|. Default value: Linux: `xdg-open` macOS: `open` Windows: `SumatraPDF` or `mupdf` if available, else `start ""` *g:vimtex_view_mupdf_send_keys* A string of keys that will be sent to MuPDF just after the PDF file has been opened. Default value: `''` *g:vimtex_view_sioyek_exe* The name or path of the Sioyek executable. The default should usually work, but in some cases it can be useful or necessary to specify the executable directly. E.g., if one downloads a release version, it may be named something like `'Sioyek-x86_64.AppImage'`. Unless the executable location is available in `PATH` one must use an absolute path here. Default value: `'sioyek'` *g:vimtex_view_sioyek_options* Set additional command-line options for Sioyek (|vimtex-view-sioyek|). This can e.g. be used to add the `--reuse-instance` or `--reuse-window` option, which some users prefer. Default value: `''` *g:vimtex_view_skim_activate* Set this option to 1 to make Skim have focus after command |:VimtexView| in addition to being moved to the foreground. Default value: 0 *g:vimtex_view_skim_sync* Set this option to 1 to make Skim perform a forward search after successful compilation. Default value: 0 *g:vimtex_view_skim_reading_bar* Set this option to 1 to highlight current line in PDF after command |:VimtexView| or compiler callback. Default value: 0 *g:vimtex_view_skim_no_select* Set this option to 1 to prevent Skim from selecting the text after command |:VimtexView| or compiler callback. Default value: 0 *g:vimtex_view_texshop_activate* Set this option to 1 to make TeXShop have focus after command |:VimtexView| in addition to being moved to the foreground. Default value: 0 *g:vimtex_view_texshop_sync* Set this option to 1 to make TeXShop perform a forward search after successful compilation. Default value: 0 *g:vimtex_view_zathura_check_libsynctex* Check on startup if Zathura is compiled with libsynctex. This is done by default because Zathura on some systems is compiled without libsynctex support, in which case forward and inverse search will not work. When this is the case, the startup check will provide a notification to the user. If this option is set to 0 or |v:false|, then the check is skipped. Default value: 1 *g:vimtex_callback_progpath* The path to the Vim/neovim executable. This is currently passed to Zathura and Sioyek for use with synctex callbacks; see |vimtex-view-zathura| and |vimtex-view-sioyek|. You usually don't have to touch this variable; VimTeX will |v:progpath| if the option is not defined. But some people may use wrappers and similar to load Vim/neovim, in which case one may want to specify the executable directly. Default value: Undefined *$VIMTEX_OUTPUT_DIRECTORY* This environment variable allows to specify the output directory of generated LaTeX files. If it exists and is a valid path, this path will be used as the output directory. This has two main use cases: 1. It allows to use a custom output directory for different projects. 2. It allows to specify an output directory for projects where one uses compiler backends such as |vimtex-compiler-arara|. This makes it possible to make e.g. the |vimtex-view| feature to work as expected if output directories are used with arara. Note: This will override `out_dir` (and `aux_dir`) of options like |g:vimtex_compiler_latexmk| and |g:vimtex_compiler_latexrun|. ------------------------------------------------------------------------------ COMMANDS *vimtex-commands* *:VimtexContextMenu* *(vimtex-context-menu)* :VimtexContextMenu Show a context menu on the item below cursor. See |vimtex-context-menu| for more information. *:VimtexInfo* *(vimtex-info)* :VimtexInfo Show information that is stored by VimTeX about the current LaTeX project (available mostly for debug purposes). *:VimtexInfo!* *(vimtex-info-full)* :VimtexInfo! Show information that is stored by VimTeX about all open LaTeX projects (available mostly for debug purposes). *:VimtexDocPackage* *(vimtex-doc-package)* :VimtexDocPackage Show documentation for packages. The command takes one optional argument, which is the name of the package to show docs for. If no argument is supplied, it parses the command under the cursor and opens the most relevant documentation. *:VimtexRefreshFolds* :VimtexRefreshFolds Refresh folds, see |vimtex-zx|. *:VimtexTocOpen* *(vimtex-toc-open)* :VimtexTocOpen Open table of contents. *:VimtexTocToggle* *(vimtex-toc-toggle)* :VimtexTocToggle Toggle table of contents. *:VimtexLog* *(vimtex-log)* :VimtexLog Open a scratch buffer to show message log with timestamps and traces from where the messages were raised. To close the log buffer, one may press `q` or ``. *:VimtexCompile* *(vimtex-compile)* :VimtexCompile [opts] If the compiler supports and is set to run in continuous mode, then this command works as a compiler toggle. If not, this command will run a single shot compilation. Arguments to the command will be passed on as options when starting the compiler. This allows the user to start the compiler with different options without changing any configuration. That is, if the user uses the latexmk backend, then adding any option argument is equivalent to adding them to the `'options'` key of |g:vimtex_compiler_latexmk|. Note: Special items in the arguments will be expanded as explained in |expandcmd|. *:VimtexCompileSS* *(vimtex-compile-ss)* :VimtexCompileSS [opts] Start single shot compilation. *:VimtexCompileSelected* *(vimtex-compile-selected)* :VimtexCompileSelected Compile the selected part of the current LaTeX file. When used as a command, it takes a range, e.g.: > :start,end VimtexCompileSelected < When used as a normal mode mapping, the mapping will act as an |operator| on the following motion or text object. Finally, when used as a visual mode mapping, it will act on the selected lines. Note: This always works linewise! The command compiles the selected text by copying it to a temporary file with the same preamble as the current file. It will be compiled similarly to a single shot compile (see |:VimtexCompileSS|. If there are errors, they will be shown in the quickfix list. One may specify a custom template with a template file in which any (single!) line with the exact content `%%% VIMTEX PLACEHOLDER` will be interchanged with the selected lines. This allows to customize the preamble and surrounding content. The template file should be named `vimtex-template.tex` or `-vimtex-template.tex`, where `` implies the head of the current file name with the extension removed. E.g., for a file `foo.tex`, one may specify a custom template `foo-vimtex-template.tex`. This will have a higher priority than `vimtex-template.tex`. *:VimtexCompileOutput* *(vimtex-compile-output)* :VimtexCompileOutput Open file where compiler output is redirected. *:VimtexStop* *(vimtex-stop)* :VimtexStop Stop compilation for the current project. *:VimtexStopAll* *(vimtex-stop-all)* :VimtexStopAll Stop compilation for all open projects in the current vim instance. *:VimtexStatus* *(vimtex-status)* :VimtexStatus Show compilation status for current project. *:VimtexStatus!* *(vimtex-status-all)* :VimtexStatus! Show compilation status for all open projects in the current vim instance. *:VimtexClean* *(vimtex-clean)* :VimtexClean Clean auxiliary files. Note: If compilation is running continuously in the background (which is the default behaviour), then this command will first temporarily stop compilation, then execute the clean command, and finally restart the compilation. *:VimtexClean!* *(vimtex-clean-full)* :VimtexClean! As |:VimtexClean|, but also remove output files. *:VimtexErrors* *(vimtex-errors)* :VimtexErrors Open |quickfix| window if there are errors or warnings. *:VimtexView* *(vimtex-view)* :VimtexView View `pdf` for current project, perform forward search if available. *:VimtexReload* *(vimtex-reload)* :VimtexReload Reload VimTeX scripts. This is primarily useful when developing and debugging VimTeX itself. *:VimtexReloadState* *(vimtex-reload-state)* :VimtexReloadState Reload the state for the current buffer. *:VimtexCountLetters* *:VimtexCountWords* *vimtex#misc#wordcount(opts)* :VimtexCountLetters Shows the number of letters/characters or words in :VimtexCountWords the current project or in the selected region. The count is created with `texcount` through a call on the main project file similar to: > texcount -nosub -sum [-letter] -merge -q -1 FILE < Note: Default arguments may be controlled with |g:vimtex_texcount_custom_arg|. Note: One may access the information through the function `vimtex#misc#wordcount(opts)`, where `opts` is a dictionary with the following keys (defaults indicated): > 'range' : [1, line('$')] 'count_letters' : 0/1 'detailed' : 0 < If `detailed` is 0, then it only returns the total count. This makes it possible to use for e.g. statusline functions. If the `opts` dict is not passed, then the defaults are assumed. *:VimtexCountLetters!* *:VimtexCountWords!* :VimtexCountLetters! Similar to |:VimtexCountLetters|/|:VimtexCountWords|, but :VimtexCountWords! show separate reports for included files. I.e. presents the result of: >bash texcount -nosub -sum [-letter] -inc FILE < *:VimtexImapsList* *(vimtex-imaps-list)* :VimtexImapsList Show the list of insert mode mappings created by the |vimtex-imaps| feature. The mappings are displayed in a scratch buffer. Press `q` or `` to close the buffer. *:VimtexToggleMain* *(vimtex-toggle-main)* :VimtexToggleMain In general, VimTeX detects the main file for the current LaTeX project and uses it for compilation and many other features. However, in some cases it may be useful to instead focus on the current file, for instance in large projects. In such cases, one can use |:VimtexToggleMain| to change which file to use as the "current project". It is easy to toggle back and forth, and both the "main project" and the "local project" can be used simultaneously if desired (e.g. for compilation). Note: To compile the current file when it is part of a larger project, one must of course include a preamble and the `\begin/\end{document}`! It is possible to have a working preamble in every file in a multi-file project with `subfiles`, see |vimtex-subfiles|. See also |g:vimtex_subfile_start_local|. *:VimtexClearCache* :VimtexClearCache {name} Clear cache files that matches `name`. The cache files are located at |g:vimtex_cache_root| and can also be deleted manually. `:VimtexClearCache ALL` clears all cache files. ------------------------------------------------------------------------------ MAP DEFINITIONS *vimtex-mappings* *vimtex-zx* When VimTeX folding is enabled and when the manual mode is turned on (|g:vimtex_fold_manual|), then VimTeX remaps |zx| and |zX| in such that the folds are refreshed appropriately. *(vimtex-env-delete)* *(vimtex-env-delete-math)* *(vimtex-env-change)* *(vimtex-env-change-math)* Delete/Change surrounding environment. When changing, there will be sensible completion candidates, see |cmdline-completion|. See also |g:vimtex_env_change_autofill| and |g:vimtex_echo_verbose_input|. *(vimtex-cmd-delete)* *(vimtex-cmd-delete-math)* *(vimtex-cmd-change)* Delete/Change surrounding command. See also |g:vimtex_echo_verbose_input|. *(vimtex-delim-delete)* *(vimtex-delim-change-math)* Delete/Change surrounding (math) delimiter. See also |g:vimtex_echo_verbose_input|. *(vimtex-cmd-toggle-frac)* Toggle fractions between inline mode (`num/den`) and command mode (`\frac{num}{den}`). Fractions are toggled according to the map specified by |g:vimtex_toggle_fractions|. In visual mode, the selected text is toggled if it matches either a `\frac{}{}` command or a `numerator / denominator` string. In normal mode, we try to detect the surrounding fraction command or inline fraction expression. If successful, the detected fraction is toggled. *(vimtex-cmd-toggle-star)* *(vimtex-env-toggle-star)* Toggle starred command/environment. *(vimtex-env-toggle-math)* Toggle between inline math and displayed math, e.g.: > ts$ \[ $f(x) = 1$ ↔ f(x) = 1 \] < One may change the toggle sequence with |g:vimtex_env_toggle_math_map|. *(vimtex-cmd-toggle-break)* Toggle the line-break macro `\\` at the end of current line. This may be convenient when working with array and math environments. *(vimtex-env-surround-line)* *(vimtex-env-surround-operator)* *(vimtex-env-surround-visual)* Surround the current line, operated text, or visually selected text, with an environment specified during execution. More specifically, this adds `\begin{ENV}` on the line above and `\end{ENV}` on the line below the specified region. The resulting region is filtered to apply proper indentation (see |==|). Note: This only works linewise! Note: There is no default for the operator version. *(vimtex-delim-toggle-modifier)* *(vimtex-delim-toggle-modifier-reverse)* Toggle delimiter modifiers, by default alternating between `(...)` and `\left(...\right)`. The normal mode mapping toggles the closest surrounding delimiter, whereas the visual mode mapping toggles all delimiters that are fully contained in the visual selection. The visual selection is preserved. When |g:vimtex_delim_toggle_mod_list| is set to contain more than one set of modifiers, these mappings iterate through the list instead of just toggling. For example, one may alternate between `(...)`, `\bigl(...\bigr)`, `\Bigl(...\Bigr)`, and so on. These mappings accept a [count], which allows the modifier to be incremented multiple steps at a time. The `-reverse` mapping goes backwards through the modifier list instead of forwards. See also |g:vimtex_delim_toggle_mod_list| and |g:vimtex_delim_list|. *(vimtex-cmd-create)* This mapping works in both insert mode, normal mode and visual mode. It is mapped by default to . See below for the behaviour in the different modes. Insert mode: Convert the preceding text into a LaTeX command. That is, it prepends a backslash and adds an opening brace. It also moves the cursor to the end of the word. If you also want the closing brace (e.g. to emulate delimitMate [0] or any of its like), you can add the following to your `~/.vim/after/ftplugin/tex.vim`: >vim imap (vimtex-cmd-create)} < [0]: https://github.com/Raimondi/delimitMate Normal/Visual mode: Surrounds the word under the cursor/visual selection by the command provided in an input prompt. *(vimtex-delim-close)* Close the current environment or delimiter (insert mode), except the top-level `document` environment. *(vimtex-delim-add-modifiers)* Add `\left` and `\right)` modifiers to all surrounding "unmodified" delimiters in the current math scope. *(vimtex-reverse-search)* Do reverse search for the MuPDF viewer, see |vimtex-view-mupdf|. *(vimtex-ac)* Commands *(vimtex-ic)* *(vimtex-ad)* Delimiters *(vimtex-id)* *(vimtex-ae)* Environments (except top-level `document`) *(vimtex-ie)* *(vimtex-a$)* Math environments *(vimtex-i$)* *(vimtex-aP)* Sections *(vimtex-iP)* *(vimtex-am)* Items *(vimtex-im)* These are all text object mappings for the indicated types of objects , see |vimtex-text-objects| for more info. *(vimtex-%)* Find matching pair. *(vimtex-]])* go to [count] next end of a section. |exclusive| motion. *(vimtex-][)* go to [count] next beginning of a section. |exclusive| motion. *(vimtex-[])* go to [count] previous end of a section. |exclusive| motion. *(vimtex-[[)* go to [count] previous beginning of a section. |exclusive| motion. *(vimtex-]m)* go to [count] next start of an environment `\begin`. |exclusive| motion. *(vimtex-]M)* go to [count] next end of an environment `\end`. |exclusive| motion. *(vimtex-[m)* go to [count] previous start of an environment `\begin`. |exclusive| motion. *(vimtex-[M)* go to [count] previous end of an environment `\end`. |exclusive| motion. *(vimtex-]n)* go to [count] next start of a math zone. |exclusive| motion. *(vimtex-]N)* go to [count] next end of a math zone. |exclusive| motion. *(vimtex-[n)* go to [count] previous start of a math zone. |exclusive| motion. *(vimtex-[N)* go to [count] previous end of a math zone. |exclusive| motion. *(vimtex-]r)* go to [count] next start of a frame environment. |exclusive| motion. *(vimtex-]R)* go to [count] next end of a frame environment. |exclusive| motion. *(vimtex-[r)* go to [count] previous start of a frame environment. |exclusive| motion. *(vimtex-[R)* go to [count] previous end of a frame environment. |exclusive| motion. *(vimtex-]/)* go to [count] next start of a LaTeX comment "%". |exclusive| motion. *(vimtex-]star)* go to [count] next end of a LaTeX comment "%". |exclusive| motion. *(vimtex-[/)* go to [count] previous start of a LaTeX comment "%". |exclusive| motion. *(vimtex-[star)* go to [count] previous end of a LaTeX comment "%". |exclusive| motion. ------------------------------------------------------------------------------ INSERT MODE MAPPINGS *vimtex-imaps* Some LaTeX commands are very common, and so it is both natural and convenient to have insert mode mappings/abbreviations for them. VimTeX therefore provides a list of such mappings that are enabled by default, see |g:vimtex_imaps_list|. The mappings utilize a map leader defined by |g:vimtex_imaps_leader|. The default list of maps are all math mode mappings, but one may also add mappings that are available and useful outside of math mode. To see the list of mappings that are created, one can use the command |:VimtexImapsList|, which is by default mapped to `lm`. It is of course possible to customize the list of mappings. First, one may specifically disable the entire imaps feature with |g:vimtex_imaps_enabled| or specific default mappings through |g:vimtex_imaps_disabled|. Second, one may specify |g:vimtex_imaps_list|, which will overwrite the default list. Finally, one may add new maps through calls to the function |vimtex#imaps#add_map|. The following are some examples of how to customize the mappings: >vim " Disable \alpha and \beta mappings let g:vimtex_imaps_disabled = ['a', 'b'] " Add custom mapping through vimtex#imaps#add_map call vimtex#imaps#add_map({ \ 'lhs' : 'test', \ 'rhs' : '\tested', \ 'wrapper' : 'vimtex#imaps#wrap_trivial' \}) " Add custom mapping: #rX -> \mathrm{X} call vimtex#imaps#add_map({ \ 'lhs' : 'r', \ 'rhs' : 'vimtex#imaps#style_math("mathrm")', \ 'expr' : 1, \ 'leader' : '#', \ 'wrapper' : 'vimtex#imaps#wrap_math' \}) < *vimtex#imaps#add_map* This function is used to add new insert mode mappings. It takes a single dictionary argument: >vim let add_map_arg = { \ 'lhs' : lhs, \ 'rhs' : rhs, \ 'expr' : bool, \ 'leader' : leader_key, \ 'wrapper' : function_name, \ 'context' : value, \ } Explanation of the keys: lhs ~ Mandatory argument. The left-hand side part of the map. rhs ~ Mandatory argument. The right-hand side part of the map. There is one utility function that can be useful: *vimtex#imaps#style_math* Wraps the RHS inside a specified command, e.g. `\myarg{RHS}`, if the cursor is inside math mode. expr ~ Either 0/|v:false| or 1/|v:true| (default: 0). If true, then the right-hand side is evaluated before it is passed to the wrapper. This is necessary e.g. for use with |vimtex#imaps#style_math|. leader ~ Custom leader key. If the key is not present, then |g:vimtex_imaps_leader| is used as leader key. wrapper ~ The name of a wrapper function that is used to generate the `rhs`. Two functions are available from VimTeX: *vimtex#imaps#wrap_trivial* Trivial wrapper: Simply returns `rhs`. *vimtex#imaps#wrap_math* Only define `rhs` if inside a math environment. This is the default wrapper function and will be used if no other wrapper is supplied. *vimtex#imaps#wrap_environment* Only define `rhs` if inside a specified environment. The wrapper works by utilizing the `context` key, which is a list that contains strings and/or dictionaries: i. If the entry is a string, then the `lhs` is mapped to `rhs` inside the specified environment. ii. If the entry is a dictionary, then we assume it has two entries, `envs` and `rhs`, where `envs` is a list of environment names. If inside any environment in this list, then we expand to the corresponding `rhs`. This allows one to create a mapping that expands to different `rhs`s in different environments. Of course, one may use custom wrapper functions. To write a custom wrapper function, please see the source for examples on how the VimTeX wrappers are written. context ~ A value that can be used by the chosen wrapper function. *vimtex-neosnippet* *vimtex-UltiSnips* Note: that this feature is not the same as the snippet feature of |UltiSnips| or |neosnippet|. The imaps feature of VimTeX previously supported `automatic` snippets, but these have been removed after careful considerations and input from VimTeX users, please see VimTeX issue #295: https://github.com/lervag/vimtex/issues/295#issuecomment-164262446 It has been decided that the best approach is to only provide basic mappings, and to let users manually create automatic snippets through the anonymous snippet functions in |UltiSnips| and |neosnippet|, please see |UltiSnips#Anon| and |neosnippet#anonymous|, respectively (these will work if the respective plugins are installed). Here are a couple of examples that show how to create such mappings: >vim " Using neosnippet#anonymous inoremap __ neosnippet#anonymous('_${1}${0}') inoremap ^^ neosnippet#anonymous('^${1}${0}') " Using UltiSnips#Anon inoremap __ __=UltiSnips#Anon('_{$1}$0', '__', '', 'i') inoremap ^^ ^^=UltiSnips#Anon('^{$1}$0', '^^', '', 'i') A drawback with the anonymous UltiSnips snippets is that they do not nest. That is, if you did `__` twice in a row, only the second one could be escaped. In recent versions of |UltiSnips|, one may set normal snippets to trigger automatically, see |UltiSnips-autotrigger|. This allows nesting, and is therefore a better approach than using the anonymous snippet function. ------------------------------------------------------------------------------ EVENTS *vimtex-events* VimTeX defines some events using the |User| autocmd that may be used for further customization. *VimtexEventQuit* This event is triggered when the last buffer for a particular LaTeX project is wiped (for example, using `:bwipeout`) and when Vim is quit. The event may be used, for instance, to cleanup up auxiliary build files or close open viewers (see Examples below). With Vim defaults, this event is not triggered when using `:quit` or `:bdelete` since these commands merely hide the buffer. In multi-file projects, the event may be triggered multiple times. The `b:vimtex` variable contains context data for the quitting file or project. For example, `b:vimtex.tex` identifies the tex file being wiped, or the main tex file of a multi-file project. Note: Commands such as |:VimtexClean| does not always work as expected with this event. This is because, when quitting vim, the current buffer does not necessarily have filetype "tex". *VimtexEventInitPre* *VimtexEventInitPost* These events are triggered at the start/end of VimTeX initialization. The post event may e.g. be used to automatically start compiling a document. *VimtexEventCompileStarted* This event is triggered after compilation is started. *VimtexEventCompileStopped* This event is triggered after compilation is stopped. *VimtexEventCompiling* This event is triggered when the compiler backend triggers a new compilation. This is only supported by |vimtex-compiler-latexmk|. *VimtexEventCompileSuccess* *VimtexEventCompileFailed* These events are triggered after successful/failed compilation and allows users to add custom callback functionality. *VimtexEventTocCreated* This event is triggered after a ToC window is created. *VimtexEventTocActivated* This event is triggered when a ToC entry has been activated. This allows to add custom behaviour after opening an entry, e.g. positioning the buffer window with the |zt| or |zz| mappings. *VimtexEventView* This event is triggered after the viewer has opened/forward search has been performed by the command |:VimtexView| or the related mapping. *VimtexEventViewReverse* This event is triggered at the end of the |vimtex#view#inverse_search| function, which can be used as the callback function for reverse goto from a PDF viewer. Examples (Vimscript) - see below for a Lua example: >vim " Compile on initialization, cleanup on quit augroup vimtex_event_1 au! au User VimtexEventQuit VimtexClean au User VimtexEventInitPost VimtexCompile augroup END " Close viewers when VimTeX buffers are closed function! CloseViewers() if executable('xdotool') \ && exists('b:vimtex.viewer.xwin_id') \ && b:vimtex.viewer.xwin_id > 0 call system('xdotool windowclose '. b:vimtex.viewer.xwin_id) endif endfunction augroup vimtex_event_2 au! au User VimtexEventQuit call CloseViewers() augroup END " Add custom mappings in ToC buffer function! TocMappings() " You probably don't want to do this, though... nnoremap q :quitall! endfunction augroup vimtex_event_3 au! au User VimtexEventTocCreated call TocMappings() augroup END " Specify window position when opening ToC entries augroup vimtex_event_4 au! au User VimtexEventTocActivated normal! zt augroup END " Specify extra behaviour after reverse goto augroup vimtex_event_5 au! au User VimtexEventViewReverse normal! zMzvzz augroup END " Focus the terminal after inverse search augroup vimtex_event_6 autocmd! autocmd User VimtexEventViewReverse call b:vimtex.viewer.xdo_focus_vim() augroup END Examples - Lua: >lua local au_group = vim.api.nvim_create_augroup("vimtex_events", {}), -- Cleanup on quit vim.api.nvim_create_autocmd("User", { pattern = "VimtexEventQuit", group = au_group, command = "VimtexClean" }) -- Focus the terminal after inverse search vim.api.nvim_create_autocmd('User', { pattern = 'VimtexEventViewReverse', group = au_group, command = "call b:vimtex.viewer.xdo_focus_vim()" }) ------------------------------------------------------------------------------ TEXT OBJECTS *vimtex-text-objects* Text objects (and motions) are a fundamental feature in Vim. Operations can be combined with motions or text objects in endless ways and can be repeated with the dot operator (|repeat.txt|). If you are reading this and do not know about these things, then it is strongly advised to read the help section about |text-objects| and the famous Stack Overflow post "Your problem with Vim is that you don't grok vi": http://stackoverflow.com/questions/1218390/what-is-your-most-productive-shortcut-with-vim/1220118#1220118 VimTeX defines LaTeX specific text objects (and motions). These are all mappings, and as such, they are also described in the sections |vimtex-mappings| and |vimtex-default-mappings|. The usual convention for text object mappings is to prepend "a" to select "a"n object, including the whitespace/delimiters/etc, and to prepend "i" to select the corresponding "inner" object. This is the case for VimTeX text objects, e.g. by default, `vie` will visually select the inner part of an environment, whereas `vae` will select the entire environment including the boundaries. VimTeX supports the well known |targets.vim| as a "backend" for the command and environment text objects (`ie`/`ae` and `ic`/`ac`). This should work automatically, see |g:vimtex_text_obj_variant| for more info. Some examples of how to use the text objects can be useful. The following is a simple table that shows the original text on the left, the keys that are typed in the middle, and the result on the right. The bar "|" indicates the cursor position before the operation. > BEFORE KEYS AFTER \comm|and{arg} dic \command{} \command{a|rg} gUac \COMMAND{ARG} \lef|t( asd \right) cid \left(| \right) \begin{x} die \begin{x} hello world| \end{x} \end{x} $math | here$ da$ \begin{itemize} \begin{itemize} \item hello moon| cim \item | \end{itemize} \end{itemize} \begin{itemize} \begin{itemize} \item hello moon| dam \end{itemize} \end{itemize} Note: The "greediness" of the command text objects (`ic` and `ac`) can be controlled with |g:vimtex_parser_cmd_separator_check|. Note: Some of the text objects rely on syntax highlighting (|vimtex-syntax|) to work. That is, some text objects check the syntax groups to determine the proper regions. Examples include the math text objects (e.g. |(vimtex-a$)| and |(vimtex-i$)|). Associated settings: * |g:vimtex_text_obj_enabled| * |g:vimtex_text_obj_linewise_operators| * |g:vimtex_text_obj_variant| ============================================================================== COMPLETION *vimtex-completion* If |g:vimtex_complete_enabled| is 1 (default), then VimTeX sets the 'omnifunc' to provide omni completion, see |compl-omni|. Omni completion is then accessible with |i_CTRL-X_CTRL-O|. If desired, one may set |g:vimtex_complete_close_braces|, which makes the completion include closing braces. The omni completion completes citations, labels, glossary entries and filenames. The following sections document the various kinds of completions provided by VimTeX's completion function. A lot of people expect VimTeX and Vim/neovim to provide `automatic` completion, aka `autocomplete`. However, autocompletion is not a built-in feature of Vim/neovim. The last section of this chapter presents some alternatives to plugins that provide an autocomplete engine and how to configure it with VimTeX, see |vimtex-complete-auto|. Associated settings: * |g:vimtex_complete_bib| * |g:vimtex_complete_close_braces| * |g:vimtex_complete_enabled| * |g:vimtex_complete_ignore_case| * |g:vimtex_complete_ref| * |g:vimtex_complete_smart_case| ------------------------------------------------------------------------------ COMPLETE CITATIONS *vimtex-complete-cites* Citation completion is triggered by `'\cite{'` commands. The completion parses included bibliography files (`*.bib`) and `thebibliography` environments to gather the completion candidates. By default, cite completion is "smart" in that it allows to complete on author names, title, and similar by matching against a match string defined by |g:vimtex_complete_bib.match_str_fmt|. If one prefers, one may set the `simple` key of |g:vimtex_complete_bib| to only allow completion on the bibkeys directly. This should typically work better with autocomplete plugins. As an example of the smart completion, assume that a bibliography file is included with the following entry: >bibtex @book{knuth1981, author = "Donald E. Knuth", title = "Seminumerical Algorithms", publisher = "Addison-Wesley", year = "1981" } Then, with the default configuration, the bibliography key `knuth1981` will be completed with e.g.: > \cite{Knuth 1981 \cite{algo \cite{Don.*Knuth As is shown in the last example, the search string (e.g. `Don.*Knuth`) is applied as a regular expression. ------------------------------------------------------------------------------ COMPLETE LABELS *vimtex-complete-labels* Label completion is triggered by `\ref{` commands. The completion parses every relevant aux file to gather the completion candidates. This is important, because it means that the completion only works when the LaTeX document has been compiled. As an example: > \ref{sec: offers a list of all matching labels with a menu that contains the associated value and page number. The completion base is matched as a regex in the following order: > \ref{ < 1. The menu, which contains the reference value and page number. 2. The actual labels. 3. The menu and label, separated by whitespace. An example: > \ref{eq 2 < This matches "eq" in the label and "2" in the menu. Finally, it should also be mentioned that for `\eqref`, the candidates will automatically be filtered to only show equation references. ------------------------------------------------------------------------------ COMPLETE COMMANDS AND ENVIRONMENTS *vimtex-complete-commands* *vimtex-complete-environments* Command completion is available after `\` and should provide completion candidates for relevant LaTeX commands. The document's preamble is analysed, and commands will be completed for the loaded packages as well as those defined within the preamble using `\newcommand`, `\let` and `\def`. Environment completion is also available after `\begin{` or `\end{`. As with commands, the suggested environment names come from the loaded packages and `\newenvironment` definitions in the preamble. A lot of packages are supported, see the path `/autoload/vimtex/complete` for a relevant file listing. ------------------------------------------------------------------------------ COMPLETE FILE NAMES *vimtex-complete-filenames* File name completion is available for the following macros: `\includegraphics{` Completes image file names. `\input{` `\include{` `\includeonly{` Complete `.tex` files. `\includepdf{` Complete `.pdf` files. This macro is provided by the `pdfpages` package. `\includestandalone{` Complete `.tex` files. This macro is provided by the `standalone` package. ------------------------------------------------------------------------------ COMPLETE INCLUDE GLOSSARY ENTRIES *vimtex-complete-glossary* Glossary entry completion from the `glossaries` package are triggered by the commands `\gls{`, `\glspl{` and their variations. ------------------------------------------------------------------------------ COMPLETE PACKAGE FILES *vimtex-complete-packages* *vimtex-complete-classes* *vimtex-complete-bibstyle* Package completion is available for the `\usepackage`, `\RequirePackage`, and `\PassOptionsToPackage` commands. Similarly, documentclass completion is available for `\documentclass` and `\PassOptionsToClass`, and bibliography style completion is available for `\bibliographystyle`. These completion types all rely on the contents of `ls-R` files that are found with: > kpsewhich --all ls-R Packages and documentclasses installed at `TEXMFHOME` will also be searched. The default value can be found with: > kpsewhich --var-value TEXMFHOME Note: If you want to change the default value of `TEXMFHOME` in your shell startup file and use `gvim` started from the desktop environment, please read |vimtex-faq-texmfhome|. ------------------------------------------------------------------------------ AUTOCOMPLETE *vimtex-complete-auto* Vim does not provide automatic completion by itself, but there exist at least several good plugins that provide this: |coc-nvim|, |deoplete|, |neocomplete|, |ncm2|, |nvim-completion-manager|, |youcompleteme|, and |nvim-compe|. Moreover, there is |VimCompletesMe| that overrides to trigger different built-in completions, such as the omni-completion by VimTeX, depending on the context. See below for descriptions on how to setup these with VimTeX. coc.nvim ~ *vimtex-complete-coc.nvim* |coc-nvim| is an intellisense engine for Vim8 & Neovim. It's a completion framework and language server client which supports extension features of Visual Studio Code. The project is here: https://github.com/neoclide/coc.nvim. |coc-nvim| can be installed using vim-plug: >vim Plug 'neoclide/coc.nvim' However, it does require some more steps, and users are recommended to read the installation instructions in the `coc.nvim` wiki: https://github.com/neoclide/coc.nvim/wiki/Install-coc.nvim To configure for VimTeX, one should use the extension plugin |coc-vimtex|, which may be found here: https://github.com/neoclide/coc-vimtex. To use it, first make sure you have |coc-nvim| installed, then just run: >vim :CocInstall coc-vimtex The `coc-vimtex` extension has a few options that can be configured in the `coc-settings.json` file. See the documentation for |coc-nvim| to learn how to apply the configurations. The following is a list of the options with a short description as it is specified on the project web page: > coc.source.vimtex.disableSyntaxes disabled syntax names coc.source.vimtex.enable set to false to disable this source coc.source.vimtex.priority priority of source, default 99 coc.source.vimtex.shortcut shortcut used in menu of completion item Note: The README of `coc.nvim` suggests using `noremap K` to show documentation. `K` is also used by VimTeX as one of the default maps (see |vimtex-default-mappings|) for the same purpose. To enable VimTeX's mapping for `.tex` files (since `coc.nvim` does not have a doc source), do one of the following: * Manually remap for `.tex` files: Put the following in your `$HOME/.vim/after/ftplugin/tex.vim:` >vim map K (vimtex-doc-package) * Use a custom function in your |vimrc| file, something like this: >vim nnoremap K :call show_documentation() function! s:show_documentation() if index(['vim', 'help'], &filetype) >= 0 execute 'help ' . expand('') elseif &filetype ==# 'tex' VimtexDocPackage else call CocAction('doHover') endif endfunction < deoplete ~ *vimtex-complete-deoplete* |deoplete| is a modern remake of |neocomplete|, and was originally written specifically for Neovim, see here: https://github.com/Shougo/deoplete.nvim. It is a highly customizable and flexible completion manager. To configure for VimTeX, one may use: >vim " This is new style call deoplete#custom#var('omni', 'input_patterns', { \ 'tex': g:vimtex#re#deoplete \}) " This is old style (deprecated) if !exists('g:deoplete#omni#input_patterns') let g:deoplete#omni#input_patterns = {} endif let g:deoplete#omni#input_patterns.tex = g:vimtex#re#deoplete neocomplete ~ *vimtex-complete-neocomplete* |neocomplete| is also a flexible automatic completion engine for vim, although active development has been stopped. Users are recommended to change to |deoplete|, see also |vimtex-complete-deoplete|. The plugin is available here: https://github.com/Shougo/neocomplete.vim. The following options may be used to enable automatic completion for LaTeX documents with |neocomplete| and VimTeX's omni completion function: >vim if !exists('g:neocomplete#sources#omni#input_patterns') let g:neocomplete#sources#omni#input_patterns = {} endif let g:neocomplete#sources#omni#input_patterns.tex = \ g:vimtex#re#neocomplete ncm2 ~ *vimtex-complete-ncm2* |ncm2| is a modern remake and replacement of |nvim-completion-manager| and is supposed to be a "Slim, Fast and Hackable Completion Framework for Neovim": https://github.com/ncm2/ncm2 The following simple configuration should work well with VimTeX: >vim " include the following plugins (here using junnegun/vim-plug) Plug 'roxma/nvim-yarp' Plug 'ncm2/ncm2' set completeopt=noinsert,menuone,noselect augroup my_cm_setup autocmd! autocmd BufEnter * call ncm2#enable_for_buffer() autocmd Filetype tex call ncm2#register_source({ \ 'name': 'vimtex', \ 'priority': 8, \ 'scope': ['tex'], \ 'mark': 'tex', \ 'word_pattern': '\w+', \ 'complete_pattern': g:vimtex#re#ncm2, \ 'on_complete': ['ncm2#on_complete#omni', 'vimtex#complete#omnifunc'], \ }) augroup END < For more lenient, omni-complete-like, filtering of completion candidates, use the following setup (in your `init.vim` or a personal |ftplugin|) instead: >vim augroup my_cm_setup autocmd! autocmd BufEnter * call ncm2#enable_for_buffer() autocmd Filetype tex call ncm2#register_source({ \ 'name' : 'vimtex-cmds', \ 'priority': 8, \ 'complete_length': -1, \ 'scope': ['tex'], \ 'matcher': {'name': 'prefix', 'key': 'word'}, \ 'word_pattern': '\w+', \ 'complete_pattern': g:vimtex#re#ncm2#cmds, \ 'on_complete': ['ncm2#on_complete#omni', 'vimtex#complete#omnifunc'], \ }) autocmd Filetype tex call ncm2#register_source({ \ 'name' : 'vimtex-labels', \ 'priority': 8, \ 'complete_length': -1, \ 'scope': ['tex'], \ 'matcher': {'name': 'combine', \ 'matchers': [ \ {'name': 'substr', 'key': 'word'}, \ {'name': 'substr', 'key': 'menu'}, \ ]}, \ 'word_pattern': '\w+', \ 'complete_pattern': g:vimtex#re#ncm2#labels, \ 'on_complete': ['ncm2#on_complete#omni', 'vimtex#complete#omnifunc'], \ }) autocmd Filetype tex call ncm2#register_source({ \ 'name' : 'vimtex-files', \ 'priority': 8, \ 'complete_length': -1, \ 'scope': ['tex'], \ 'matcher': {'name': 'combine', \ 'matchers': [ \ {'name': 'abbrfuzzy', 'key': 'word'}, \ {'name': 'abbrfuzzy', 'key': 'abbr'}, \ ]}, \ 'word_pattern': '\w+', \ 'complete_pattern': g:vimtex#re#ncm2#files, \ 'on_complete': ['ncm2#on_complete#omni', 'vimtex#complete#omnifunc'], \ }) autocmd Filetype tex call ncm2#register_source({ \ 'name' : 'bibtex', \ 'priority': 8, \ 'complete_length': -1, \ 'scope': ['tex'], \ 'matcher': {'name': 'combine', \ 'matchers': [ \ {'name': 'prefix', 'key': 'word'}, \ {'name': 'abbrfuzzy', 'key': 'abbr'}, \ {'name': 'abbrfuzzy', 'key': 'menu'}, \ ]}, \ 'word_pattern': '\w+', \ 'complete_pattern': g:vimtex#re#ncm2#bibtex, \ 'on_complete': ['ncm2#on_complete#omni', 'vimtex#complete#omnifunc'], \ }) augroup END < nvim-completion-manager ~ *vimtex-complete-ncm* Note: |nvim-completion-manager| has been replaced by |ncm2|, and users are recommended to change. See |vimtex-complete-ncm2| for hints on how to setup |ncm2| for VimTeX. |nvim-completion-manager| is a fast, extensible, async completion framework for neovim (and Vim version 8.0 and above). The project is available here: https://github.com/roxma/nvim-completion-manager To configure for VimTeX, one can use the following code: >vim augroup my_cm_setup autocmd! autocmd User CmSetup call cm#register_source({ \ 'name': 'vimtex', \ 'priority': 8, \ 'scoping': 1, \ 'scopes': ['tex'], \ 'abbreviation': 'tex', \ 'cm_refresh_patterns': g:vimtex#re#ncm, \ 'cm_refresh': {'omnifunc': 'vimtex#complete#omnifunc'}, \ }) augroup END YouCompleteMe ~ *vimtex-complete-youcompleteme* |youcompleteme| is probably the most popular code-completion engine for Vim. The github repository is here: https://github.com/ycm-core/YouCompleteMe. It is described as: > YouCompleteMe is a fast, as-you-type, fuzzy-search code completion engine > for Vim. It has several completion engines: an identifier-based engine that > works with every programming language, a semantic, Clang [3]-based engine > that provides native semantic code completion for the C-family languages, > a Jedi [4]-based completion engine for Python, an OmniSharp [5]-based > completion engine for C# and an omnifunc-based completer that uses data from > Vim's omnicomplete system to provide semantic completions for many other > languages (Ruby, PHP etc.). To enable automatic completion with |youcompleteme|, use the following options: >vim if !exists('g:ycm_semantic_triggers') let g:ycm_semantic_triggers = {} endif au VimEnter * let g:ycm_semantic_triggers.tex=g:vimtex#re#youcompleteme VimCompletesMe ~ *vimtex-complete-vcm* A plugin that maps to trigger the built-in completion that is most suitable to the current context. The plugin is available here: https://git.sr.ht/~ackyshake/VimCompletesMe.vim The following options may be used to enable completion with the trigger for LaTeX documents with |VimCompletesMe| and VimTeX's omni completion function: >vim augroup VimCompletesMeTex autocmd! autocmd FileType tex \ let b:vcm_omni_pattern = g:vimtex#re#neocomplete augroup END nvim-cmp ~ *vimtex-complete-nvim-cmp* |nvim-cmp| [0] is the successor of |nvim-compe|. It provides completion for a lot of different sources. VimTeX support is provided either by using the dedicated `cmp-vimtex` extension [1] or through the general omni-completion source, `cmp-omni` [2]. Both approaches are explained briefly below in the form of a Lua snippet for configuration. It is assumed that the reader already knows how to install and configure plugins, though! [0]: https://github.com/hrsh7th/nvim-cmp [1]: https://github.com/micangl/cmp-vimtex [2]: https://github.com/hrsh7th/cmp-omni nvim-cmp with cmp-vimtex ~ `cmp-vimtex` is a dedicated `nvim-cmp` extension that gives some extra benefits compared to the more general `cmp-omni`: * Allows fuzzy matching against all info provided by Vimtex (including bibliographic details, useful for citations). * Parses and display all details contained in bibtex files for cite completions. * Trims long strings in the completion menu (to add space for the documentation window). * Triggers the completion menu automatically after typing `\cite{`. * Allows more granular configuration of the menus, and more. To use `cmp-vimtex`, you should add something like the following to your configuration. For more info, check the README of the github repo ([1] above). >lua local cmp = require('cmp') cmp.setup { -- global configuration goes here sources = { { name = 'buffer' }, -- other sources (GLOBAL) }, } cmp.setup.filetype("tex", { sources = { { name = 'vimtex' }, { name = 'buffer' }, -- other sources }, } nvim-cmp with cmp-omni ~ >lua local cmp = require('cmp') cmp.setup { -- global configuration goes here sources = { { name = 'buffer' }, -- other sources (GLOBAL) }, } cmp.setup.filetype("tex", { formatting = { -- nvim-cmp overrides the standard completion-menu formatting. We use -- a custom format function to preserve the format as provided by -- VimTeX's omni completion function: format = function(entry, vim_item) vim_item.menu = ({ omni = (vim.inspect(vim_item.menu):gsub('%"', "")), buffer = "[Buffer]", -- formatting for other sources })[entry.source.name] return vim_item end, }, sources = { { name = "omni", trigger_characters = { "{", "\\" } }, { name = 'buffer' }, -- other sources }, } nvim-compe ~ *vimtex-complete-nvim-compe* |nvim-compe| is an automatic completion plugin for Neovim. It has support for many different completion sources, including omni-completion. However, |nvim-compe| has been deprecated in favor of the more recent |nvim-cmp|, see |vimtex-complete-nvim-cmp|. The following configuration examples should still be valid for anyone who for some reason would still wish to use |nvim-compe|. https://github.com/hrsh7th/nvim-compe. The omni-completion source can be enabled for TeX/LaTeX files by adding `omni` to the completion sources and specifying the `tex` filetype. For example, in Lua, it should look something like this: >lua require('compe').setup({ source = { omni = { filetypes = {'tex'}, }, }, -- the rest of your compe config... }) And in Vimscript, it should look something like this: >vim let g:compe.source = { \ 'omni': { \ 'filetypes': ['tex'], \ } \} MUcomplete ~ *vimtex-complete-mucomplete* MUcomplete is an implementation of chained (fallback) completion, whereby several completion methods are attempted one after another until a result is returned. The plugin is available here: https://github.com/lifepillar/vim-mucomplete. To enable automatic completion with MUcomplete, use the following options: >vim let g:mucomplete#can_complete = {} let g:mucomplete#can_complete.tex = \ { 'omni': { t -> t =~# g:vimtex#re#neocomplete . '$' } } ============================================================================== FOLDING *vimtex-folding* *vimtex-bib-folding* VimTeX can fold documents according to the LaTeX structure (part, chapter, section and subsection). Folding in tex files is turned off by default, but can be enabled if desired, either through the option |g:vimtex_fold_enabled|, or manually with >vim set foldmethod=expr set foldexpr=vimtex#fold#level(v:lnum) set foldtext=vimtex#fold#text() The folding is mainly configured through the dictionary option |g:vimtex_fold_types|. Note: The |fold-expr| method of folding is well known to be slow, e.g. for long lines and large files. To speed things up, the user may want to enable the |g:vimtex_fold_manual| option. An alternative is to add a dedicated plugin that improves folding speed for the slow fold methods, e.g. https://github.com/Konfekt/FastFold. In order to get slightly cleaner fold text, I recommend setting the global 'fillchars' option to a single space for folds: >vim set fillchars=fold:\ Note: Remember to include the whitespace after backslash! In addition, VimTeX also provides basic folding in bibtex files. This is disabled by default, but will be enabled if |g:vimtex_fold_enabled| is set to 1 or |v:true|. It can also be individually configured with |g:vimtex_fold_bib_enabled|. Associated settings: * |g:vimtex_fold_enabled| * |g:vimtex_fold_manual| * |g:vimtex_fold_levelmarker| * |g:vimtex_fold_types| * |g:vimtex_fold_types_defaults| * |g:vimtex_fold_bib_enabled| * |g:vimtex_fold_bib_max_key_width| ============================================================================== INDENTATION *vimtex-indent* *vimtex-bib-indent* VimTeX provides custom indentation functions both for LaTeX documents and for bibliography files (`.bib` files). Associated settings: * |g:vimtex_indent_enabled| * |g:vimtex_indent_bib_enabled| * |g:vimtex_indent_delims| * |g:vimtex_indent_ignored_envs| * |g:vimtex_indent_lists| * |g:vimtex_indent_on_ampersands| * |g:vimtex_indent_tikz_commands| ============================================================================== SYNTAX HIGHLIGHTING *vimtex-syntax* VimTeX provides a core syntax plugin combined with package specific addons. The syntax plugin aims to be both consistent, structured, and efficient. The package specific addons are generally only loaded when applicable. In these modern times, a lot of people have started to rely on Tree-sitter for syntax highlighting (and more). Thus, it is pertinent to mention that a couple of the text objects rely on the syntax highlighting rules to work. See also |vimtex-text-objects| and |vimtex-faq-treesitter|. LaTeX is a macro expansion language and it is impossible to write a fully correct syntax parser without running the `tex` compiler itself. VimTeX aims to be pragmatic and provide a best-effort syntax highlighting - a decent trade off between simplicity and completeness. There will probably always be situations where the parser will fail, and in some cases it may be hard to "recover". It is therefore possible to manually activate a severely reduced syntax zone to handle such situations. The zone is activated with the directive `% VimTeX: SynIgnore on` and disabled with the similar directive `% VimTeX: SynIgnore off`, e.g.: >latex % VimTeX: SynIgnore on \catcode`\$=11 $ \catcode`\$=3 % VimTeX: SynIgnore off The above LaTeX code will look plain, but OK with VimTeX. Note: The directive is matched case insensitive, and the synonyms `enable` and `disable` may be used instead of `on` and `off`. Overleaf's magic comment [0] is also supported similarly as the `SynIgnore` method described above, i.e.: >latex %%begin novalidate \catcode`\$=11 $ \catcode`\$=3 %%end novalidate The VimTeX syntax plugin is loosely based on Dr Chip's syntax plugin for LaTeX which is shipped by default with Vim and neovim (|ft-tex-syntax|) [1]. There are several major differences that users may want to be aware of: * VimTeX syntax use different names for almost all syntax groups. * VimTeX syntax does not support syntax based folding. * VimTeX syntax does not lint `@` in commands, e.g. `\@cmd` (you should know what you are doing). [0]: https://www.overleaf.com/learn/how-to/Code_Check [1]: http://www.drchip.org/astronaut/vim/index.html#SYNTAX_TEX Associated settings: * |g:vimtex_syntax_enabled| * |g:vimtex_syntax_custom_cmds| * |g:vimtex_syntax_custom_cmds_with_concealed_delims| * |g:vimtex_syntax_conceal| * |g:vimtex_syntax_conceal_cites| * |g:vimtex_syntax_conceal_disable| * |g:vimtex_syntax_nested| * |g:vimtex_syntax_packages| ------------------------------------------------------------------------------ SYNTAX CONCEAL *vimtex-syntax-conceal* VimTeX utilizes the |syn-conceal| feature of Vim to allow displaying commands like `\alpha` as `α`. That is, various elements/commands can be concealed or substituted with a unicode symbol. This feature is mostly enabled by default. Various types of concealments can be enabled/disabled with |g:vimtex_syntax_conceal|. The entire feature can be fully disabled with |g:vimtex_syntax_conceal_disable|. For conceals to work properly, one must set the option 'conceallevel' to 2. It is also good to be aware of the 'concealcursor' option. It is very important to note that not all fonts are suitable for this feature. That is, for this feature to work well, you should install and use a font that includes unicode characters. For Vim or Neovim in a terminal, this means you must configure your terminal to use such a font. This is, of course, an exercise for the reader, but here is a list of some possibly useful links: * https://www.programmingfonts.org/ * A convenient site to test different "programming" fonts. Not always easy to see if the unicode support is good, but at least you can see examples of how they look. * https://wiki.archlinux.org/index.php/Fonts * The Arch Wiki is famous for being useful, and it does not fail. But it is rather technical and of course refers to Arch Linux packages. It may still be a good source of knowledge and inspiration. * https://www.binarytides.com/gorgeous-looking-fonts-ubuntu-linux/ * This is a blog post on how to install some modern/good looking/better fonts on a Ubuntu system. * https://github.com/cormullion/juliamono * This is the font that I personally use (2021-03-24, @lervag). ------------------------------------------------------------------------------ SYNTAX CORE SPECIFICATION *vimtex-syntax-core* As it is relatively common for some users to customize their colorschemes, it is useful to describe some of the underlying "philosophy" of the syntax rules. Note that, for the following information to be useful, the reader should have at least some basic understanding of how to customize their colorschemes and syntax highlighting. The best resources to learn about this are: i) |usr_06| "Using syntax highlighting" (READ THIS FIRST) ii) https://gist.github.com/romainl/379904f91fa40533175dfaec4c833f2f "The right way to override any highlighting if you don't want to edit the colorscheme file directly" This is a good resource that describes how to properly customize the highlighting of syntax groups on top of a basic colorscheme. iii) https://github.com/lervag/vimtex/wiki/Syntax This wiki page gives an example of how to customize and fine-tune syntax highlighting of TeX and BibTeX files. iv) |usr_44| "Your own syntax highlighted" (ADVANCED) The main philosophy of the VimTeX syntax plugin is to keep things simple, structured, and consistent. There is a small set of primitive syntax elements whose highlighting rules are linked to conventional highlight groups (see |group-name|). More specialized syntax elements are then linked to a corresponding primitive syntax element. This allows a user to change the highlighting of primitives with the effect that corresponding elements are automatically also updated. It is also possible to override specialized groups to link them to other conventional groups or set colors directly. This gives a high degree of flexibility with regards to customizing colorschemes for LaTeX files. See |vimtex-syntax-reference| for tables of the most important syntax groups with examples and descriptions. Most of LaTeX syntax is based around the macro expansion where forms are of the type `\name` + `[optional group(s)]` + `{argument group(s)}`, where there can often (not always) be white spaces and newlines between the elements. An argument group can often consist of other top level elements, but not always. Further, since LaTeX is designed to have very strong support for typing mathematical equations, there are several ways to start math mode, e.g. `$ ... $`, `$$ ... $$`, `\( ... \)`, `\[ ... \]`, and `\begin{equation}` matched with `\end{equation}`. Within math mode, there's a different subset of commands available, and it is common to want a slightly different highlighting of the math mode regions. VimTeX's syntax script is implemented to support these basic structures as well as a large set of more specific commands and elements. The more specific rules define groups whose names are more specific, and it is usually possible to define custom highlighting of specific commands and argument groups. Finally, it is useful to explain the naming scheme of specialized groups. The general idea can be described as follows. `texCmd{type}` `tex{type}Opt` `tex{type}Arg` A lot of LaTeX macros and commands are specified specifically with a given number of optional and real arguments. They may also specify what those arguments are. In most cases, the highlighting of `texCmd{type}` is linked to `texCmd` and the highlighting of `tex{type}Opt` and `tex{type}Arg` are respectively linked to `texOpt` and `texArg`. An example of this scheme is `texCmdAuthor`, `texAuthorOpt`, and `texAuthorArg` for `\author[...]{...}`. Often, but not always, `texCmd{name}` is coupled with `tex{name}*` groups. For example, `\include{...}` wants a file argument. The command is matched as `texCmdInput`, but it is followed by a `texFileArg` argument group. `tex{type}Zone` Some commands open specific syntax regions that have different rules. Math mode is a good example. Math mode is highlighted differently, and the main syntax regions are named `texMathZone*`. The `tex{type}Zone`s may typically contain their own (sub)sets of syntax groups that are only matched within the specific region. Another example is the inclusion of nested syntax highlighting with e.g. the `minted` or `listings` packages. `tex{type}{element}` Some regions or commands include other types of elements, e.g. parameters like in `\def\name #1` where `#1` is matched as `texDefParm`. For completeness: `\def` is matched as `texCmdDef` and `\name` is matched as `texDefArgName`. ------------------------------------------------------------------------------ SYNTAX PACKAGE SPECIFICATION *vimtex-syntax-packages* VimTeX provides several package specific syntax addons that provide richer syntax highlighting. These are built around the same principles as explained in |vimtex-syntax-core|. The syntax improvements for a specific package are by default loaded only if that package is detected in the current document (as explained in |vimtex-package-detection|). This generally works well when a document is compiled, but VimTeX may fail to detect packages for new documents or documents that are not compiled. It is therefore possible to configure that individual syntax packages should always load. One may also disable individual syntax packages. See |g:vimtex_syntax_packages| for a full list of which syntax addons exist and how to configure them. ------------------------------------------------------------------------------ SYNTAX GROUP REFERENCE *vimtex-syntax-reference* The following is a reference of the main syntax groups and its default highlighting, as well as one or more examples of what it matches. Most of the primitive groups are linked to conventional syntax groups as listed in |group-name|. In the examples, capital letters are used to indicate which parts are matched by the current group. For even more details, please refer to the code itself: * Core elements: The `vimtex#syntax#core#init_highlights()` function in the file `/autoload/vimtex/syntax/core.vim` specifies the default highlighting of the core groups. * Package specific groups and elements are defined in the package specific scripts: `/autoload/vimtex/syntax/p/*.vim`. Note: * This is only a reference of the main groups. There are also other groups available. See the source files for the full lists. * The following lists might not be always completely up to date. If you find inconsistencies or errors, please open an issue. Table 1: A list of groups that are only primitive link targets. ~ > GROUP DEFAULT ---------------------------------------------------------------------------- VimtexMsg ModeMsg VimtexInfo Question VimtexTodo Todo VimtexWarning WarningMsg VimtexError ErrorMsg VimtexFatal Error VimtexSuccess Statement texCmdType Type texParm Special texZone PreCondit texSymbol SpecialChar texError VimtexError Table 2: A list of the most common normal LaTeX groups. ~ > GROUP DEFAULT EXAMPLE ---------------------------------------------------------------------------- texComment Comment % COMMENT texCommentTodo VimtexTodo % TODO texDelim Delimiter {, }, [, and ] texCmd Statement \CMD texOpt Identifier \cmd[OPT] texOptSep NormalNC [a, b] (commas) texOptEqual texSymbol [a=b] texArg Include \cmd[...]{ARG} texSpecialChar SpecialChar \S, \P, \$, \;, ... texCmdInput texCmd \INPUT \INCLUDE \INCLUDEONLY \INCLUDEGRAPHICS texCmdBib texCmd \BIBLIOGRAPHY \BIBLIOGRAPHYSTYLE texCmdClass texCmd \DOCUMENTCLASS texCmdPackage texCmd \USEPACKAGE \REQUIREPACKAGE texFileOpt texOpt \includegraphics[PACKAGE OPTIONS] \documentclass[CLASS OPTIONS] texFileArg texArg \input{FILE} \include{FILE} \includegraphics[...]{FILE} \bibliographystyle{FILE} \documentclass[...]{CLASS} texFilesOpt texFileOpt \usepackage[PACKAGE OPTIONS] \RequirePackage[PACKAGE OPTIONS] texFilesArg texFileArg \includeonly{FILE1, FILE2} \bibliography{FILE1, FILE2} \usepackage[...]{PACKAGE1, PACKAGE2} \RequirePackage[...]{PACKAGE1, PACKAGE2} texCmdTitle texCmd \TITLE texTitleArg Underlined \title{MAIN TITLE} texCmdAuthor texCmd \AUTHOR texAuthorOpt texOpt \author[OPT] texAuthorArg NONE \author[...]{AUTHOR LIST} texCmdPart texCmd \(SUB*)SECTION texPartArgTitle String \(sub*)section{TITLE} texCmdEnv texCmd \BEGIN; \END texEnvArgName PreCondit \begin{ENVNAME} texCmdRef texCmd \CITE; \LABEL texRefArg Special \cite{REFERENCE}; \label{REF} texE3Variable texCmd \G_MYFILE_NAME_STR texE3Constant texE3Variable \C_MYFILE_NAME_STR texE3Function texCmdType \STR_NEW:n texE3Type texParm \str_new:N texCmdParbox texCmd \PARBOX[p][h][i]{w}{c} texBoxOptPosVal texSymbol \parbox[P][h][i]{w}{c} \begin{minipage}[P][h][i]{w} texBoxOptIPosVal texBoxOptPosVal \parbox[p][h][I]{w}{c} \begin{minipage}[p][h][I]{w} Table 3: A list of math mode groups. ~ > GROUP DEFAULT EXAMPLE ---------------------------------------------------------------------------- texMathZone Special texMathZoneLI texMathZone \( HERE \) texMathZoneLD texMathZone \[ HERE \] texMathZoneTI texMathZone $ HERE $ texMathZoneTD texMathZone $$ HERE $$ texMathZoneEnv texMathZone \begin{menv} HERE \end{menv} texMathZoneEnvStarred texMathZone \begin{menv*} HERE \end{menv*} texMathZoneEnsured texMathZone \ensuremath{HERE} texMathDelimZone texDelim texMathDelimZoneLI texMathDelimZone \(; \) texMathDelimZoneLD texMathDelimZone \[; \] texMathDelimZoneTI texMathDelimZone $ texMathDelimZoneTD texMathDelimZone $$ texCmdMathEnv texCmdEnv \BEGIN; \END (Only for math environments.) texMathEnvArgName Delimiter \begin{EQUATION} texCmdMath texCmd \ENSUREMATH texMathDelim Type \LVERT texMathDelimMod texMathDelim \LEFT\lvert \RIGHT\rvert texMathOper Operator Basic operators: +-=/ texMathSuperSub texMathOper Sub and super operators (^, _) texMathError texError Unmatched region endings Table 4: A list of other important groups. ~ > GROUP DEFAULT EXAMPLE ---------------------------------------------------------------------------- texLength Number Length units, e.g. "4 cm". Only when contained e.g. in option groups. texLigature texSymbol --; ---; ``; ''; ,, texCmdAccent texCmd \"{a} texCmdLigature texSpecialChar \ss; \ae texCmdSpaceCodeChar Special Catcodes. For more info, see: https://en.wikibooks.org/wiki/TeX/catcode texCmdTodo VimtexTodo \TODOSOMETHING texCmdVerb texCmd \VERB texVerbZoneInline texZone \verb+VERB TEXT+ texVerbZone texZone \begin{verbatim} VERB TEXT \end{verbatim} texCmdDef texCmdNew \DEF texDefArgName texArgNew \def\NAME texDefParm texParm \def\name #1 texCmdItem texCmd \item Table 5: Bold, italic and underline groups. ~ These groups are used as targets for various (nested) commands, e.g. `\emph{\textbf{...}}`. > GROUP EFFECT ---------------------------------------------------------------------------- texStyleBold Bold texStyleItal Italic texStyleUnder Underlined texStyleBoth Bold + italic texStyleBoldUnder Bold + underlined texStyleItalUnder Italic + underlined texStyleBoldItalUnder Bold + italic + underlined texMathStyleBold Bold [ONLY in math mode] texMathStyleItal Italic [ONLY in math mode] ============================================================================== NAVIGATION *vimtex-navigation* Vim already has a lot of useful navigation related features, such as |tags-and-searches| and |include-search|. VimTeX improves the latter feature by setting the 'include' and 'includeexpr' options, see |vimtex-includeexpr|. VimTeX also provides a separate table-of-content feature. This works by parsing the LaTeX project and displaying a table of contents in a separate window. For more info, see |vimtex-toc|. The "engine" for collecting the table-of-content entries may also be used as a backend for external plugins. There are sources for |denite.nvim|, |unite.vim| and |fzf.vim| that should work well. The source code may be used as inspiration to write custom sources or sources for other, similar plugins. ------------------------------------------------------------------------------ INCLUDE EXPRESSION *vimtex-includeexpr* VimTeX provides an advanced |includeexpr| that makes it possible to open source files for e.g. packages and documentclasses with the |gf| command. The implementation relies on `kpsewhich` to find the source files. Consider the following example: >latex \documentclass{article} \usepackage{MyLocalPackage} \usepackage{SomeOtherPackage,YetAnotherPackage} ... With the cursor on the documentclass name `article` or one of the package names, |gf| will take you to the TeX source files (typically `.cls` file for documentclass and `.sty` files for packages). ------------------------------------------------------------------------------ TABLE OF CONTENTS *vimtex-toc* |vimtex-toc| displays a table of contents (ToC) for the current LaTeX document. The ToC entries may be activated/jumped to with or . There are currently four different "layers" of entries: * content This is the main part and the "real" ToC * todo This shows TODOs from comments and `\todo{...}` commands * label This shows `\label{...}` commands * include This shows included files The ToC is configured with |g:vimtex_toc_config|. One may change things from where the ToC window is positioned to which layers to show and more. Please read the option help for details. The ToC parser uses a list of matchers to parse the LaTeX project for the ToC entries. One may add custom matchers through the |g:vimtex_toc_custom_matchers| option. The syntax of a custom matcher is specified here: |toc_matcher_specification|. Note: By setting the `mode` configuration key to > 2, the separate ToC window is not opened and most of the features mentioned here will be irrelevant. One may force file input entries of the "include" type into the ToC through comments with the following syntax: > % vimtex-include: /path/to/file The path may be absolute or relative. In the latter case, it will be relative to the current root (as printed by |:VimtexInfo|). This will add an entry in the ToC which makes it easy to open any file. Any file opened through the ToC that was included in this manner will be linked to the current VimTeX project, and thus the ToC and similar commands will be available, even if the file is not a LaTeX file. *vimtex-toc-custom-maps* Some people may want to have separate mappings for different ToC contents, e.g. one mapping to open a table of labels and todos and a different mapping to open a table of include files. This may be easily added with custom mappings: >vim augroup vimtex_customization autocmd! autocmd FileType tex call CreateTocs() augroup END function CreateTocs() let g:custom_toc1 = vimtex#toc#new({ \ 'layers' : ['label', 'todo'], \ 'todo_sorted' : 0, \ 'show_help' : 0, \ 'show_numbers' : 0, \ 'mode' : 4, \}) nnoremap \ly :call g:custom_toc1.open() let g:custom_toc2 = vimtex#toc#new({ \ 'layers' : ['include'], \ 'show_help' : 0, \}) nnoremap \lY :call g:custom_toc2.open() endfunction The `vimtex#toc#new` function takes a dictionary argument that may be used to override the one main configuration (i.e. the combination of the default values and |g:vimtex_toc_config|). Associated settings: * |g:vimtex_toc_enabled| * |g:vimtex_toc_custom_matchers| * |g:vimtex_toc_todo_labels| * |g:vimtex_toc_show_preamble| * |g:vimtex_toc_config| ------------------------------------------------------------------------------ DENITE AND UNITE SOURCES *vimtex-denite* *vimtex-unite* https://github.com/Shougo/denite.nvim https://github.com/Shougo/unite.vim |denite.nvim| is a popular interface for many things, including outlines. Although VimTeX includes a simple interface for a tables of contents, it also makes sense to provide these as a source to |denite.nvim|. The source name is simply `vimtex`. |unite.vim| is the predecessor to |denite.nvim|. As for denite, there is a source called `vimtex`. If one prefers the |denite.nvim| or |unite.vim| source to the VimTeX interface, one may override the default mapping, e.g.: >vim nnoremap lt :Denite vimtex nnoremap lt :Unite vimtex ------------------------------------------------------------------------------ FZF INTEGRATION *vimtex-fzf* https://github.com/junegunn/fzf.vim https://github.com/junegunn/fzf |fzf.vim| integrates the general-purpose command-line fuzzy finder |fzf| into vim and neovim. Similar to the |denite.vim| and |unite.vim| source it may be used to quickly navigate VimTeX's built-in ToC feature. To use it, just define a mapping to `vimtex#fzf#run()` in your .vimrc, e.g.: >vim nnoremap lt :call vimtex#fzf#run() You can also choose to only show certain entry "layers", according to this table (see |vimtex-toc| for detailed explanation of the "layers"): `c`: content `t`: todo `l`: label `i`: include The default behavior is to show all layers, i.e. `'ctli'`. To only show `content` and `label`s use: >vim :call vimtex#fzf#run('cl') On Windows the python package Colorama is required for colored output. For Linux and MacOS colors should work out-of-the-box, even without Colorama. A second argument can be passed to this function to customize the FZF options. It should be an object containing the parameters passed to `fzf#run()`. For example, if you've defined `g:fzf_layout`, then those options can be passed to `vimtex#fzf#run`: >vim :call vimtex#fzf#run('ctli', g:fzf_layout) ============================================================================== COMPILER *vimtex-compiler* VimTeX provides an interface to the following LaTeX compilers/compiler backends: * |vimtex-compiler-latexmk| http://users.phys.psu.edu/~collins/software/latexmk-jcc * |vimtex-compiler-latexrun| https://github.com/aclements/latexrun * |vimtex-compiler-tectonic| https://tectonic-typesetting.github.io/ * |vimtex-compiler-arara| https://github.com/cereda/arara * |vimtex-compiler-generic| The interface is implemented in a general way, which makes it relatively easy to add new compilers. Compilation is started and stopped with |:VimtexCompile| and |:VimtexStop|. Although, |:VimtexStop| stopping is only relevant for continuous compilations, and in this case, |:VimtexCompile| itself works as a toggle. Single shot compilation is always available through |:VimtexCompileSS|. The default mappings for these commands are listed here: |vimtex-default-mappings|. It is also possible to compile a selection of the file. To do this, one may either use the mapping, |(vimtex-compile-selected)|, or the command |:VimtexCompileSelected|. The compilers should respect the TeX program directive as described here: |vimtex-tex-program|, except for |vimtex-compiler-arara|, which uses its own set of directives and rules. Associated commands: * |:VimtexCompile| * |:VimtexCompileSS| * |:VimtexCompileSS!| * |:VimtexCompileSelected| * |:VimtexCompileOutput| * |:VimtexStatus| * |:VimtexStatus!| * |:VimtexStop| * |:VimtexStopAll| * |:VimtexErrors| * |:VimtexErrors| * |:VimtexClean| * |:VimtexClean!| * |:VimtexErrors| Associated settings: * |g:vimtex_compiler_enabled| * |g:vimtex_compiler_method| * |g:vimtex_compiler_latexmk| * |g:vimtex_compiler_latexmk_engines| * |g:vimtex_compiler_latexrun| * |g:vimtex_compiler_latexrun_engines| * |g:vimtex_compiler_tectonic| * |g:vimtex_compiler_arara| * |g:vimtex_compiler_generic| * |$VIMTEX_OUTPUT_DIRECTORY| Associated events: * |VimtexEventCompileStarted| * |VimtexEventCompileStopped| * |VimtexEventCompileSuccess| * |VimtexEventCompileFailed| ------------------------------------------------------------------------------ LATEXMK *vimtex-compiler-latexmk* http://users.phys.psu.edu/~collins/software/latexmk-jcc > latexmk is a perl script for running LaTeX the correct number of times to > resolve cross references, etc; it also runs auxiliary programs (e.g. > bibtex). It has a number of other useful capabilities, for example to start > a previewer and then run latex whenever the source files are updated, so > that the previewer gives an up-to-date view of the document. The script runs > on both UNIX and MS-WINDOWS (XP, etc). `latexmk` is a compiler backend that handles recompilation of LaTeX documents when source files have been changed. VimTeX uses the continuous mode by default, but `latexmk` also allows single shot compilations. The compiler may be configured through the |g:vimtex_compiler_latexmk| option. If the `callback` key is enabled (it is by default and there is really no reason to disable it!), then compilation errors will be parsed automatically. This is done by utilizing the tricks explained below. Although `latexmk` can control viewers directly, VimTeX disables this feature with `-view=none` to get full control of the viewers. As stated, one may customize the `latexmk` options through |g:vimtex_compiler_latexmk|. However, one may also configure `latexmk` explicitly through a global `~/.latexmkrc` file, or a project specific `.latexmkrc` file. It is important to know that command line arguments have priority, so one may want to use custom options if one wants to specify particular things in a configuration file. A particular set of options are very convenient for a good coupling between `latexmk` and Vim: `$compiling_cmd`, `$success_cmd`, and `$failure_cmd`. These options can be used to specify commands that are run by `latexmk` before and after compilation. They are used by VimTeX to achieve callbacks after compilation has finished through |vimtex#compiler#callback|. Another neat way to use these options is to use `xdotool` to change the window title of the viewer to indicate the compilation status: >perl $compiling_cmd = "xdotool search --name \"%D\" " . "set_window --name \"%D compiling...\""; $success_cmd = "xdotool search --name \"%D\" " . "set_window --name \"%D OK\""; $failure_cmd = "xdotool search --name \"%D\" " . "set_window --name \"%D FAILURE\""; Note: If you define these options similar to the above `xdotool` trick and still want to enable the VimTeX callbacks, then one must include a semicolon at the end of the `cmd` strings so that VimTeX may append safely to the options. Note: More info on `xdotool` here: https://www.semicomplete.com/projects/xdotool. ------------------------------------------------------------------------------ LATEXRUN *vimtex-compiler-latexrun* https://github.com/aclements/latexrun > See LaTeX run. Run latexrun. > > latexrun fits LaTeX into a modern build environment. It hides LaTeX's > circular dependencies, surfaces errors in a standard and user-friendly > format, and generally enables other tools to do what they do best. `latexrun` is a compiler backend that handles recompilation of LaTeX documents when source files have been changed. However, it is a much simpler backend, and does not support e.g. continuous mode. The compiler may be configured through the |g:vimtex_compiler_latexrun| option. ------------------------------------------------------------------------------ TECTONIC *vimtex-compiler-tectonic* https://tectonic-typesetting.github.io/ > Tectonic is a modernized, complete, self-contained TeX/LaTeX engine, powered > by XeTeX and TeXLive. `tectonic` is a compiler backend that features automatic support file downloading along with reproducible builds and full Unicode and OpenType fonts support thanks to the power of XeTeX. It does not support continuous compilation like |vimtex-compiler-latexmk|, so the only relevant commands are |:VimtexCompile| to start (single shot) compilation, and |:VimtexCompileOutput| to see the compilation output. `tectonic` cleans up intermediate files like `.aux` and log files by default. However, VimTeX's backend invoke it with the flags `--keep-logs` and `--keep-synctex` which enables us to see the errors on the quickfix and it gives us synctex support. Therefore, by default, |(vimtex-clean)| and |:VimtexClean| clean these files. The compiler may be configured through the |g:vimtex_compiler_tectonic| option. Some users may be interested in using a custom command for running `tectonic` in a forced continuous mode by use of external tools like `entr` [0]. This could be achieved with the |vimtex-compiler-generic| interface, e.g. like this: >vim let g:vimtex_compiler_method = 'generic' let g:vimtex_compiler_generic = { \ 'command': 'ls *.tex | entr -c tectonic /_ --synctex --keep-logs', \} [0]: http://eradman.com/entrproject/ ------------------------------------------------------------------------------ ARARA *vimtex-compiler-arara* https://github.com/cereda/arara > arara is a TeX automation tool based on rules and directives. It gives you > subsidies to enhance your TeX experience. `arara` is a TeX automation tool that uses rules and directives that are defined in the preamble of a LaTeX project. The user manual can be found here: https://ctan.uib.no/support/arara/doc/arara-manual.pdf `arara` does not do continuous compilation, so the only relevant commands are |:VimtexCompile| to start (single shot) compilation, and |:VimtexCompileOutput| to see the compilation output. The compiler may be configured through the |g:vimtex_compiler_arara| option. Note: It is not possible to directly specify an output directory from VimTeX. This is a restriction caused by the design of arara. However, since one may still want to specify custom output directories, VimTeX allows to customize the output directory through the environment variable |$VIMTEX_OUTPUT_DIRECTORY|. ------------------------------------------------------------------------------ GENERIC COMPILER *vimtex-compiler-generic* There are a lot of various compiler backends for LaTeX, and it is also possible to simply use things like a Makefile. The generic backend allows to use mostly whatever you want. However, since it is a generic implementation, it will not be as well integrated as e.g. |vimtex-compiler-latexmk|. An example may be illuminating. Let's say you want to use a Makefile to compile your project. Then the following shows how to configure with the generic interface, including how to include a simple callback function that reacts to the compiler program output. >vim function! Callback(msg) " Use a regex match on the compiler output to get automatic VimtexErrors " functionality. The below conditional must likely be changed to be " useful, of course! if a:msg =~# 'error' call vimtex#compiler#callback(!vimtex#qf#inquire(b:vimtex.tex)) endif endfunction let g:vimtex_compiler_method = 'generic' let g:vimtex_compiler_generic = { \ 'command' : 'make', \ 'hooks': [function('Callback')], \} < See also |vimtex-compiler-tectonic| for another example that relies on the generic interface to run a "continuous" tectonic command. Some examples of build tools that can be used with the generic backend: * Light LaTeX Make (llmk) https://ctan.org/pkg/light-latex-make > This program is yet another build tool specific for LaTeX documents. Its > aim is to provide a simple way to specify a workflow of processing LaTeX > documents and encourage people to always explicitly show the right > workflow for each document. * spix (Yet another TeX compilation tool: simple, human readable, no option, no magic) https://ctan.org/pkg/spix > SpiX offers a way to store information about the compilation process for > a tex file inside the tex file itself. Just write the commands as comments > in the tex files, and SpiX will extract and run those commands. > Everything is stored in the tex file (so that you are not missing some > piece of information that is located somewhere else), in a human-readable > format (no need to know SpiX to understand it). ============================================================================== SYNTAX CHECKING (LINTING) *vimtex-lint* VimTeX provides syntax checking (linting) for TeX and BibTeX files through three compilers: `lacheck` [1], `chktex` [2], and `biber` [3]. These may be activated with the |:compiler| command, see |compiler-select|. A selected compiler may then be used e.g. with |:make| or |:lmake|. See the following text for some tips on how one may use this feature. It is possible to use more automatic linting through dedicated plugins. For more information, see |vimtex-af-linting|. Associated settings: * |g:vimtex_lint_chktex_parameters| * |g:vimtex_lint_chktex_ignore_warnings| ------------------------------------------------------------------------------ A common workflow is to utilize the |location-list| with |:lmake|: - To lint the currently open TeX file with `lacheck`, run `:compiler lacheck|lmake` - To lint the currently open TeX file with `chktex`, run `:compiler chktex|lmake` - To lint the currently open BibTeX file with `biber`, run `:compiler bibertool|lmake` After linting, the compiler or linter messages are added to the location list. This list may be displayed in the location-list window with |:lwindow|, and one may jump between the entries with |:lN| and |:lp|. To automatically open the location-list window after linting is finished, one may add the following to one's |vimrc|: >vim augroup VimTeX autocmd! autocmd QuickFixCmdPost lmake lwindow augroup END For convenience, one may also define a command for linting for each file type and add an autocmd to automatically lint on save. The following gives an example for `bibertool` and BibTeX, but one may of course do the same with `lacheck` and/or `chktex` for TeX files as well. First, add the following to `~/.vim/after/ftplugin/bib.vim`: >vim command! -buffer -bang Lint compiler bibertool | lmake Then, add to `~/.vim/after/ftplugin/bib.vim`: >vim augroup VimTeX autocmd! autocmd BufWrite compiler bibertool | lmake! augroup END If one minds that Vim becomes unresponsive while linting, then one may utilize plugins like |vim-dispatch| [4], |AsyncRun| [5] or |tasks.vim| [6]. With `vim-dispatch`, one may replace the `:lmake` call with `:Make`. Note that this may conflict with the listing of compilation errors, since `:Make` from `vim-dispatch` uses the quickfix window. `tasks.vim` provide `:LMake` which allows one to use the location list. For `AsyncRun`, one may define a custom `:Make` command with: >vim command! -bang -nargs=* -complete=file Make \ AsyncRun -auto=make -program=make The quickfix window that lists the linter errors and warnings can then be opened by |:cwindow| and they can be jumped to by |:cN| respectively |:cp|. Often, a syntax error in a BibTeX file is due to a missing comma after an entry. One may define a command to automatically add such missing commas, e.g. by adding the following lines in `~/.vim/after/ftplugin/bib.vim`: >vim command! -buffer -range=% -bar AddMissingCommas keeppatterns \ ,substitute:\v([}"])(\s*\n)+(\s*\a+\s*\=):\1,\2\3:giep To call this automatically after saving a BibTeX file, add the following autocommand inside a proper autocommand group (e.g. `augroup VimTeX` as suggested above) in `~/.vim/after/ftplugin/bib.vim`: >vim autocmd BufWrite exe \ 'normal! m`' | silent AddMissingCommas | silent! exe 'normal! g``' Finally, for more full-fledged linting in Vim, see the plug-ins mentioned in |vimtex-and-friends|. [1] https://ctan.org/pkg/lacheck [2] https://www.nongnu.org/chktex/ [3] https://github.com/plk/biber [4] https://github.com/tpope/vim-dispatch [5] https://github.com/skywind3000/asyncrun.vim [6] https://github.com/mg979/tasks.vim ============================================================================== GRAMMAR CHECKING *vimtex-grammar* VimTeX provides several compilers for grammar checking TeX files through the |compiler-select| feature in Vim. A compiler may be activated with the |:compiler| command (see |vimtex-lint| above for some more tips on how to use this feature). The selected compiler may then be used e.g. with |:make| or |:lmake|. As an example, one may do the following to use the |location-list| with a given checker: >vim :compiler {checker}|lmake The following is a list of the available checkers: textidote ~ See more details here: |vimtex-grammar-textidote| vlty ~ See more details here: |vimtex-grammar-vlty| style-check ~ https://github.com/nspring/style-check.git The language of the Tex file is determined by the option |'spelllang'|. This option can be specified in one's vimrc file, but it can also be specified in a |modeline| (see also the user manual section |21.6| for a gentle introduction to the use of modelines). Other possibilities for grammar and language checking are: * The LTeX project: a grammar and spell checking tool available as a language server. See |vimtex-af-lsp| for more info. * Angry Reviewer: An off-line vim plugin for the AngryReviewer service that provides style suggestions for academic and scientific text in the quickfix list. https://github.com/anufrievroman/vim-angry-reviewer ------------------------------------------------------------------------------ TEXTIDOTE *vimtex-grammar-textidote* The `textidote` compiler is a VimTeX wrapper over TeXtidote [1]. TeXtidote is a correction tool for LaTeX documents to check grammar, style, and perform spell checking. Configuration of the wrapper is controlled by the Vim dictionary |g:vimtex_grammar_textidote|. In particular, it is important to specify the `jar` key to the path of the executable jar file `textidote.jar`. Please note that if one installs `textidote` with a package manager e.g. in some common Linux distributions, the `.jar` file might be missing. If so, it should be possible to download it manually from [1]. However, before one does that, it can be smart to check the top lines of the installed executable, as it may be a simple Bash script wrapper. [1]: https://sylvainhalle.github.io/textidote/ ------------------------------------------------------------------------------ VLTY *vimtex-grammar-vlty* The `vlty` compiler uses the Python package `YaLafi` [1] for extracting the plain text and combines this with the proofreading software `LanguageTool` [2]. The name `vlty` comes from VimTeX + LanguageTool + YaLafi. In order to use `vlty`, you need local installations of both components. An archive of `LanguageTool` can be downloaded from [3]. After uncompressing at a suitable place, the path to it is specified as shown below. On a system like `Arch Linux`, `LanguageTool` may also be installed with: >sh sudo pacman -S languagetool `YaLafi` itself can be installed with: > pip install --user yalafi Configuration is controlled by the Vim dictionary |g:vimtex_grammar_vlty|. As a minimal example, one could write in |vimrc|: >vim let g:vimtex_grammar_vlty = {'lt_directory': 'path/to/LanguageTool'} set spelllang=en_gb The given directory has to contain the `LanguageTool` software, including for instance the file `languagetool-server.jar`. If instead `LanguageTool` is installed through a package manager as mentioned above, one could write: >vim let g:vimtex_grammar_vlty = {'lt_command': 'languagetool'} set spelllang=en_gb Calling `:compiler vlty` will raise an error message if some component cannot be found. Note: Spell checking with `LanguageTool` is only enabled if a country code is specified in |'spelllang'|. [1] https://github.com/torik42/YaLafi [2] https://www.languagetool.org [3] https://www.languagetool.org/download/ ============================================================================== VIEW *vimtex-view* VimTeX provides the command |:VimtexView| to open the output PDF in a desired viewer specified by |g:vimtex_view_method|. The command is mapped to `lv` by default. The supported viewers are described in |vimtex-view-configuration|, which also explains how to configure them. Many viewers support synctex for navigating between the PDF and the source tex file. If possible, |:VimtexView| will perform forward search when the viewer is opened. See |vimtex-synctex| for more details. Associated settings: * |g:vimtex_view_enabled| * |g:vimtex_view_automatic| * |g:vimtex_view_forward_search_on_start| * |g:vimtex_view_use_temp_files| * |g:vimtex_view_method| * |g:vimtex_view_general_options| * |g:vimtex_view_general_viewer| Associated events: * |VimtexEventView| * |VimtexEventViewReverse| ------------------------------------------------------------------------------ VIEWER CONFIGURATION *vimtex-view-configuration* |g:vimtex_view_method| is the main configuration variable. It allows to choose between a set of predefined viewers, including a generic customizable interface. For the predefined viewers, forward search with synctex should usually work without any further configuration. With the general viewer, one may often specify options to enable forward search. Inverse search requires configuration on the viewer side in most cases. The generic interface is flexible. It relies on three options: * |g:vimtex_view_general_viewer| Specify the viewer executable. * |g:vimtex_view_general_options| Specify the viewer options (e.g. to specify forward search configuration). The following is a list of popular PDF viewers, in alphabetic order, and how they can be configured to work with VimTeX. *vimtex-view-evince* Evince ~ https://wiki.gnome.org/Apps/Evince Evince is a document viewer for viewing multiple document formats, including PDFs. It comes by default with Gnome. Configuration: >vim let g:vimtex_view_general_viewer = 'evince' Note: Evince only supports synctex through DBus, which is not supported by VimTeX. Thus VimTeX does not support forward and inverse search with Evince. However, the Vim plugin `SVED` by Peter Jorgensen is reported to work well in combination with VimTeX. See the plugin page [0] for more information. [0]: https://github.com/peterbjorgensen/sved *vimtex-view-mupdf* MuPDF ~ https://www.mupdf.com/ MuPDF is a very minimalistic and quick PDF viewer. It does not support synctex itself, but VimTeX provides both forward and inverse search by abusing `xdotool`. Inverse search must be used from within VimTeX with the mapping |(vimtex-reverse-search)| (default mapping: `'lr'`). One can also use |g:vimtex_view_mupdf_send_keys| to specify a set of keys that is sent to MuPDF on startup. Configuration: >vim let g:vimtex_view_method = 'mupdf' Associated settings: * |g:vimtex_view_mupdf_options| * |g:vimtex_view_mupdf_send_keys| Note: Both forward and inverse search requires `xdotool` to work. Forward search will only take you to the correct page. Inverse search will take you to the line in Vim that corresponds to the first line of the current page in MuPDF. Note: Viewer handling uses window title matching. If there exists another pdf viewer with the same name as the current project pdf file, then there might be conflicts, and so MuPDF might not work as expected. *vimtex-view-okular* Okular ~ https://okular.kde.org/ Okular is a very feature rich PDF viewer that supports both forward and inverse search. Configuration: >vim let g:vimtex_view_general_viewer = 'okular' let g:vimtex_view_general_options = '--unique file:@pdf\#src:@line@tex' Inverse search can be set up within Okular in the settings pane under "Settings > Editor > Custom Text Editor" [0]. The following is the recommended settings for Vim and neovim, respectively: >bash vim -v --not-a-term -T dumb -c "VimtexInverseSearch %l '%f'" nvim --headless -c "VimtexInverseSearch %l '%f'" To perform an inverse search in Okular, do `shift + click` while browse mode is enabled. For more info, see |vimtex-synctex-inverse-search|. [0]: https://docs.kde.org/stable5/en/okular/okular/inverse_search.html *vimtex-view-qpdfview* qpdfview ~ https://launchpad.net/qpdfview qpdfview is a tabbed document viewer. It supports both forward and inverse search. Configuration: >vim let g:vimtex_view_general_viewer = 'qpdfview' let g:vimtex_view_general_options \ = '--unique @pdf\#src:@tex:@line:@col' Inverse search must be set up from within qpdfview under "Edit -> Settings -> Source Editor". The following is the recommended settings for Vim and neovim, respectively: >bash vim -v --not-a-term -T dumb -c "VimtexInverseSearch %2 '%1'" nvim --headless -c "VimtexInverseSearch %2 '%1'" Use right click to perform an inverse search. For more info, see |vimtex-synctex-inverse-search|. *vimtex-view-sioyek* Sioyek ~ https://sioyek.info/ Sioyek is a PDF viewer designed for reading research papers and technical books. Configuration: >vim let g:vimtex_view_method = 'sioyek' Inverse search should be automatically configured and work out of the box. VimTeX will try to pass options to Sioyek to automatically configure inverse search. This means that, in most cases, inverse search should work as expected without any further configuration. One may still be interested in learning how inverse-search configuration works, in which case one should read |vimtex-synctex-inverse-search|. Note: The interpolation variables for Sioyek inverse search configuration are `%2` and `%1`, not `%l` and `%f`. Associated settings: * |g:vimtex_callback_progpath| * |g:vimtex_view_sioyek_exe| *vimtex-view-skim* Skim ~ https://skim-app.sourceforge.net/ https://sourceforge.net/p/skim-app/wiki/TeX_and_PDF_Synchronization Skim is a PDF reader and note-taker for OS X. It is designed to help you read and annotate scientific papers in PDF, but is also great for viewing any PDF file. The VimTeX implementation supports forward search and uses a callback to update Skim after successful compilations. Configuration: >vim let g:vimtex_view_method = 'skim' To configure inverse search: Open the `Sync` tab in the settings panel in Skim and set the options according to your desired version of Vim. With MacVim, one may use the `MacVim` preset. However, it may be more convenient to use a `Custom` setting and configure the inverse search option to >bash vim -v --not-a-term -T dumb -c "VimtexInverseSearch %line '%file'" nvim --headless -c "VimtexInverseSearch %line '%file'" Inverse search is activated by pressing `Shift` and `Command`, then clicking the text you want to search. For more info on inverse search, see |vimtex-synctex-inverse-search|. Associated settings: * |g:vimtex_view_skim_activate| * |g:vimtex_view_skim_reading_bar| * |g:vimtex_view_skim_no_select| *vimtex-view-sumatrapdf* SumatraPDF ~ https://www.sumatrapdfreader.org/free-pdf-reader.html SumatraPDF is a PDF viewer for windows that is powerful, small, portable and starts up very fast. It supports both forward and inverse search. Configuration: >vim let g:vimtex_view_general_viewer = 'SumatraPDF' let g:vimtex_view_general_options \ = '-reuse-instance -forward-search @tex @line @pdf' For convenience, the above configuration is used by default on Windows if `SumatraPDF` is detected as executable. Inverse search must be configured under `Settings --> Options` from within SumatraPDF. Find the section `Set inverse search command-line` in the bottom and use the following viewer configuration: >bash cmd /c start /min "" vim -v --not-a-term -T dumb -c "VimtexInverseSearch %l '%f'" cmd /c start /min "" nvim --headless -c "VimtexInverseSearch %l '%f'" Inverse search is activated with a double click in the PDF file. See |vimtex-synctex-inverse-search| for more info on inverse search. Note: If you want to use SumatraPDF with VimTeX from within WSL, please read |vimtex-faq-sumatrapdf-wsl|. Note: There is a known issue with VimTeX + SumatraPDF when you use `xelatex`, where the pdf file in SumatraPDF is not refreshed after compilation. A workaround was found and posted by @Whitebeard0 here: https://github.com/lervag/vimtex/issues/1410#issuecomment-506143020 *vimtex-view-texshop* TeXShop ~ https://pages.uoregon.edu/koch/texshop/index.html TeXShop is a TeX front-end program for macOS. It provides an editor (which can be replaced by other external editors, such as vim), a front-end to call TeX-related programs that process source files, and a PDF viewer with support for syncing between source and PDF. VimTeX supports both forward and inverse searches with TeXShop. Configuration: >vim let g:vimtex_view_method = 'texshop' From TeXShop, inverse search is activated by `Command`-clicking in the viewer. Furthermore, if TeXShop's compiler front-end is used, clicking `Goto Error` in the console (keyboard shortcut `Command-Control-E`) will also activate inverse search and jump to the line containing the error in the source. To configure inverse search: 1. Adjust TeXShop's preference from a terminal: >bash defaults write TeXShop OtherEditorSync YES defaults write TeXShop UseExternalEditor -bool true < These commands only need to be run once as they modify TeXShop's preference file in `~/Library/Preferences/TeXShop.plist`, which persists through sessions. While the first preference is a hidden preference and must be set via a terminal command, the second can be toggled from within TeXShop's preferences pane. 2. Create a shell script `/usr/local/bin/othereditor` that contains a call to either Vim or neovim, i.e. one of the following lines, respectively: >bash vim -v --not-a-term -T dumb -c "VimtexInverseSearch $1 '$2'" nvim --headless -c "VimtexInverseSearch $1 '$2'" < The script must be executable: >bash chmod +x /usr/local/bin/othereditor < MacVim users should read |vimtex-faq-texshopviewer| for additional setup instructions and limitations. For more info on inverse search, please see |vimtex-synctex-inverse-search|. Associated settings: * |g:vimtex_view_texshop_activate| * |g:vimtex_view_texshop_sync| *vimtex-view-zathura* *vimtex-view-zathura-simple* Zathura ~ https://pwmt.org/projects/zathura/ Zathura is, like MuPDF, a very fast and minimalistic viewer. Compared to MuPDF, it allows more user configuration. Zathura has full support for both forward and inverse search. Zathura should be straightforward to install and use on Linux with Xorg. It should also work on macOS and WSL, but users may want to consider to use either the native Skim viewer (|vimtex-view-skim|) or Sioyek (|vimtex-view-sioyek|). The macOS users who still want to use Zathura should read |vimtex-faq-zathura-macos| or |vimtex-faq-zathura-windows-wsl|. Configuration: >vim " Main variant with xdotool let g:vimtex_view_method = 'zathura' " For simple variant without xdotool let g:vimtex_view_method = 'zathura_simple' VimTeX will start Zathura with the `-x` argument to specify the inverse search options automatically. This means that, in most cases, inverse search should work as expected without any further configuration. One may still be interested in learning how inverse-search configuration works, in which case one should read |vimtex-synctex-inverse-search|. The main variant uses `xdotool` to help avoid duplicate Zathura instances. However, in some environments, `xdotool` is not available. Here the simple variant should work well. Associated settings: * |g:vimtex_callback_progpath| * |g:vimtex_view_zathura_check_libsynctex| * |g:vimtex_view_zathura_options| Note: The interpolation variables for Zathura configuration of inverse search are `%{line}` and `%{input}`, not `%l` and `%f`. Note: Recent versions of Zathura no longer ensures synctex support. This has resulted in synctex support being dropped on some platforms, e.g. on OpenSUSE, cf. https://github.com/lervag/vimtex/issues/384. A workaround is to build Zathura from source manually. Note: Viewer handling uses window title matching. If there exists another pdf viewer with the same name as the current project pdf file, then there might be conflicts. In particular, this might affect forward/inverse searching for Zathura. ------------------------------------------------------------------------------ SYNCTEX SUPPORT *vimtex-synctex* Synctex is a tool that enables synchronization of the text editor position and the pdf viewer position. The tool may be used to add mappings in vim to go to the current position in the compiled pdf document (forward search), and also to go from a specific position in the pdf file to the corresponding position in vim (inverse search). To make synctex work, it must be enabled. VimTeX enables this by default by passing `-synctex=1` on the command line, unless the user overrides the option (see the `options` key for |g:vimtex_compiler_latexmk| or |g:vimtex_compiler_latexrun|). Alternatively, for |vimtex-compiler-latexmk|, one can put this in one's `~/.latexmkrc` file: >perl $pdflatex = 'pdflatex -synctex=1 %O %S'; Forward search ~ *vimtex-synctex-forward-search* For supported viewers, |:VimtexView| (lv) will issue a forward search if the viewer is already opened. The forward search will take you to the page or position in the viewer that corresponds to the current line in your vim session. See |g:vimtex_view_method| for a list of supported viewers. Inverse search ~ *vimtex-synctex-inverse-search* *vimtex-synctex-backward-search* *:VimtexInverseSearch* In supported viewers, one may set up inverse search, which allows one to go directly from a selected line in the viewer (typically by double clicking with the mouse or something similar) to the corresponding line inside the Vim instance. This is sometimes also called backward search or reverse search. Inverse search relies on communicating with Vim/neovim from the viewer by use of shell commands executed by the viewer. It is usually configured within the specific viewer through an option named something like "inverse search command-line". The option specifies the necessary shell command to perform the inverse search. The target line and file are provided as interpolation variables. A typical shell command looks like this: >bash vim --remote-silent +%l %f Luckily, VimTeX provides a convenience function to simplify the viewer configuration. The command `VimtexInverseSearch` will execute |vimtex#view#inverse_search| with the target line and file as arguments inside the desired Vim or neovim instance. The latter function is the one that really performs the inverse search. The combined effect is a more robust experience that will seamlessly handle multiple Vim or neovim instances and multiple VimTeX instances. The user doesn't need to worry about passing the correct servernames. To configure with `VimtexInverseSearch`, use: >bash vim -v --not-a-term -T dumb -c "VimtexInverseSearch %l '%f'" nvim --headless -c "VimtexInverseSearch %l '%f'" On Windows, the above commands may lead to an annoying command window "popup". This may be avoided, or at least reduced, with the following variants: >bash cmd /c start /min "" vim -v --not-a-term -T dumb -c "VimtexInverseSearch %l '%f'" cmd /c start /min "" nvim --headless -c "VimtexInverseSearch %l '%f'" Note: In the above, we used `%l` and `%f`. However, the interpolation variables may be named different in some viewers. The correct names are given for each supported viewer (see e.g. |vimtex-view-skim|). Note: Vim users should be aware that one may need to ensure that the server is really running, see |vimtex-clientserver|. Note: Many plugin managers provide mechanisms to lazy load plugins. There is no need to use such a mechanism for VimTeX, and in fact, doing it will prevent Vim/neovim from loading the `:VimtexInverseSearch` command. Note: You may need to add the installation prefix for Vim/Neovim, for example `/opt/homebrew/bin`, in your PDF viewer if inverse search does not work. ============================================================================== LATEX DOCUMENTATION *vimtex-latexdoc* VimTeX provides the command |:VimtexDocPackage| to open documentation for packages and documentclasses. The command is mapped to `K` by default. For simplicity, the standard method provided by VimTeX is to look up documentation online through http://texdoc.net/. However, this can be customized with the option |g:vimtex_doc_handlers|. The option allows much flexibility for advanced users. For users that want to use a local `texdoc` installation as the main method, they may use the following config: >vim let g:vimtex_doc_handlers = ['vimtex#doc#handlers#texdoc'] < See https://www.tug.org/texdoc/doc/texdoc.pdf for more info about `texdoc`. Associated settings: * |g:vimtex_doc_enabled| * |g:vimtex_doc_confirm_single| * |g:vimtex_doc_handlers| In the following, I list some relevant online and offline alternatives for accessing LaTeX documentation. Please note that these methods are not integrated into VimTeX and are listed purely for the readers convenience. ------------------------------------------------------------------------------ ONLINE *vimtex-latexdoc-online* I recommend the LaTeX Wikibook [0] as a good source of documentation for LaTeX. One should also know about the Comprehensive TeX Archive Network, or CTAN [1], which is the central place for all kinds of material around TeX. The long-existing unofficial LaTeX(2e) reference manual (latexref) can be found online at [2]. [0]: https://en.wikibooks.org/wiki/LaTeX [1]: https://ctan.org/ [2]: https://latexref.xyz/ ------------------------------------------------------------------------------ OFFLINE *vimtex-latexdoc-offline* One may use a more dedicated offline documentation system. On macOS, Dash [0] is a non-free but high-quality system. On Linux, one may use Zeal [1] or dasht [2], both of which access the Dash documentation sets. Zeal should also work well on Windows. The above systems may be accessed from vim through dash.vim [3], zeavim.vim [4] or vim-dasht [5], respectively. Other alternative vim plugins include investigate.vim [6]. The unofficial LaTeX(2e) reference manual (latexref) should also be mentioned, since it may be easily downloaded in various formats from [7]. [0]: https://kapeli.com/dash [1]: https://zealdocs.org/ [2]: https://github.com/sunaku/dasht [3]: https://github.com/rizzatti/dash.vim [4]: https://github.com/sunaku/vim-dasht [5]: https://github.com/KabbAmine/zeavim.vim [6]: https://github.com/keith/investigate.vim [7]: https://latexref.xyz/dev/ ============================================================================== CONTEXT MENU *vimtex-context-menu* VimTeX provides the command |:VimtexContextMenu| to open a context menu for the item below the cursor. The menu allows various actions relevant to the current context. It is mapped by default to `la`. The available contexts are listed below. Associated settings: * |g:vimtex_context_pdf_viewer| ------------------------------------------------------------------------------ CITATION CONTEXT *vimtex-context-citation* When the cursor is over a citations, e.g. `\textcite{myRef}`, then the context menu will show choices relevant to the current citation entry. This works by parsing the relevant `bib` file for metadata and providing menu actions depending on the available metadata. The actions are only displayed when they are relevant. Possible actions: Edit entry ~ Go to the entry location in the relevant bib file. Show entry ~ Show the registered data for the current entry. Open PDF ~ Open associated PDF file from the `file` key of the bib entry. Open DOI ~ Open associated DOI url from the `doi` key of the bib entry. Open URL ~ Open associated URL from the `url` key of the bib entry. ============================================================================== CODE STRUCTURE *vimtex-code* The VimTeX code is based on the |autoload| feature of vim. For each new latex buffer, the function *vimtex#init* initializes a state variable as well as buffer local mappings and commands, all based on the desired options (see |vimtex-options|). The main init function calls `vimtex#mymodule#init_buffer` for each submodule, if it exists. This function should take care of defining buffer local mappings, commands, and autocommands. The state variable is a |Dictionary| that contains data that is specific to a single LaTeX project. Such a project may consist of several buffers for different files if the project is a multi-file project (see |vimtex-multi-file|). A submodule may add to the state during initialization with `vimtex#mymodule#init_state`, which takes the state object as a single argument. The command |:VimtexInfo| (mapped to li by default) will show the (relevant) contents of the local state, as well as some auxiliary information that may be useful for debugging purposes. See also the supplementary high-level code documentation [0] for more detailed information about the VimTeX code. [0]: https://github.com/lervag/vimtex/blob/master/DOCUMENTATION.md ------------------------------------------------------------------------------ API REFERENCE *vimtex-code-api* This is an API reference of the most useful VimTeX functions available to users for customization. Note: This reference is currently a work in progress! *vimtex#cite#get_entry* Returns a citation entry. It takes an option `key` argument. If a `key` is supplied, then the corresponding bib entry for that key is returned (a |Dict|). Else it returns the entry for the key under the cursor. If no key is found, an empty |Dict| is returned. *vimtex#cite#get_key* Returns the citation key under the cursor. Can be useful e.g. to create a function to open a citation in another progrem such as BibDesk or Zotero. For example: >vim function! OpenInBibDesk() abort let l:key = vimtex#cite#get_key() if empty(l:key) | return | endif call vimtex#util#www('x-bdsk://' .. vimtex#util#url_encode(l:key)) endfunction *vimtex#compiler#callback* Utility function to be used as a compiler callback function. Takes a single argument, which is the compiler status: 1: Compilation cycle has started 2: Compilation complete - Success 3: Compilation complete - Failed The function does several useful things based on the status, such as running the |VimtexEventCompiling|, |VimtexEventCompileFailed| and |VimtexEventCompileSuccess| events. *vimtex#env#get_inner* *vimtex#env#get_outer* *vimtex#env#get_all* Functions that return the surrounding inner or outer environment, or all surrounding environments. The return value is a dictionary with the following keys: `name`: The environment name `open`: The environment opening delimiter object `close`: The environment closing delimiter object The delimiter objects contain information about the locations and arguments of the corresponding `\begin{...}[...]` and `\end{...}` commands. *vimtex#env#is_inside* A function that returns the start position of the `\begin{environment}` of the environment name that was passed as the only mandatory argument. That is, the return value is a list of two numbers: The line number and the column number. These are both 0 if no surrounding environment was found. *vimtex#syntax#in* `vimtex#syntax#in(name)` -> |Boolean| `vimtex#syntax#in(name, line, column)` -> |Boolean| Returns |v:true| if the cursor position or the specified position is inside the `name`d group. `name` is a regex that is used to matched against the syntax group stack. *vimtex#syntax#in_mathzone* `vimtex#syntax#in_mathzone()` -> |Boolean| `vimtex#syntax#in_mathzone(line, column)` -> |Boolean| Returns |v:true| if the cursor position or the specified position is inside a math zone. *vimtex#view#inverse_search* Utility function for reverse search from pdf viewer. Takes two arguments: the line number and a filename. The function runs the event |VimtexEventViewReverse| at the end, which allows more user customization. ============================================================================== FAQ *vimtex-faq* This is a section of some frequently asked questions whose answers may be of help to users. Contents: * |vimtex-faq-windows| * |vimtex-faq-neovim| * |vimtex-faq-slow-matchparen| * |vimtex-faq-surround| * |vimtex-faq-isfname| * |vimtex-faq-tags| * |vimtex-faq-tags-bibtex| * |vimtex-faq-texmfhome| * |vimtex-faq-wsl| * |vimtex-faq-sumatrapdf-wsl| * |vimtex-faq-zathura-macos| * |vimtex-faq-zathura-windows-wsl| * |vimtex-faq-texshopviewer| * |vimtex-faq-treesitter| ------------------------------------------------------------------------------ *vimtex-faq-windows* Q: Does VimTeX support Windows? A: Yes. But there are some "gotchas": * It is highly recommended to install a dedicated Perl distribution (e.g. Strawberry Perl [0]). * Several features rely on having executables like `latexmk` and `SumatraPDF.exe` "readily available" by adding the parent directories of the executables to your PATH environment variable. See [1] for more info on PATH. * VimTeX does not work well with the 'shell' setting set to Windows PowerShell. It is therefore recommended to use the default 'shell' settings. See [2] for more information. * |:VimtexInfo| might fail on the first attempt to run because Windows doesn't natively support UTF-8. This support can be enabled by [3]: - navigating to `Control Panel/Clock and Region/Region`, - going to the `Administrative` tab and clicking on the `Change system locale` button, - checking the box for `Use Unicode UTF-8 for worldwide language support`. Note that this Windows feature is still in Beta and could cause side effects on other programs. Use it with care and revert the process if you encounter more trouble. [0]: https://strawberryperl.com/ [1]: https://www.rapidee.com/en/path-variable [2]: https://github.com/lervag/vimtex/issues/1507 [3]: https://github.com/lervag/vimtex/issues/2671 ------------------------------------------------------------------------------ *vimtex-faq-neovim* Q: Does VimTeX support neovim? A: Yes, but some people may complain that VimTeX is not written in Lua! ------------------------------------------------------------------------------ *vimtex-faq-slow-matchparen* Q: Why is matching parens so slow? A: Because it is complicated and requires some expensive searches for matching parentheses. It uses the syntax information to skip commented delimiters, which is expensive. You can tune the timeout and stopline parameters for the searches with |g:vimtex_delim_timeout| and |g:vimtex_delim_stopline|, which may help. If it is still too slow, you can also try to use vim-matchup [0], see also |vimtex-af-enhanced-matchparen|. [0]: https://github.com/andymass/vim-matchup ------------------------------------------------------------------------------ *vimtex-faq-surround* Q: VimTeX provides `dse`, `dsc`, `cse`, and `csc`. These seem to be inspired by |surround.vim|. Does VimTeX also provide the corresponding `yse` and `ysc`? A: The mentioned mappings are indeed inspired by |surround.vim|. However, VimTeX does not provide `yse` and `ysc`. If you use |surround.vim|, then the asked for mappings may be easily added if one adds the following lines to `~/.vim/after/ftplugin/tex.vim` or any other `ftplugin/tex.vim` in your |runtimepath|: >vim let b:surround_{char2nr('e')} \ = "\\begin{\1environment: \1}\n\t\r\n\\end{\1\1}" let b:surround_{char2nr('c')} = "\\\1command: \1{\r}" < Remark also that, by default, |surround.vim| already provides the mapping `ysl` for encapsulating a text object in a LaTeX environment. Note: Please also read the section |vimtex-af-surround|! Note: An alternative is to use `vim-sandwich` (see |sandwich.txt| or https://github.com/machakann/vim-sandwich), which has built-in support for LaTeX-specific surroundings. ------------------------------------------------------------------------------ *vimtex-faq-isfname* Q: Vim throws error when jumping to file with |gf|. A: This might be due to the |isfname| setting, which by default contains `{,}` on windows. |isfname| is a global option, and can therefore not be set by VimTeX. Suggested solution is to remove `{,}` from |isfname| by: >vim set isfname-={,} < ------------------------------------------------------------------------------ *vimtex-faq-tags* Q: How can I jump from a `\ref{label}` to the corresponding label? A: This is not a feature provided by VimTeX itself, but vim has very good support for tag navigation, see |tags-and-searches|. It is worth mentioning that the |ctags| support for LaTeX is somewhat lacking. This can be amended by adding some lines to your `~/.ctags` configuration file (or `.ctags.d/default.ctags` if you use Universal ctags), e.g.: > --langdef=tex2 --langmap=tex2:.tex --regex-tex2=/\\label[ \t]*\*?\{[ \t]*([^}]*)\}/\1/l,label/ < See [0,1] for references. I also find |gutentags| [2] to be very convenient for automatically generating and updating tag files. [0]: http://stackoverflow.com/q/8119405/51634 [1]: https://github.com/lervag/vimtex/issues/348 [2]: https://github.com/ludovicchabant/vim-gutentags ------------------------------------------------------------------------------ *vimtex-faq-tags-bibtex* Q: How can I jump from a `\cite{key}` to the corresponding bibtex entry? A: This is not a feature provided by VimTeX itself. Similar to |vimtex-faq-tags|, the feature is available through |tags-and-searches|. The following `~/.ctags` configuration will be useful (or `.ctags.d/default.ctags` if you use Universal ctags): > --langdef=bib --langmap=bib:.bib --regex-bib=/^@[A-Za-z]+\{([^,]+),/\1/e,entry/i --regex-bib=/^@article\{([^,]*)/\1/a,article/i --regex-bib=/^@book\{([^,]*)/\1/b,book/i --regex-bib=/^@booklet\{([^,]*)/\1/L,booklet/i --regex-bib=/^@conference\{([^,]*)/\1/c,conference/i --regex-bib=/^@inbook\{([^,]*)/\1/B,inbook/i --regex-bib=/^@incollection\{([^,]*)/\1/C,incollection/i --regex-bib=/^@inproceedings\{([^,]*)/\1/P,inproceedings/i --regex-bib=/^@manual\{([^,]*)/\1/m,manual/i --regex-bib=/^@mastersthesis\{([^,]*)/\1/T,mastersthesis/i --regex-bib=/^@misc\{([^,]*)/\1/M,misc/i --regex-bib=/^@phdthesis\{([^,]*)/\1/t,phdthesis/i --regex-bib=/^@proceedings\{([^,]*)/\1/p,proceedings/i --regex-bib=/^@string\{([^ "#%')(,=}{]+)/\1/s,string/i --regex-bib=/^@techreport\{([^,]*)/\1/r,techreport/i --regex-bib=/^@unpublished\{([^,]*)/\1/u,unpublished/i ------------------------------------------------------------------------------ *vimtex-faq-texmfhome* Q: How can I change `TEXMFHOME`? A: If you change `TEXMFHOME` in your `.bashrc` or `.zshrc` or similar and use `gvim` invoked from the desktop environment (from menus, hotkeys, etc.), gvim does not know about the new value of `TEXMFHOME`. The reason for this is that `vim` invokes shells (e.g. with `!` or `system()`) as non-interactive and non-login shell, which means `.bashrc` or `.zshrc` are not read. If you start `gvim` from an interactive shell which has read `.bashrc` or `.zshrc, `gvim` inherits these values and therefore they are consistent. One can make the invoked shells interactive by setting |shellcmdflag| to "-ic". If you want to keep them non-interactive, you can create an additional shell startup file where you keep your environment variables: 1. If bash is your default shell, create e.g. the file `.bashenv` containing your customized `TEXMFHOME` variable and add `$BASH_ENV=$HOME/.bashenv` to `$MYVIMRC` and `source $HOME/.bashenv` to `.bashrc` [0]. 2. If zsh is your default shell, use `.zshenv` for customizing `TEXMFHOME`. This file is always read by zsh. Nothing has to be added to `$MYVIMRC` [1]. For more information on how to correctly set environment variables, see e.g. the SO answer by @Rmano [2]. [0]: https://www.gnu.org/software/bash/manual/html_node/Bash-Startup-Files.html [1]: http://zsh.sourceforge.net/Intro/intro_3.html [2]: http://askubuntu.com/a/356973/16395 ------------------------------------------------------------------------------ *vimtex-faq-wsl* Q: Does VimTeX support WSL (the Windows Subsystem for Linux)? A: For the moment, rudimentarily, as follows: To set up the viewer, install Sioyek [0], MuPDF [1], or SumatraPDF [2], add the executable to `%PATH%`, say by Rapidee [3]. In your vimrc, the lines >vim if has('win32') || (has('unix') && exists('$WSLENV')) if executable('sioyek.exe') let g:vimtex_view_method = 'sioyek' let g:vimtex_view_sioyek_exe = 'sioyek.exe' let g:vimtex_callback_progpath = 'wsl nvim' elseif executable('mupdf.exe') let g:vimtex_view_general_viewer = 'mupdf.exe' elseif executable('SumatraPDF.exe') let g:vimtex_view_general_viewer = 'SumatraPDF.exe' endif endif < make |:VimtexView| work under Windows, and also under WSL, provided that at least Windows 10 version 1903 [4] of WSL is installed, the current work dir and the compiled file is contained in the Linux home directory `$HOME` (as opposed to `%USERPROFILE%` in Windows). With this configuration, both forward and inverse search should work with Sioyek and neovim. However, forward search does not work for SumatraPDF. It seems that, while SumatraPDF is able to find the PDF file in `\\wsl$\\...`, the corresponding source file in `\\wsl$\\...` is not available. To set up a LaTeX distribution, while reusing that of Windows as proposed at [5] seems efficient, in practice accessing files on mounted NTFS drives from WSL is slow, even more so under WSL2 [6]. Therefore a full TeXLive installation is recommended. If only basic functionality is required, then a minimal TeXLive installation, such as TinyTeX [7] or a minimal set of packages to compile LaTeX as provided by your distribution, is an option, as discussed at [8]. For example, under openSUSE, it suffices to install the packages texlive-scheme-basic, texlive-latexmk, texlive-collection-fontsrecommended. [0]: https://sioyek.info/ [1]: https://chocolatey.org/packages/mupdf [2]: https://chocolatey.org/packages/sumatrapdf [3]: https://www.rapidee.com/en/about [4]: https://devblogs.microsoft.com/commandline/whats-new-for-wsl-in-windows-10-version-1903/ [5]: https://github.com/lervag/vimtex/issues/1380 [6]: https://vxlabs.com/2019/12/06/wsl2-io-measurements/ [7]: https://yihui.org/tinytex/ [8]: https://tex.stackexchange.com/questions/397174/minimal-texlive-installation ------------------------------------------------------------------------------ *vimtex-faq-sumatrapdf-wsl* Q: Does VimTeX work with SumatraPDF from within WSL (the Windows Subsystem for Linux)? A: SumatraPDF expects all path arguments to be in the regular Windows format, for instance `C:\Path\To\file.pdf`. When you work in WSL you will typically work in a Bash shell where the corresponding path would be `/mnt/c/Path/To/file.pdf`. This means SumatraPDF will not work with VimTeX inside WSL without some adjustments. Luckily, there is a CLI tool `wslpath` that can be used to translate these paths. This means we can make VimTeX work with SumatraPDF from within WSL by writing a simple wrapper script for SumatraPDF and using it instead. Essentially, we will achieve most of the functionality we expected, except backward search from SumatraPDF to VimTeX. That may also be possible, but it is currently uncharted territory. First, create a script called `sumatrapdf.sh` and put it under `~/.local/bin` inside your WSL environment. You may copy the script provided by @Liampor on GitHub [0] or write something similar on your own. The main idea is to let the wrapper of the script do two things: 1. Convert all paths to Windows style paths with `wslpath`. 2. Update the Synctex file (`*.synctex.gz` ) correspondingly to allow forward search. Now, configure the viewer like this: >vim let g:vimtex_view_general_viewer = '~/.local/bin/sumatrapdf.sh' let g:vimtex_view_general_options \ = '-reuse-instance -forward-search @tex @line @pdf' < [0]: https://github.com/lervag/vimtex/issues/2566#issuecomment-1322886643 ------------------------------------------------------------------------------ *vimtex-faq-zathura-macos* Q: Does Zathura + VimTeX work on macOS? A: Yes, it should work. The following recipe has been reported to work [0], although users with Apple Silicon CPUs have reported difficulties starting `dbus`. These users may want to try the more involved recipe given in [3] if the below procedure fails. The steps assume the user has installed and knows how to use Homebrew [1]. 1. Zathura needs `dbus` to work properly. Install it with the following: `brew install dbus`, or, if it is already installed, reinstall (this seems necessary for some unknown reason): `brew reinstall dbus` 2. The `DBUS_SESSION_BUS_ADDRESS` environment variable must be set for Zathura to work with VimTeX; see [2] for details. This can be done by adding the following to your `.bashrc` or `.zshrc` file (or similar): > export DBUS_SESSION_BUS_ADDRESS="unix:path=$DBUS_LAUNCHD_SESSION_BUS_SOCKET" < 3. Changed the value of `<\auth>` in `/usr/local/opt/dbus/share/dbus-1/session.conf` from `EXTERNAL` to `DBUS_COOKIE_SHA1`. 4. Run `brew services start dbus`, and use `brew services info dbus` to double-check that `dbus` is running. Apple Silicon users that encounter problems at this step should try the recipe in [3]. Also, if the user encounter problems with running `dbus` with `brew services start`, they could try to start it manually as explained in [4]. 5. Now install Zathura (most recent version, aka HEAD): > brew tap zegervdv/zathura brew install girara --HEAD brew install zathura --HEAD --with-synctex brew install zathura-pdf-poppler mkdir -p $(brew --prefix zathura)/lib/zathura ln -s $(brew --prefix zathura-pdf-poppler)/libpdf-poppler.dylib $(brew --prefix zathura)/lib/zathura/libpdf-poppler.dylib < 6. Reboot and enjoy. Note: If you already had Zathura and girara installed and things don't work, then first uninstall and unlink them and try to follow the above steps from step 1. [0]: https://github.com/lervag/vimtex/issues/1737#issuecomment-759953886 [1]: https://brew.sh [2]: https://github.com/lervag/vimtex/issues/2391#issuecomment-1127678531 [3]: https://github.com/zegervdv/homebrew-zathura/issues/99 [4]: https://github.com/lervag/vimtex/issues/2889#issuecomment-1974827512 ------------------------------------------------------------------------------ *vimtex-faq-zathura-windows-wsl* Q: Does Zathura + VimTeX work on WSL2? A: Yes, but `systemd` or `D-Bus` must be enabled to make inverse search work properly. 1. `systemd` is the default for Ubuntu 23.04 running on WSL 2. In this case, there is nothing to do: Zathura and VimTeX should work fine. 2. Otherwise, if WSL version is 0.67.6 or newer, enable `systemd` by adding the following content to the config file `/etc/wsl.conf` (create the file if it doesn't exist). >conf [boot] systemd=true < Then close WSL by using the command `wsl.exe --shutdown` in PowerShell to restart all WSL instances [0]. 3. Another approach which also works with older version of WSL consists in setting up `D-Bus` daemons that can be shared in all your WSL consoles. These steps are described in [1]. [0]: https://learn.microsoft.com/en-us/windows/wsl/systemd [1]: https://x410.dev/cookbook/wsl/sharing-dbus-among-wsl2-consoles/ ------------------------------------------------------------------------------ *vimtex-faq-treesitter* Q: How does VimTeX compare to Tree-sitter? A: VimTeX implements a traditional syntax script for syntax highlighting of LaTeX documents (see |syntax.txt|). The implementation is quite complete and has support for a lot of packages. It should work well for most people. See |vimtex-syntax| for detailed information. Tree-sitter [0] is a modern library for incremental parsing of code. Neovim has built-in support for Tree-sitter (see |treesitter|). With the additional Tree-sitter plugin [1], one can have syntax highlighting based on the Tree-sitter parser. The general benefit of this is that it should be very fast, and that, for a lot of languages, it can provide high quality results. However, it is hard to write a general parser for LaTeX. This is because LaTeX is a semantic language with a large amount of different commands and macros from thousands of available packages, many of which makes sense to highlight in a different manner. That is, we need to handle a whole lot of special cases and edge cases! Furthermore, Tree-sitter highlighting does not currently support concealing, which many people find useful (see |vimtex-syntax-conceal|). Finally, some features of VimTeX relies on the VimTeX syntax highlighting to work. Examples include the math text objects (e.g. |(vimtex-a$)| and |(vimtex-i$)|) as these text objects check the syntax groups to determine a math region. Thus, for people who use Tree-sitter, it is strongly advised to disable Tree-sitter highlighting for LaTeX buffers. This can be done with the `ignore_install` option for the setup part of `nvim-treesitter`, e.g.: >lua require 'nvim-treesitter.configs'.setup { ignore_install = { "latex" }, -- more stuff here } < Or, alternatively, to only disable the highlighting: >lua require 'nvim-treesitter.configs'.setup { highlight = { enable = true, disable = { "latex" }, }, -- more stuff here } < Of course, some people may still want to use Tree-sitter for highlighting regardless of the arguments raised above. In this case, it is advised to use these options for VimTeX to avoid the startup warning: >vim let g:vimtex_syntax_enabled = 0 let g:vimtex_syntax_conceal_disable = 1 < Q: Can I use VimTeX with Markdown plugins that need Tree-sitter enabled? A: Yes, it is possible by using the "additional_vim_regex_highlighting" option in the `nvim-treesitter` setup (|nvim-treesitter-highlight-mod|), e.g.: >lua require 'nvim-treesitter.configs'.setup { ensure_installed = { "markdown" }, highlight = { enable = true, disable = { "latex" }, additional_vim_regex_highlighting = { "latex", "markdown" }, }, --other treesitter settings } < Be warned, though, that this will run both Tree-sitter and regex highlighting in parallel. This negates any performance benefit, and it can possibly lead to weird results since both types of highlighting are applied, one over the other. [0]: https://tree-sitter.github.io/tree-sitter/ [1]: https://github.com/nvim-treesitter/nvim-treesitter [2]: https://github.com/nvim-treesitter/nvim-treesitter#available-modules ------------------------------------------------------------------------------ *vimtex-faq-texshopviewer* Q: How do I set up VimTeX to work with TeXShop and MacVim (macOS)? A: Start by reading the section on |vimtex-view-texshop|. The examples below apply to MacVim [0]. Here is an example `/usr/local/bin/othereditor` script that uses the VimTeX's convenience function `VimtexInverseSearch`: >bash #!/bin/bash /usr/local/bin/mvim -v --not-a-term -T dumb -c "VimtexInverseSearch $1 '$2'" < The call with the convenience function `VimtexInverseSearch` offers the advantage that the buffer will be found if it is open, regardless of how it was opened. If the buffer is not active, in a hidden tab or if the file is not open at all, inverse search will fail. As alternative, to `VimtexInverseSearch`if the .tex document was opened with the `--remote-silent` option, i.e.: >bash /usr/local/bin/mvim --remote-silent foo.tex < the following script `/usr/local/bin/othereditor` can be used instead: >bash #!/bin/bash /usr/local/bin/mvim --remote-silent +$1 "$2" < It will activate the buffer even if it is hidden, or open the file if it is not yet loaded in any buffer. The TeXShop release notes for versions 4.24 and 4.25 contain information about backward searches with external editors in general [1]. [0]: https://macvim-dev.github.io/macvim/ [1]: https://pages.uoregon.edu/koch/texshop/changes_3.html ============================================================================== TROUBLESHOOTING *vimtex-troubleshooting* Here are some pitfalls that one may experience if one of these assumptions are broken: - Completion may not work properly for exotic file encodings, such as for UTF-16LE (see https://github.com/lervag/vimtex/issues/615) With different operating systems and different plugin configurations, there are a few things that must be considered for system interoperability. A number of common problems and suggested solutions are included in the following troubleshooting section. Problem: Continuous compilation seems to hang ~ Upon starting continuous compilation the status bar indicates "VimTeX: Compiler started in continuous mode", but the compilation never terminates and the quickfix window does not load. Tips: 1. Ensure that a latexmk process and a Perl process have started. If they have not been started, then these two programs may not accessible given your operating system's PATH environment variable. 2. Ensure that the option `-interaction=nonstopmode` is provided to latexmk. This is done by default by VimTeX, unless the user provides custom options through |g:vimtex_compiler_latexmk| (see the `options` key). In the latter case, the user must ensure that the said option is also provided. Problem: Text objects on Windows ~ In Windows, environment text object commands, like `vae` and `vie`, do not select the entire body of the environment. More specifically, given: >latex \begin{someenv} some content \end{someenv} The command `dae` results in: > } and `die` results in: >latex \begin{someenv} t \end{someenv} Solution: It seems that vim for Windows comes with some options set by default in the vimrc file. One of these has been reported to be `:behave mswin` (see |:behave|) which, among other things, sets the 'selection' option to "exclusive". This can be ameliorated by pursuing one of two options: 1. Add `:behave xterm` to your vimrc file. 2. Add `:set selection=inclusive` to your vimrc file. See also: https://github.com/lervag/vimtex/issues/408 Problem: Typing or causes Vim to hang before making a completion ~ VimTeX may be scanning included files with `kpsewhich` while collecting completion candidates for keyword completion. Try disabling this feature by setting |g:vimtex_include_search_enabled| to 0 in your |vimrc|: >vim let g:vimtex_include_search_enabled = 0 Note: Plugins like |supertab| [0], which often maps the |i_| key, will typically use keyword completion "behind the scenes" to gather completion candidates. [0]: https://github.com/ervandew/supertab ============================================================================== CREDITS *vimtex-credits* VimTeX is developed by Karl Yngve Lervåg , and is distributed under the MIT license. The project is available as a Git repository: https://github.com/lervag/vimtex. VimTeX was developed from scratch, but much of the code has been based on LaTeX-Box: https://github.com/LaTeX-Box-Team/LaTeX-Box. LaTeX-suite was also an inspiration: http://vim-latex.sourceforge.net/. I do accept donations through PayPal (see link below [0]). As there are no expenses related to VimTeX (except time), any money I receive would be spent on coffee, beer or chocolate. These things make me happy. However, I will also be happy if one should choose to donate to a charity instead, as there are a lot of people in more need of money than me! Examples of charities may be |ICCF| (the organisation that Vim specifically supports) or Medicins sans Frontieres [1]. Feel free to let me know if you should donate to a charity due to VimTeX, as I would be happy to hear of it. [0]: https://www.paypal.com/cgi-bin/webscr?cmd=_s-xclick&hosted_button_id=5N4MFVXN7U8NW [1]: https://www.msf.org/ ============================================================================== CHANGELOG *vimtex-changelog* The following changelog only logs particularly important changes, such as changes that break backwards compatibility. See the git log for the detailed changelog. 2022-11-06: Better main file detection algorithm ~ The detection whether a file is a main file has seen gradual improvements. In course of this, *g:vimtex_disable_recursive_main_file_detection* has been removed. 2021-10-25: Better inverse search ~ Deprecate *g:vimtex_compiler_progname* as it is no longer necessary. 2021-10-09: Better options for syntax conceal ~ Deprecate *g:vimtex_syntax_conceal_default* in favor of |g:vimtex_syntax_conceal_disable|. The new option makes things more explicit and makes better sense (at least to me). 2020-11-16: More flexible package syntax options ~ Deprecate *g:vimtex_syntax_autoload_packages* in favor of |g:vimtex_syntax_packages|, which allows more fine grained control over each package. 2020-09-24: More concise grammar options ~ Deprecate *g:vimtex_textidote_jar* in favor of |g:vimtex_grammar_textidote|. 2020-08-11: Remove g:vimtex_quickfix_latexlog ~ The option *g:vimtex_quickfix_latexlog* was deprecated in favor of the more general mechanism provided by |g:vimtex_quickfix_ignore_filters|. 2020-07-31: Use events for callback hooks ~ The events |VimtexEventCompileSuccess|, |VimtexEventCompileFailed|, and |VimtexEventView| have been added to make it easier to hook personal customizations. This deprecates the following options: * *g:vimtex_compiler_callback_hooks* * *g:vimtex_view_general_callback* * *g:vimtex_view_general_hook_callback* * *g:vimtex_view_general_hook_view* * *g:vimtex_view_mupdf_hook_callback* * *g:vimtex_view_mupdf_hook_view* * *g:vimtex_view_skim_hook_callback* * *g:vimtex_view_skim_hook_view* * *g:vimtex_view_zathura_hook_callback* * *g:vimtex_view_zathura_hook_view* 2020-07-19: Released version 1.0 ~ Version 1.0 (and earlier) works on Vim 7.4 and with neovim 0.1.7. Later versions require Vim 8.0 or neovim 0.4.3. 2018-08-15: Refactored the ToC interface ~ I've made a large update to the code for the ToC window in order to simplify and unify the interface. In the new version, |g:vimtex_toc_config| replaces all of the following options: * *g:vimtex_index_split_width* * *g:vimtex_index_split_pos* * *g:vimtex_index_show_help* * *g:vimtex_index_resize* * *g:vimtex_index_hide_line_numbers* * *g:vimtex_index_mode* * *g:vimtex_toc_layers* * *g:vimtex_toc_fold* * *g:vimtex_toc_fold_level_start* * *g:vimtex_toc_hotkeys* * *g:vimtex_toc_refresh_always* * *g:vimtex_toc_show_numbers* * *g:vimtex_toc_tocdepth* 2017-07-27: Major refactoring of the folding feature ~ I've made a large update to the code for folding. The configuration of the various folded elements is now done through a single option: |g:vimtex_fold_types|. Deprecated options: * *g:vimtex_fold_comments* * *g:vimtex_fold_preamble* * *g:vimtex_fold_envs* * *g:vimtex_fold_env_blacklist* * *g:vimtex_fold_env_whitelist* * *g:vimtex_fold_markers* * *g:vimtex_fold_parts* * *g:vimtex_fold_sections* * *g:vimtex_fold_commands* * *g:vimtex_fold_commands_default* *vimtex-lacheck* 2017-06-05: Removed Lacheck support ~ Removed support for using `lacheck` for checking LaTeX syntax. The reason is that there exist several (good) external plugins for syntax checking files. These are general purpose plugins that work for multiple file types. For more info, see |vimtex-and-friends|. 2017-05-20: Updated TOC options ~ There's been a few updates to the TOC. During this work, I removed some unnecessary options. Deprecated options: * *g:vimtex_toc_fold_levels* (was not necessary) * *g:vimtex_toc_number_width* (see |g:vimtex_toc_tocdepth|) 2017-03-31: Refactored quickfix related features ~ I've added a more general layer for handling different error parsers. Currently there are few or now changes from the user point of view, but this should make it possible to add other methods for showing errors in a LaTeX project than the current one that parses the `.log` file directly. Deprecated options: * *g:vimtex_quickfix_warnings* (see |g:vimtex_quickfix_latexlog|) 2017-03-28: Major refactoring of initialization ~ Added a general compiler interface, see |vimtex-compiler|. To configure the `latexmk` compiler, see |g:vimtex_compiler_latexmk|. Deprecated options: * *g:vimtex_latexmk_enabled* (use |g:vimtex_compiler_enabled|) * *g:vimtex_latexmk_progname* (use |g:vimtex_compiler_progname|) * *g:vimtex_latexmk_callback_hooks* (use |g:vimtex_compiler_callback_hooks|) * *g:vimtex_latexmk_callback* * *g:vimtex_latexmk_autojump* * *g:vimtex_latexmk_continuous* * *g:vimtex_latexmk_background* * *g:vimtex_latexmk_options* Deprecated commands: * *VimtexCompileToggle* (use |:VimtexCompile|) 2017-03-28: Major refactoring of initialization ~ The initialization has been refactored in order to provide a more consistent separation of buffer initialization and state initialization. This has no major consequence for users, but it makes maintenance and further development easier. 2017-03-02: Changed how to set ignored warnings ~ I'm updating the changelog to notify of a change to the quickfix settings. Deprecated options: * *g:vimtex_quickfix_ignore_all_warnings* * *g:vimtex_quickfix_ignored_warnings* See instead: |g:vimtex_quickfix_warnings| 2016-05-31: A lot of things have updated ~ I know that people would like to see a simple list of changes. Unfortunately, I am bad at keeping this changelog updated. All details are available in the git log, though. The reason I added this entry is to note that I have removed an option: * *g:vimtex_env_complete_list* --- It is no longer necessary. Completion candidates are instead parsed from the project. 2016-02-06: Large refactoring of delimiter parsing ~ I've refactored a lot of the code in order to make the parsing of delimiters and features that rely on delimiter detection and similar more consistent. This results in some changes in option names and similar, but it should make it easier to provide improved and more robust features. There is one feature change: The delimiter toggle now consistently toggles the modifier, not the delimiter itself, and it toggles between a range of modifiers by default. For customization, see |g:vimtex_delim_toggle_mod_list|. The following options have changed names: * *g:vimtex_change_set_formatexpr* ---> |g:vimtex_format_enabled| * *g:vimtex_change_complete_envs* ---> |g:vimtex_env_complete_list| * *g:vimtex_change_toggled_delims* ---> |g:vimtex_delim_toggle_mod_list| The following options have been removed: * *g:vimtex_change_ignored_delims_pattern* --- It was no longer necessary The following mappings have been renamed: * *(vimtex-delete-env)* ---> |(vimtex-env-delete)| * *(vimtex-delete-cmd)* ---> |(vimtex-cmd-delete)| * *(vimtex-change-env)* ---> |(vimtex-env-change)| * *(vimtex-change-cmd)* ---> |(vimtex-cmd-change)| * *(vimtex-toggle-star)* ---> |(vimtex-env-toggle-star)| * *(vimtex-toggle-delim)* ---> |(vimtex-delim-toggle-modifier)| * *(vimtex-create-cmd)* ---> |(vimtex-cmd-create)| * *(vimtex-close-env)* ---> |(vimtex-delim-close)| 2015-10-19: Added convenient insert mode mappings ~ I've merged the `math_mappings` branch (see #172 and #251). It adds the feature that is explained in |vimtex-imaps|. 2015-06-06: Minor but convenient restructuring (++) ~ I've changed a lot of the code structure in relatively small ways. For instance, instead of referring to the particular data blobs through the global array, I instead linked a buffer variable to the correct global array element. One particular change is that all modules are now initialized in three steps: 1. Initialize module options 2. Initialize script variables and single execution functionalities 3. Initialize buffer options Finally, I've cleaned up a lot of the code by removing some deprecation warnings and similar. 2015-03-21: Implemented index buffers, deprecated vimtex_toc filetype ~ The system for displaying the table of content relied on a dedicated filetype plugin. This was inherited from LaTeX-Box, and worked quite well. However, I intend to implement more functionality that uses the same kind of buffer to display similar things, such as a list of labels. I realized I wanted the ToC window to be more adaptable, so I implemented the `index` interface for such buffers. The `index` in itself may be used to create ToC-like buffers with simple actions. The |vimtex-toc| uses and expands the `index` in such a way that the changes should barely be noticeable from the user perspective. Note however the following variable name changes: * *g:vimtex_toc_numbers_width* ---> |g:vimtex_toc_number_width| * *g:vimtex_toc_hide_preamble* ---> |g:vimtex_toc_show_preamble| * *g:vimtex_toc_numbers* ---> |g:vimtex_toc_show_numbers| * *g:vimtex_toc_hide_line_numbers* ---> |g:vimtex_index_hide_line_numbers| * *g:vimtex_toc_resize* ---> |g:vimtex_index_resize| * *g:vimtex_toc_hide_help* ---> |g:vimtex_index_show_help| * *g:vimtex_toc_split_pos* ---> |g:vimtex_index_split| * *g:vimtex_toc_width* -/ *vim-latex-namechange* 2015-03-08: Changed the name to VimTeX ~ The old name `vim-latex` was already used by LaTeX-Suite. I was not aware of the name clash in the beginning. Due to the rising popularity of this plugin, it has become clear that such a name clash is very inconvenient. The present change is therefore very much needed. The name change is reflected throughout the plugin in the names of commands, mappings, functions, and options. People should update their `vimrc` settings accordingly. For instance, every option name should be changed from > g:latex_... = ... to > g:vimtex_... = ... 2014-12-07: Added more general view functionality ~ Added new module for view functionality. This allows more complex view functions (and commands), for instance to do forward (and possibly inverse) searching through `synctex`. In the first version, I added forward search for mupdf by use of the `synctex` command and `xdotool`. The `g:latex_viewer` option has now been deprecated. Instead one should use |g:vimtex_view_method| and |g:vimtex_view_general_viewer|. Deprecated option: * *g:latex_viewer* 2014-06-13: Changed some option names ~ Some VimTeX option names were changed in an attempt to make the names more consistent. These options are listed here for reference: * *g:latex_errorformat_ignore_warnings* * *g:latex_errorformat_show_warnings* * *g:latex_latexmk_autojump* * *g:latex_latexmk_quickfix* The new names are, respectively: * |g:vimtex_quickfix_ignored_warnings| * |g:vimtex_quickfix_ignore_all_warnings| * |g:vimtex_quickfix_autojump| * |g:vimtex_quickfix_mode| 2013-10-05: First public release ~ VimTeX was first released on github on this date. The initial version was named vim-latex, which conflicted with Vim LaTeX-Suite which is also known as vim-latex. ============================================================================== vim:tw=78:ts=8:ft=help:norl:fdm=marker: