Visual Studio Code LaTeX Workshop Extension

LaTeX Workshop is an extension for Visual Studio Code, aiming to provide all-in-one features and utilities for LaTeX typesetting with Visual Studio Code.

One million downloads! This project won't be successful without contributions from the community, especially project maintainers Jerome Lelong @jlelong, James Booth @jabooth, and all code contributors! Thank you!

Features

Build LaTeX (including BibTeX) to PDF automatically on save (see Build on Save)
$build process gif$
View PDF on-the-fly (in VS Code or browser).
$demo of preview feature$
Direct and reverse SyncTeX. Click to jump between location in .tex source and PDF and vice versa.
$demo of SyncTeX$
Intellisense, including completions for bibliography keys (\cite{}) and labels (\ref{}).
$intellisense demo$
Syntax highlighting (colorized code) for .tex / .bib files and more (.cls, .dtx, .ltx, .sty)
LaTeX log parser, with errors and warnings in LaTeX build automatically reported in VS Code.
$error reporting demo$
Real-time linting of LaTeX with ChkTeX to pick up common LaTeX issues as you type.
- Code Actions (automatic fixes) are offered for many issues found by ChkTeX.
- Auto load .chktexrc configure in the following order: 1. manually configured -l setting in chktex.args; 2. .chktexrc file (if exists) in the same folder as the main LaTeX file; 3. .chktexrc file (if exists) at the project root folder.
$auto \item demo$
LaTeX file formatting.
Acting on environments
- To auto close LaTeX environments, call LaTeX Workshop: Close current environment from the Command Palette (command function latex-workshop.close-env).
- To navigate from \begin/\end to the corresponding \end/\begin, while on the begin or end keywords, call LaTeX Workshop: Navigate to matching begin/end from the Command Palette (command latex-workshop.navigate-envpair).
- To select the current environment name, call LaTeX Workshop: Select the current environment name from the Command Palette (command latex-workshop.select-envname). For this command to work, the cursor must be strictly between \begin{...} and \end{...}. Repeated calls result in selecting the outer environment. Note: this function does not work with the Vim extension.
- To add a multi-cursor to the current environment name, call LaTeX Workshop: Add a multi-cursor to the current environment name from the Command Palette (command latex-workshop.multicursor-envname). For this command to work, the cursor must be strictly between \begin{...} and \end{...}. Repeated calls result in selecting the outer environments.
- To surround selected text with an environment, call LaTeX Workshop: Surround/wrap selection with \begin{}...\end{} from the Command Palette (command latex-workshop.wrap-env). A multi-cursor is added inside the braces, to insert the environment name.
Snippets
- A lot of LaTeX commands can be typed using snippets starting in \, then type part of the command to narrow the search.
  $auto \item demo$
- [Deprecated] Surround some selected text with a LaTeX command by pressing \ after selecting some text. A new menu pops up to select the command. This feature is enabled when latex-workshop.intellisense.surroundCommand.enabled is set to true, default is false.
- Surround some selected text with a LaTeX command using ctrl+l, ctrl+w (⌘+l, ⌘+w on Mac). A new menu pops up to select the command. This works with multi selections. The former approach using \ has been deprecated.
  $wrap demo$
- We also provide a few other snippets mechanisms
  - Greek letters are obtained as @ + letter. Some letters have variants, which are available as @v + letter. See here.
    $greek letters demo$
  - Common environments can be obtained by BXY where XY are the first two letters of the environment name, eg. BEQ gives the equation environment. If you want the star version of the environment, use BSXX, eg. BSEQ gives the equation* environment. See here.
    $BSAL demo$
  - Common font commands can be obtained by FXY where XY are the last two letters of the font command name, eg. FIT gives \textit{}. See here.
    $FBF demo$
  - Many other maths symbols can be obtained with the @ prefix. See here.
    $\frac shortcut demo$ $\int shortcut demo$
Shortcuts
- In addition snippets, there are shortcuts that provided by the extension that allow you to easily format text (and one or two other things).
  $\emph{} demo$
When the current line starts with \item or \item[], hitting Enter automatically adds a newline starting in the same way. For a better handling of the last item, hitting Enter on a line only containing \item or \item[] actually deletes the content of the line. The alt+Enter is bind to the standard newline command. This automatic insertion of \item can be deactivated by setting latex-workshop.bind.enter.key to false.
$auto \item demo$
Preview on hover. Hovering over the start tag of a math environment causes a mathjax preview to pop up.
$auto \item demo$

Requirements

LaTeX distribution in system PATH. For example, TeX Live.
- Please note MikTeX does not ship with SyncTeX. See this link for a possible solution.
latexmk is required for the default recipe for building LaTeX projects to work. Alternatively, you can set up your own LaTeX recipe.
Optional: Install ChkTeX to lint LaTeX projects.
Optional: Install latexindent.pl for formatting support if it is not provided by your LaTeX distribution.

Installation

Installing LaTeX Workshop is simple. You can find it in Visual Studio Code Marketplace, or simply run ext install latex-workshop in VS Code Quick Open (ctrl/cmd + P).

Usage

Open a .tex file, right click to build, SyncTeX, or show all features.
- For a complete list, select LaTeX Workshop Actions entry.
For reverse SyncTeX from PDF to LaTeX, ctrl/cmd + left mouse click in the PDF.
Alternatively, VS Code commands are provided in VS Code Command Palette (ctrl/cmd + shift + P).
- Type latex workshop to show all related commands.
To view an arbitrary PDF file, just click on the file in the explorer.

FAQ

LaTeX recipe?

LaTeX recipe refers to a sequence/array of commands which LaTeX Workshop will execute sequentially when building LaTeX projects. It is set in File>Preferences>Settings>latex-workshop.latex.recipes. By default, LaTeX Workshop includes two basic recipes: one simply running the latexmk command, and an other one running the typical sequence of commands pdflatex → bibtex → pdflatex → pdflatex.

You can create multiple recipes with different tools. Each recipe is an object in the configuration list, consisting of a name field and a list of tools to be invoked in the recipe.

The tools in recipes can be defined in latex-workshop.latex.tools, in which each command is a tool. Each tool is an object consists of a name, a command to be spawned, and its arguments (args). To include a tool in a recipe, the tool's name should be included in the recipe's tools list.

When building the project, the first recipe is used. You can compile with another recipe by command latex-workshop.recipes. By default latexmk is used. This tool is bundled in most LaTeX distributions, and requires perl to execute. For non-perl users, the following texify toolchain from MikTeX may worth a try:

"latex-workshop.latex.recipes": [{
  "name": "texify",
  "tools": [
    "texify"
  ]
}],
"latex-workshop.latex.tools": [{
  "name": "texify",
  "command": "texify",
  "args": [
    "--synctex",
    "--pdf",
    "--tex-option=\"-interaction=nonstopmode\"",
    "--tex-option=\"-file-line-error\"",
    "%DOC%.tex"
  ]
}]

As you may notice, there is a mystic %DOC% in the arguments. Symbols surrounded by % are placeholders, which are replaced with its representing string on-the-fly. LaTeX Workshop registers the following placeholders:

Placeholder	Replaced by
`%DOC%`	The LaTeX root file path and name without `.tex` extension
`%DOCFILE%`	The LaTeX root file name without `.tex` extension
`%DIR%`	The LaTeX root file path

Alternatively, you can also set your commands without the placeholder, just like what you may input in a terminal. As most LaTeX compiler accepts root file name without extension, %DOC% and %DOCFILE% do not include .tex extension. Meanwhile, texify requires the extension. So in the above tool %DOC% and .tex are concatenated for completeness.

From toolchain to recipe?

If you have a custom toolchain defined in pre-4.0 versions of LaTeX Workshop, you may want to migrate the existing configuration to the new recipe system. This can be easily done with the following steps:

Create a tool in latex-workshop.latex.tools for each step in the original toolchain.
Name the tools with the name field.
Create a recipe in latex-workshop.latex.recipes with its tools field set as a list of the defined names in Step 2.
Name the recipe with the name field.
Happy typesetting.

Problem Panel and `--max-print-lines`

LaTeX compilers usually produce hard wrapped log messages, which makes them really hard to parse. To hopefully deal with complex log messages, we have decided to rely on non hard wrapped log messages. This can be achieved either

by setting the environment variable max_print_line. This is automatically done within the extension and works for the TeXLive distribution.
by adding the --max-print-line option to the compilers. This is automatically done within the extension and works for the MiKTeX distribution. Unfortunately, some compilers such as lualatex or xelatex do not understand this option and may therefore fail. To disable the automatic addition of this option, set latex-workshop.maxPrintLine.option.enabled to false.

Note that when log messages are hard wrapped, the Problems Pane may be messed up.

Root file?

While it is fine to write all contents in one .tex file, it is common to split things up for simplicity. For such LaTeX projects, the file with \begin{document} is considered as the root file, which serves as the entry point to the project. LaTeX Workshop intelligently finds the root file when a new document is opened, the active editor is changed, or any LaTeX Workshop command is executed.

To find the root file, LaTeX Workshop will follow the steps below, stopping whenever one is found:

Magic comment % !TEX root = relative/or/absolute/path/to/root/file.tex. If such comments exist in the currently active editor, the referred file is set as root.
Self check If current active editor contains \begin{document}, it is set as root.
Root directory check LaTeX Workshop iterates through all .tex files in the root folder of the workspace. The first one with \begin{document} is set as root.

If no root file is found, most of the features in LaTeX Workshop will not work.

Magic comments?

LaTeX Workshop supports both % !TEX root and % !TEX program magic comments. The former is used to define the root file, while the latter helps select compiler program. However, it is advised to use the recipe system instead of magic program to define the building process, since the latter is only implemented for backward compatibility.

For % !TEX program magic comment, its arguments are defined in latex-workshop.latex.magic.args:

"latex-workshop.latex.magic.args": [
  "-synctex=1",
  "-interaction=nonstopmode",
  "-file-line-error",
  "%DOC%"
]

Suppose there is a line % !TEX program = xelatex in the root file. Upon building the project, LaTeX Workshop will parse the root file and figure out that xelatex should be used. Arguments are included to invoke the compiler.

When using % !TEX program with bibliographies, a bib compiler must be defined with % !BIB program comment, e.g., % !BIB program = bibtex. Otherwise the extension will only run one-pass compilation with the specified LaTeX compiler.

Spell check?

Code Spellchecker did a great job. Users may also find other extensions better alternatives, e.g., Spell Right and LanguageTool. Especially the last one is credited for its multi-lingual support.

Build on save?

By default, the extension compiles the project upon saving any tex files. If you want to disable this feature, setting the configuration item latex-workshop.latex.autoBuild.onSave.enabled to false will do.

Synctex after build?

When using the internal PDF viewer, you can make it automatically jump after build to the location pointed out by the tex file. If you want to enable this feature, setting the configuration item latex-workshop.synctex.afterBuild.enabled to true will do.

Docker?

From version 5.3.0 there is an experimental implementation on docker support following the idea of @Arxisos. You can set latex-workshop.docker.enabled to true to use tianon/latex. It is advised that the image is 'pre-'pulled.

@Arxisos created snippets for LaTeX binaries in docker, and @lippertmarkus had another short description on how to use docker with LaTeX Workshop.

GitHub

The code for this extension is available on github at: https://github.com/James-Yu/LaTeX-Workshop

Like this work?

😄 Star this project on GitHub and Visual Studio Marketplace
😊 Leave a comment
☺️ Spare me some coffee via Paypal

License

MIT

yzhang-gh/LaTeX-Workshop