LaTeX Workshop

LaTeX Workshop is a popular LaTeX extension for Visual Studio Code, providing a comprehensive set of features for LaTeX editing, compiling, and previewing. In the following, I summarize some useful settings and tips for using LaTeX Workshop effectively.

Highlight features:

Writing assistance
- AI prompts from GitHub Copilot
  
  This is the most important reason I use VS Code for LaTeX editing, rather than Overleaf (online LaTeX editor) or TexShop. It is also what distinguishes VS Code from the other LaTeX editors.
  
  With an university email, you can get GitHub Copilot Pro for free. It is a powerful tool to help me to write academic papers, create reports, and prepare teaching materials. ✅
  
  See HERE for more details about GitHub Copilot Education benefits.
Editing
- Intellisense for code autocompletion
- Snippets for quickly insert commonly used commands and environments

Useful resources:

Latex-Workshop GitHub repo: https://github.com/James-Yu/LaTeX-Workshop/wiki/Install#usage
Configure LateX Workshop by Paul Wintz: https://paulwintz.com/latex-in-vscode/ 👍
Integrating Overleaf with VS Code: https://www.youtube.com/watch?v=SaMRCYbsAek
Snippets: https://github.com/James-Yu/LaTeX-Workshop/wiki/Snippets#Handy-mathematical-snippets

Aesthetic themes for LaTeX Workshop PDF viewer:

"latex-workshop.view.pdf.color.dark.backgroundColor": "#F5F5DC",
"latex-workshop.view.pdf.color.dark.pageColorsBackground": "#F5F5DC",

This sets the background color and the spacing btw pages in the PDF viewer to beige in dark mode, which is easier on the eyes.

By default, LaTeX Workshop auto builds the pdf on every save. This can be too frequent and distracting. I set "files.autoSave": "onFocusChange" so that the pdf only rebuilds when I switch away from the tex file, not on every keystroke.

Snippets

Environment snippets works directly in tex, you type B, a drop-down list will show up for you to choose.

The prefixes start with B and are followed by an abbreviation of the environment name.
The unnumbered versions of the environments are prefixed with BS, e.g., BSEQ for equation*.
In tex, these cmds work in both math and text environments.
However, it is more restrictive in markdown, where these cmds work only inside math environments ( $...$ )

Mathematical symbols

Prefix	Command
`__`	`_{$1}`
`**`	`^{$1}`
`...`	`\dots`

Environments

Prefix	Environment name
`BEQ`	`equation`
`BSEQ`	`equation*`
`BAL`	`align`
`BSAL`	`align*`
`BGA`	`gather`
`BSGA`	`gather*`
`BMU`	`multline`
`BSMU`	`multline*`
`BIT`	`itemize`
`BEN`	`enumerate`
`BSPL`	`split`
`BCAS`	`cases`
`BFR`	`frame`
`BFI`	`figure`
`BTA`	`table`

How to surround some selected text with an environment:

In editing mode, select the text you want to surround.
Insert the environment by typing either
- ✅ \<envname>, e.g., \equation, or
  
  This will surround the selected text with \begin{envname} and \end{envname}.
- \beginend
  
  This will surround the selected text with \begin{} and \end{}, and enter the multi-cursor mode. Type your desired environment name in \begin{} and the same name will be automatically filled in the \end{}.

Q: How to select the current environment, e.g., a table environment?
A: Place the cursor inside the environment, then press Cmd+Shift+P (Mac) to open the command palette, type Latex Workshop: Select Current Environment, and press Enter. This will select the entire environment, including the \begin{} and \end{} lines.

LaTeX Workshop: Select the current environment content only selects the content inside the environment, excluding the \begin{} and \end{} lines.
LaTeX Workshop: Navigate to matching begin/end moves the cursor to the matching \begin{} or \end{} of the current environment.
Changing from one environment to another. ↩︎
1. Place the cursor inside the environment you want to change.
2. LaTeX Workshop: Select the current environment name to select the environment name.
3. LaTeX Workshop: Add a multi-cursor to the current environment name to add a multi-cursor to both the \begin{} and \end{} lines.
4. Type the new environment name to replace the old one.

`@` Suggestsions

LaTeX-Workshop provides an independent intellisense mechanism triggered by @. For example, you can type @a for \alpha. It works for most Greeks and have some useful mathematical helpers.

Mathmetical helpers:

Prefix	Command
`@(`	`\left( $1 \right)`
`@{`	`\left\{ $1 \right\}`
`@[`	`\left[ $1 \right]`
`@^`	`\Hat{$1}`
`@_`	`\bar{$1}`

Inserting Greek letters:

Prefix	Command
`@a`	`\alpha`
`@b`	`\beta`
`@g`	`\gamma`
`@d`	`\delta`
`@e`	`\epsilon`

Build the document

You can define several compiling toolchains to build LaTeX projects using LaTeX recipes and then call the command Build with recipe to choose the appropriate toolchain for actually building the project. Alternatively, you can directly select the appropriate recipe from the TeX badge .

Below are some commonly used examples:

"latex-workshop.latex.recipes": [
  {
    "name": "latexmk",
    "tools": [
      "latexmk"
    ]
  },
  {
    "name": "pdflatex -> bibtex -> pdflatex * 2",
    "tools": [
      "pdflatex",
      "bibtex",
      "pdflatex",
      "pdflatex"
    ]
  }
]

The first one simply relies on the latexmk command. This is the default recipe to use when building a project for the first time.

If you want a different default recipe, put it as the first element of the latex-workshop.latex.recipes array.
The second one run the following sequence of commands pdflatex → bibtex → pdflatex → pdflatex.
Many of my projects use xelatex instead of pdflatex to support Unicode characters and OpenType fonts.

This recipe is similar to the second one, but it uses xelatex instead of pdflatex.

You can change the default recipe by setting the latex-workshop.latex.recipe.default. Recipes are referred to by their names as defined in latex-workshop.latex.recipes.

Note there are two special values:

"first": Use the first recipe defined in latex-workshop.latex.recipes.
"lastUsed": Use the last used recipe by the command *LaTeX Workshop:

Build with recipe*. This is useful when you have multiple recipes defined and you want to use the last one you used without having to select it again.

// set the default recipe to the last used one
"latex-workshop.latex.recipe.default": "lastUsed"

View PDF

Forward/Direct synctex (source to pdf) can either be activated by selecting ‘Navigate, select, and edit’ > ‘SyncTeX from cursor’ in the side bar, or by the shortcut cmd+option+j (on Mac).
```
  // enable 
  "latex-workshop.synctex.afterBuild.enabled": true
```
The setting syncs PDF with cursor position after compiling., defaults to false.
Backward/Reverse synctex (pdf to source) is activated by pointing at the relevant element of the pdf preview. When using the internal viewer, the default keybinding to point at an element in the pdf preview is cmd+click. It can be changed to double-click using the setting latex-workshop.view.pdf.internal.synctex.keybinding.
```
"latex-workshop.view.pdf.internal.synctex.keybinding": "double-click"
```

Output Directory

By default, LaTeX builds with LaTeX Workshop puts output files in the directory containing your .tex file. This quickly creates a cluttered mess, due to the numerous auxiliary files generated by the LaTeX build process. To avoid clutter and allow for build files to be quickly deleted, change the out directory. I use the following setting:

"latex-workshop.latex.outDir": "%DIR%/out_dir",

After changing "latex-workshop.latex.outDir", LaTeX Workshop’s "Clean up auxiliary files" command no longer deletes auxiliary files unless you also change this setting:

"latex-workshop.latex.clean.subfolder.enabled": true,

(Note: The “Clean up auxiliary files” command misses some file types, so for a full clean you should just delete all of the files in the folder manually.)

Overleaf Integration

Overleaf Workshop Extension: https://github.com/iamhyc/overleaf-workshop

Overleaf is nice for collaboration, but you will loss the LaTeX Workshop features. E.g., snippets, better synctex (with highlighter of precise location), etc.

A workaround is to use GitHub integration to sync Overleaf projects to your computer. Using Git incurs some overhead with pushing, pushing, and (possibly) merging, but it may be worth the upsides of editing Overleaf documents with the exact same tools as any of your local LaTeX documents.

Log in with Cookies

Find Overleaf cookies:

Go to Overleaf homepage in Chrome > Open the browser developer tools (F12), go to “Network” tab > In the Filter field, type “project” > Click the project under “Name” column > Go to “Headers” tab > Scroll down to “Request Headers” section > Copy the value of “Cookie”.
In VS code:

Go to the Overleaf Workshop extension, click “log in with cookies”, paste the cookies you copied from the browser, and click “Log in”.

When the login is successful, you will see your Overleaf projects listed in the extension sidebar. And you will see the server status at the bottom left corner of VS Code.

Highlight features:

Sync with Overleaf Cloud

User cursor indicator will show your position.
Chat with Collaborators (copy line reference)
On-the-fly Compiling and Previewing

Real-time PDF preview as you type.
- Cmd + Option + B (on macOS) to compile, and
- Cmd + Option + V to preview
The compiling is done on Overleaf servers. The pdf output together with all auxiliary files will be in a folder named /.output/ in your project.

Your lock latex compiler, such as Latex Workshop, won’t work here.

Caveats:

Do NOT use the Overleaf Workshop “Open Projects Locally” feature.

❗️ Using a local version leads to major issues, including edit conflicts and data loss. See this GitHub issue.

Overleaf pdf viewer supports three themes: default (white), light (warm yellow, easy on eyes 👍), and dark. You can change the theme via clicking the theme button (the square) on the title bar in the Overleaf PDF viewer.
P.S. If you cannot see the theme button, please make sure the PDF viewer is wide enough.

SyncTeX and Reverse SyncTeX

The SyncTeX and Reverse SyncTeX are supported in the Overleaf PDF viewer.

SyncTeX, Jump to PDF: Also called forward sync.

Put your cursor in the expected position in the document editor, then press Cmd+Option+J (Mac) to jump to the corresponding position in the PDF.

At first the keybinding did not work for me. To fix it, I need to change the when condition of the command overleaf-workshop.compileManager.syncCode.

Open Keyboard Shortcuts (⌘+K, ⌘+S), search for overleaf-workshop.compileManager.syncCode. Right click the command, select Change When Expression, and change it to: “editorTextFocus && resourceScheme == ‘overleaf-workshop’”.

The final keybinding looks like this:
```
{
  "key": "alt+cmd+j",
  "command": "overleaf-workshop.compileManager.syncCode",
  "when": "editorTextFocus && resourceScheme == 'overleaf-workshop'"
}
```
Reverse SyncTeX, Jump to Code: backward sync. Double click on the text on PDF to jump to the corresponding position in the editor.

Q: Editor stops responding when compiling tex for preview.
A: Disable auto build on save. This way, you can have a smooth editing experience and only compile when you need to preview. Use ⌥+⌘+B to compile when needed.

"overleaf-workshop.compileOnSave.enabled": false

GitHub Integration

Left side bar > Integrations > GitHub

This will create a GitHub repository and link it to your Overleaf project. You can then clone the repository to your local machine and use Git to sync changes between your local machine and Overleaf.

Cloning the repository to your computer

On GitHub, navigate to the main page of the repository.
Click the green Code button > Copy the URL for the repository.
Open Terminal > Go to your local folder where you want to clone the repository, then run:
```
git clone <repository URL>
```

Synchronizing changes

Synchronization between GitHub and Overleaf does NOT happen automatically. Synchronization options are shown by clicking the GitHub option within Integrations.

GitHub ahead of Overleaf: Pull changes from GitHub to Overleaf.
Overleaf ahead of GitHub: Push changes from Overleaf to GitHub.

Resolving merge conflicts

Merging conflicts happen when your collaborator changed a line in Overleaf and you changed the same line in the GitHub repository, Overleaf may not be able to choose which version to keep.

Suggested practice: Always pull changes from GitHub to Overleaf before pushing changes from Overleaf to GitHub. This way, you can resolve any conflicts locally on your computer before pushing the changes to GitHub.

ref: GitHub synchronization