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.

Features

• Build LaTeX (including BibTeX) to PDF automatically on save.
• View PDF on-the-fly (in VS Code or browser).
• Direct and reverse SyncTeX. Click to jump between location in .tex source and PDF and vice versa.
• Intellisense, including completions for bibliography keys (\cite{}) and labels (\ref{}).
• Syntax highlighting (colorized code) for .tex / .bib files and more.
• LaTeX log parser, with errors and warnings in LaTeX build automatically reported in VS Code.
• 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 ChxTeX.

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.
• Optional: Set your LaTeX toolchain (LaTeX Workshop should just work out of the box for users with latexmk installed).

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).

Alternatively, you can check out this repository and copy it to the VS Code local extensions folder:

• Windows %USERPROFILE%\.vscode\extensions
• Mac/Linux $HOME/.vscode/extensions

Usage

• Open a .tex file, right click and many features have menu entries there.
• For reverse SyncTeX from PDF to LaTeX, ctrl/cmd + left mouse click in the PDF.
• Alternatively, VS Code commands are provided as follows:
  • latex-workshop.build: Build LaTeX project to PDF using LaTeX toolchain.
  • latex-workshop.view: Open a web browser window to view the PDF file.
  • latex-workshop.tab: Open a VS Code tab to view the PDF file.
  • latex-workshop.synctex: Direct synctex from cursor position.
  • latex-workshop.clean: Clean up LaTeX auxillary files.

Linting with ChkTeX

If you have ChkTeX installed as part of your LaTeX distribution, Latex Workshop can run it against your LaTeX files in order to highlight issues.

To enable linting, set latex-workshop.linter: true in settings.

The current file will be linted after a brief pause in typing. The full project will be linted upon opening VS Code for the first time, and each time you hit save. Warnings and errors are shown in the Problems pane - you can click on each entry to go to the relevant position where ChkTeX has found an issue.

For details on how to interpret the reported issues, consult the ChkTeX manual.

Code actions

For many issues, LaTeX Workshop will offer Code Actions to help you correct your LaTeX files. If you take your mouse to a highlighted error, you will see a lightbulb in the gutter if LaTeX Workshop is able to propose a solution to the problem. Alternatively, you can hit ctrl/cmd + . whilst the cursor is on a highlighted area to trigger the same dropdown. Choose the item in the menu to have LaTeX Workshop attempt to fix the issue:

FAQ

LaTeX toolchain?

LaTeX toolchain 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.toolchain. By default latexmk is used. For non-perl users, the following texify toolchain may worth a try:

[ "texify --synctex --tex-option=\"-interaction=nonstopmode -file-line-error\" --pdf %DOC%" ]

LaTeX toolchain must always be defined as a JSON array, even if there is only one command to execute. For multiple commands, each one is represented by a string in the array.

The placeholder %DOC% in all strings will be replaced by the quoted LaTeX root file name on-the-fly. Alternatively, you can also set your commands without the placeholder, just like what you may input in a terminal.

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:

1. 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.
2. Self check If current active editor contains \begin{document}, it is set as root.
3. 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.

Contributing

• Fork it.
• Do something.
• Pull request.
• Thank you and have some beer.

License

MIT