Visual Studio Code as Latex Editor

From anecdotal evidence engineers tend to carefully evaluate a tool before including it into their standard toolkit. Naturally, products they spend most of time working with become subject of day to day conversations and an inevitable source of complaints every time they hinder productivity. This article presents a Visual Studio Code as a robust editor for the .tex files that does not cause much headache.

This article became obsolete due to recent changes in the editor and Latex plugins. We recommend switching to the newer version of the post.

Visual Studio Code is related to Visual Studio as JavaScript to Java. Both are source code editors from Microsoft, but contrary to its ponderous cousin, Visual Studio Code is lightweight, cross-platform and available open-source. In the following tutorial I will present how to configure the editor to offer syntax highlight, spell checking and a document preview for Latex files with some help of a few plugins developed by community.

Tutorial

Download the latest version of Visual Studio Code for your system.

The following Bash snippet downloads and installs Visual Studio Code on Debian and Ubuntu.
```
wget -Ovscode.deb https://vscode-update.azurewebsites.net/latest/linux-deb-x64/stable
dpkg -i vscode.deb
```

Install the following Visual Studio Code plugins .

code --install-extension streetsidesoftware.code-spell-checker
code --install-extension ajshort.latex-preview
code --install-extension ms-vscode.latex

Create a directory for a Latex project. Later on in the tutorial we will refer to this directory as the project directory.
Create a directory .vscode in the project directory.
```
mkdir -p .vscode
```
.vscode is a directory where Visual Studio Code stores workspace specific settings.
Create a tasks.json file in the .vscode directory with the following content.
```
{
 "version": "0.1.0",
 "isShellCommand": true,
 "suppressTaskName": true,
 "showOutput": "always",
 "tasks": [{
         "taskName": "Build PDF",
         "command": "pdflatex",
         "isBuildCommand": true,
         "args": [
             "-interaction=nonstopmode",
             "-file-line-error",
             "report.tex"
         ]}, {
         "taskName": "Build BibTex",
         "command": "bibtex",
         "isTestCommand": true,
         "args": ["report.aux"]
         }]
}
```
The file defines two tasks. A task in Visual Studio Code is an action executed by the editor in response to a specific event. In our case the actions are commands to build a Latex document and refresh bibliography references. The Build PDF task is declared as a build command. Its execution can be triggered by a Ctrl+Shift+B keystroke combination. The Build BibTex task is declared as a test command.

As of this writing there is no default keystroke bound to the test command. You can register a custom binding using menu File > Preferences > Keyboard Shortcuts. For more information on a custom keystroke bindings see Customizing Shortcut section in the Visual Studio Code Key Bindings article.

Before executing the tasks, you may want to change the report.tex and report.aux filenames from the template above if you are using different naming convention for files in your project.

Assuming that the pdflatex and bibtex command line utilities required to compile Latex documents are installed on your machine, press the key combination Ctrl+Shift+B to build the Latex document. You should see the command output in the terminal window integrated into the editor.
Enable word wrapping and spell checking in your workspace by creating a settings.json file in the .vscode directory with the following content.
```
{
  "editor.cursorBlinking": "solid",
  "telemetry.enableCrashReporter": false,
  "telemetry.enableTelemetry": false,
  "editor.wordWrap": "on",
  "editor.wordWrapColumn": 80,
  "editor.wrappingIndent": "same",
  "cSpell.enabled": true
}
```
The settings.json file is the place for the workspace specific settings of the editor. In the example above cursor blinking is disabled for the performance considerations. Telemetry and crash reporting are turned off as well. Automatic word wrapping is enabled to avoid the horizontal scroll bar when lines of text exceed the viewport. Finally, the spell checking offered by an external plugin is enabled.
Deactivate spell checking for certain Latex commands and add a custom dictionary of non standard phrases and acronyms that appear in your document.

Create a cSpell.json file in the .vscode directory. The example file below loads a custom dictionary file dictionary.txt from the .vscode directory. The file format is simple list of words separated by a newline character. For more information on custom dictionaries refer to the project documentation.
```
{
 "version": "0.1",
 "language": "en",
 "dictionaryDefinitions": [
     { "name": "projectDictionary", "path": "./dictionary.txt"}
 ],
 "dictionaries": ["projectDictionary"],
 "languageSettings": [
     { "languageId": "*", "dictionaries": ["projectDictionary"] }
 ],
 "ignoreRegExpList": [
     "^\\\\\\w+{?",
     "\\\\cite{\\w+}",
     "\\\\begin{\\w+}",
     "\\\\end{\\w+}",
     "\\\\usepackage{\\w+}",
     "\\\\bibliographystyle{\\w+}"]
}
```
Finally, disable spell checking for Latex commands, words that start with the slash \ character, and phrases in between parentheses following begin, end, cite, usepackage and bibliographystyle commands.

Please do not hesitate to comment below if you spot an error or you would like to share your opinion on the subject of the article. Your feedback is highly valued!

Visual Studio Code as Latex Editor

Tutorial

Share this post