Using TeXLive with Dev Containers in VSCode

In this post I will describe how to set up VSCode to use a Docker container to run TeXLive and how to set up a folder template to quickly setup documents in the future.

Prerequisites

In this post I will assume that you are running Linux and that your template folder is called latex_template. What you need in order to get started is:

• A working rootless Docker installation
• VSCode installed along with the extensions Dev Containers, LaTeX Workshop, and Folder Templates installed. Container Tools is also recommended, but not required.
• Enough disk space for the docker image which is about 5.2GB and enough bandwidth to download it in a timely manner, it is a download of about 2.3GB.

Setting up a Dockerfile

We shall use Island of TeX‘s Docker image as a base. But in order to use Git and commit signing (as you should) we need some slight customization. This will do the trick:

FROM registry.gitlab.com/islandoftex/images/texlive:latest

RUN apt-get update 
RUN apt-get install -y git ssh gnupg2
RUN apt-get clean

This will install Git, SSH and GnuPG into the base image in a persistent manner. Copy the above into the file latex_template/.devcontainer/Dockerfile.

Setting up Dev Containers: Method 1

Copy

{
  "build": { "dockerfile": "Dockerfile" },
  "customizations": {
    "vscode": {
      "extensions": [
        "James-Yu.latex-workshop"
      ]
    }
  }
}

into the file latex_template/.devcontainer/devcontainer.json.

Setting up Dev Containers: Method 2

You can also build the Dockerfile from the commandline (from a folder with the Dockerfile from above) with the command

$ docker build -t mytexlive . 

and instead set latex_template/.devcontainer/devcontainer.json to be

{
  "image": "mytexlive",
  "customizations": {
    "vscode": {
      "extensions": [
        "James-Yu.latex-workshop"
      ]
    }
  }
}

Setting up Folder Templates

Make a file latex_template/.ftsettings.json with the contents:

{
  "name": "Template Title",
  "omitParentDirectory": true
}

Where you give whatever name you want to the template.

Make a file latex_template/latexmkrc with the contents:

$pdf_mode = 4;

$out_dir = "build";

This will cause latexmk to use LuaLaTeX (as you should…) and place the output in latex_template/build. You can also add a line to latex_template/latexmkrc:

@default_files = ('[FTName].tex');

to specify the initial TeX file as the main document to run LuaLaTeX on, so you can include other TeX-files. For further information on how to customize latexmkrc refer to its documentation.

The folder latex_template/build should be ignored by Git, so it is recommended to set up latex_template/.gitignore to do this:

build/

Next, create a file latex_template/[FTName].tex (and yes, the file name should literally be [FTName].tex). This file should contain the common code for the template you are creating, for example:

% Preamble  
\documentclass[12pt, a4paper]{article}  

% The title is likely not something
% you can predetermine
\title{}  

% Your name and other authors
\author{Your Name}  

% Your packages etc.  
  
\begin{document}
          
% Your document

    \maketitle  
    \tableofcontents  
          
    % ...
      
\end{document}

Move the folder latex_template to a place there you will keep other templates, e.g. ~/Documents/Templates.

Setting up VSCode

From the Command Palate (on a PC, the Command Palate can be accessed by pressing Ctrl + Shift + P), select the command “Set Custom Global Folder Templates Folder” and browse to and select the folder containing your templates, e.g. ~/Documents/Templates.

In the VSCode Settings, go to the option and set Latex-workshop > Latex > Recipe: Default to latexmk (latexmkrc).

Make your project

Now, open an empty folder in VSCode, and from the Command Palate, select “Create New Templated Folder” (this can also be done via the context menu in the file browser), select your template and type the name of your project, e.g. myproject. You should now see some new files, like myproject.tex which contains the LaTeX document prepared earlier, and copies of the other files and sub-folders in latex_template/.

From the Command Palate, select “Reopen in Dev Container”. After the base image has been downloaded and built, you can open myproject.tex and (on a PC) press Ctrl+S and a sub-folder build/ should appear containing the resulting PDF and other temporary files.

Files

You can download a ZIP archive with the folder template here.