Setting up VS Code to write in LaTeX using latexmk and biber

Figure: VS Code + LaTeX, another local alternative to Overleaf.

As it is widely known, LaTeX brings great typography, as well as a lot of control over document formatting, from book editing to scientific writing. There are a great number of editors for writing .tex files locally, but I feel more “at home” using the code editor I am mostly familiar with. In my case, getting it to run flawlessly was a bit tricky, so here’s what I had to do.

Prerequisites

Beyond the obvious VS Code (or VSCodium), the LaTeX Workshop extension is required, as well as a TeX distribution such as MiKTeX, which comes with a package manager that automatically installs dependencies on the fly.

Note: MikTeX has some hyphenation issues that can be fixed by going into the GUI console and choosing Settings → Formats → (select all) → Build format.

Preferences: Open User Settings (JSON)

Configuring VS Code for LaTeX is quite easy. Open Preferences: Open User Settings (JSON) with your command palette and add the following contents to set the command line definitions for some common LaTeX tools:

"latex-workshop.latex.tools": [
    {
        "args": [
            "-synctex=1",
            "-interaction=nonstopmode",
            "-file-line-error",
            "%DOC%"
        ],
        "command": "pdflatex",
        "name": "pdflatex"
    },
    {
        "args": [
            "-synctex=1",
            "-interaction=nonstopmode",
            "-file-line-error",
            "%DOC%"
        ],
        "command": "xelatex",
        "name": "xelatex"
    },
    {
        "args": [
            "-synctex=1",
            "-interaction=nonstopmode",
            "-file-line-error",
            "-pdf",
            "-outdir=%OUTDIR%",
            "%DOC%"
        ],
        "command": "latexmk",
        "name": "latexmk"
    },
    {
        "args": [
            "%DOCFILE%"
        ],
        "command": "bibtex",
        "name": "bibtex"
    },
    {
        "args": [
            "%DOCFILE%"
        ],
        "command": "biber",
        "name": "biber"
    }
],

Those are just command line definitions for some common LaTeX tools, so you might not need to define all of them, depending on which you'll use.

Next, we have to set up the recipe to build our files with. Personally, I use the latexmk package — default in Overleaf — which automates compiling .tex documents and solved the errors I had related to .eps and .bib files (only when using biber, a backend for biblatex with some nifty improvements):

"latex-workshop.latex.recipes": [
    {
        "name": "latexmk",
        "tools": [
            "latexmk",
        ]
    }
],

The next time you build your document, it should automatically be used. Below is a list of similar recipes with other tools, including default ones:

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

And finally, to fix citation warnings in the editor, an additional parameter must be set. I’ve also added a few other optional settings that I use below:

// Fix citation warnings in editor when using biber (wavy lines).
"latex-workshop.intellisense.citation.backend": "biblatex",
// Set bibliography indentation to four spaces (default: two).
"latex-workshop.bibtex-format.tab": "4 spaces",
// Avoid building PDF every time a file is modified or saved.
"latex-workshop.latex.autoBuild.run": "never",
// Sync PDF with cursor position after compiling.
"latex-workshop.synctex.afterBuild.enabled": true,
// Automatically choose last used recipe on next build.
"latex-workshop.latex.recipe.default": "lastUsed",

Note: do take care to avoid breaking the JSON formatting in your settings.

Preferences: Open Keyboard Shortcuts (JSON)

After relying on Overleaf for quite some time, I’ve grown fond of using the [Ctrl + Enter] keybind to compile. Setting [Alt + Enter] to sync the PDF viewer with the text cursor position is a nifty plus, among a few others.

To configure them, open your shortcuts in Preferences → Open Keyboard Settings (JSON) and add the following contents to the existing list:

{
    "key": "ctrl+enter",
    "command": "latex-workshop.build",
    "when": "!config.latex-workshop.bind.altKeymap.enabled && !virtualWorkspace && editorLangId =~ /^latex$|^latex-expl3$|^rsweave$|^jlweave$|^pweave$/"
},
{
    "key": "alt+enter",
    "command": "latex-workshop.refresh-viewer"
},
{
    "key": "ctrl+l c",
    "command": "latex-workshop.citation"
},
{
    "key": "ctrl+l escape",
    "command": "latex-workshop.kill"
},
{
    "key": "ctrl+l x",
    "command": "workbench.view.extension.latex-workshop-activitybar",
    "when": "!config.latex-workshop.bind.altKeymap.enabled"
},

Note: replace ctrl with cmd instead, if you are on MacOS.

That’s about it. Also note that there are many other snippets and shortcuts (also listed in this cheat sheet) available during editing — all very useful!