Tidy LaTeX files with VS Code

Visual Studio Code can offer an excellent cross-platform environment for editing $\LaTeX$ documents. Using the spectacular Latex-workshop extension and a spell checker it beats most any other option.

Under the hood, Latex-workshop implements latexmk so unfortunately by default we still encounter the perpetual frustration of $\LaTeX$ — the messy auxiliary files generated during the build. Which clog up your folders like this:

example.aux
example.bbl
example.blg
example.fdb_latexmk
example.fls
example.log
example.out
example.pdf
example.synctex.gz
example.tex
example.toc
example.bib

We really only need the highlighted files here.

It is possible to pass latexmk a command line flag to delete the extra files after the build but this breaks synctex and stops us being able to do speedy rebuilds.

Modifying the output folder

We can modify the settings file for VS Code (in settings.json) to solve our problems.

Firstly, we can tell Latex-workshop to output everything to a sub-folder:

"latex-workshop.latex.outDir": "%DIR%/output"

This gets us 80% of the way there, but tiding the output away includes the crucial .pdf file!

Custom build commands

To separate the file we want (the .pdf file) from the extra stuff, after the build we need to copy it somewhere else. For example, to a different folder or to the top level.

Here is the code snippet in my settings.json file I use to make that happen on macOS including for LuaTeX:

"latex-workshop.latex.recipes": [
    {
      "name": "latexmk ➞ makeFolder ➞ copyPDF",
      "tools": ["latexmk", "makeFolder", "copyPDF"]
    },
    {
        "name": "lualatexmk ➞ makeFolder ➞ copyPDF",
        "tools": ["lualatexmk", "makeFolder", "copyPDF"]
    }
],
"latex-workshop.latex.tools": [
    {
        "name": "latexmk",
        "command": "latexmk",
        "args": [
            "-shell-escape",
            "-synctex=1",
            "-interaction=nonstopmode",
            "-file-line-error",
            "-cd",
            "-pdf",
            "-outdir=%OUTDIR%",
            "%DOC%"
        ],
        "env": {}
    },
    {
        "name": "lualatexmk",
        "command": "latexmk",
        "args": [
            "-shell-escape",
            "-synctex=1",
            "-interaction=nonstopmode",
            "-file-line-error",
            "-pdflatex=lualatex",
            "-cd",
            "-pdf",
            "-outdir=%OUTDIR%",
            "%DOC%"
        ],
        "env": {}
    },
    {
        "name": "makeFolder",
        "command": "mkdir",
        "args": [ 
            "-p", 
            "%DIR%/pdfs/"
        ],
        "env": {}
    },
    {
        "name": "copyPDF",
        "command": "cp",
        "args": [ 
            "%OUTDIR%/%DOCFILE%.pdf",
            "%DIR%/pdfs/%DOCFILE%.pdf"
        ],
        "env": {}
    }
]

We create a custom build command that chains three elements: first we build $\LaTeX$ as many times as we need using latexmk, then we checks if a folder called “/pdfs” exists (if not we create it), and finally we copy the output .pdf file to this folder.

Benefits of this approach

I like this method because we have a super tidy folder structure while still maintaining all the possible features of $\LaTeX$.

It’s nice because you can have many different documents sorted neatly in the same directory, and easily import the same references and style:

example1.tex
example2.tex
example3.tex
  /references
    references.bib
  /style
    style.sty
  /output
     # blah...
  /pdfs
    example1.pdf
    example2.pdf
    example3.pdf

Lovely!

I hope you find this setup as helpful and productive as I have.