Compiling LaTeX Locally on macOS with VS Code and Git (How I'm Writing My Thesis)

Introduction

In the past few months, I've finally learned to use LaTeX properly in an attempt to make my eventual thesis-writing life easier. Additionally, it seemed difficult to help all my group members get some collaborative writing platform working together (and we all avoid Google Docs because of how limited its capabilities are). OneDrive for Business/Office 365 used to be my go-to, but it was hard to get accounts working together.

Overleaf became my tool of choice because of its powerful collaborative, text editing, and LaTeX compiling features. It's also quite popular here at TU Delft; one student council organization wants to get us institutional licenses because of how widely we use it. Unfortunately, I still much prefer to write and compile LaTeX files on my own computer.

Why am I doing this? I don't want to rely on Overleaf:

I want an offline editor – any online service suffers from interruptions and I become frustrated when Overleaf prevents me from writing at all during one. Also, I often work in places without internet (trains, busses, etc.), and I use VPNs, which sometimes have networking glitches too.
Customizability – my Android friends might make fun of me for this, but being able to define keyboard shortcuts, change themes and fonts, and the editing layout are big plusses, especially if I am going to be spending many hours writing. Or even changing how my editor, PDF viewer, and others are laid out.
Double backups – writing offline makes backing up my responsibility, but I already have a robust system in place. My working directory syncs with iCloud Drive, I run Time Machine on an external hard drive, and since I run git (see below), I can also push changes to another online repository.
VS Code's text and code editing tools are almost unmatched (for the record, I haven't used Atom or Sublime Text) – It's also lightweight, open source, and the most popular editor for coders in industry. There are too many useful features to give justice to here, but an abridged list might be: moving text up and down rows, integrated git (including showing diffs and managing conflicts), its universal find and replace, and its keyboard–based superpowers. This Smashing Magazine article might be a nice overview of some ncie features, though it's two years old now.
Working locally makes referencing an absolute breeze – I can easy integrate my reference management workflow so papers are available to cite almost as soon as I find them. For those with premium Overleaf accounts, there's a direct integration too, but I'm not ready to pay for it (especially next to all my other reasons of why to not use it).
Git – being able to have precise version control over my writing is great, especially being able to branch. Overleaf doesn't have this built-in and its version management is nowhere near as powerful as git. Git also lets me do some other fun things (see below).

Below is a small demonstration of some of these features, but it's nowhere near complete. I don't show off how awesome window management is, how the powerful the command pallette is (automatic document formatting, switching between files), and so many features that I use instinctively now (the learning curve is not steep)!

Editing LaTeX Locally

So, to run everything locally, I need three things:

Some flavour of LaTeX tools (including compiler and packages)
Code Editor
Version Management (which doubles as a form of backing up)

BasicTeX (or some other flavour of LaTeX)

Firstly, I should clarify for the unitiated that, while you can write LaTeX files in any text editor, you need a compiler to turn raw TeX code into a formatted document. Each compiler relies on other packages to work, like hyperref for making links in your PDF.

There are many versions of LaTeX you can download, but BasicTeX is the most lightweight version that comes with some compilers and the minimal set of LaTeX packges you might need to compile a document. Make sure to get Tex Live Utility to help manage packages though. Other, larger (and admittedly more recommended) options come with text editors and GUIs (interfaces), but since I lean so heavily on VS Code, I don't need them.

The full LaTeX package runs near 4 GB, and I’m also fundamentally opposed to downloading more files than I need. BasicTeX comes in 10x smaller at 400 MB. The main sources of discrepancy are the GUIs and extra fonts and packages. Doing things my way also means that you'll likely need to manually install packages, which is simple but time-consuming, and might require you to work inside a command line terminal.

VS Code

I already mentioned why I love VS Code so much above, but it's worth iterating: using VS Code has probably been the biggest change to my productivity toolset ever. I would put it at least on par with the collaborative writing revolution that Google Docs brought, except this is more for personal use.

VS Code is almost infinitely expandable (this is an exaggeration) with extensions and customizability. Luckily, some people smarter than me have also thought to use LaTeX in VS Code, so there are a few tools ready to marry the two. James Yu's LaTeX Workshop is the most popular and my favourite.

Note: VS Code is simply a super powerful text editor that depends on other tools to accomplish tasks. Its plugins are only that; don't skip downloading LaTeX in the step above!

Version Management

Git is probably the standard these days and it comes built in with macOS, most flavours of Linux, and is widely supported by online repositories like GitHub and GitLab. Technically, this step is completely optional, but I would compare it to not only how to ride a bike or drive a car, but also how to change gears.

Steps (Generic but biased towards macOS)

Install BasicTeX (or whichever you want – MikTeX seems to be the most comparable lightweight one for Windows)
Download VS Code
Install LaTeX packages. Necessary and my favourites are:

latexmk
biber (bibtex works too, but I prefer biblatex and biber over it)
TeXcount (to count words, though you can also do this in VS Code)
longtables (multi-page tables)
pdflscape (rotates PDF pages when you define a landscape page)

If you are working with a LaTeX template (like the [TU Delft dissertation one I edited](https://gitlab.com/jasonrwang/dissertation-tudelft-latex)), another approach is to install a compiler (e.g. latexmk) and the package texliveonfly, which will read through the template's defintions (.cls file) and automatically install the packages you are missing.

4. Configure VS Code to work better with LaTeX

https://code.visualstudio.com/docs/getstarted/settings
Install LaTeX Workshop in VS Code (search it in the extensions tab), and latex-count to count words within VS Code (note that this is entirely different from TeXShop or TeXWorks)
Rainbow Brackets for being able to see nested brackets much more clearly!
GitLens to see even more git stuff within VS Code
cSpell for spell check
Define keyboard bindings for bolding and italicizing with this guide (allows ⌘+⇧+to italicize, for example; ⌘+B is used to close the browser in VS Code)

LaTeX Workshop comes with a compiling script, but it's better to set up a file in each LaTeX project's working directory called Makefile that runs latexmk (or you can call this manually in a command line). See my fork of the TU Delft dissertation template for a guide of what a LaTeX project could look like.

If you know your way around a terminal, here's a skeleton of a workflow:

# Update and install LaTeX packages
sudo tlmgr update —self
sudo tlmgr install biber # and others

# Make a new project folder and get VS Code running
cd ~/Documents/Projects
mkdir NewLaTeXProject
git init # Use git to track this project
code ./ # Launch VS Code in this folder (also as the working directory)

# Edit text in VS Code, like in a file called main.tex
make # if Makefile is defined OR...
latexmk main.tex # Turn main.tex into main.pdf!

# Save changes in git and upload (this can also be done in VS Code)
git pull
git add . # Add all changes
git commit -m "Made some changes to ..."
git push # Add it to your online repository

Using LaTeX With an Online Repository

Lastly, I want to make another case for pushing your LaTeX work, tracked through Git, to somewhere online. This has to do with the idea of reproducible science – how can you make sure your code is robust? How can you ensure that you haven't "hacked" something together that will only work on your computer? There are often temporary and auxiliary files left over from LaTeX compiling, especially with citations, and not only the perfectionist in me wants to go one more step to ensure someone else can also run my code, but the general scientist in me too.

Continuous integration and automatic deployment of LaTeX files

A tutorial on how to set-up continuous integration via Travis-CI, and automatic deployment in DropBox for LaTeX files

Lj MirandaLJ MIRANDA

LJ Miranda wrote a guide on their blog on this very matter, and I have configured my own thesis work and the aforementioned TU Delft dissertation template to work in the same way. Every time I "push" (upload) my files to my GitLab repository, it will automatically spin up a mini-server, download a full installation of LaTeX (the 4 GB version), and compile my project into a PDF. If this is successful, it will not only tell me (it also tells me if it fails), but it then commits and pushes that PDF onto the repository too. This workflow essentially simulates someone else, like my supervisors or you, my reader, downloading my files and compiling it just like I have. This helps to guarantee my files work correctly and that I haven't fudged something to make my PDF perfect – it's exactly what the source code has made it out to be. I plan to replicate this for my GitHub version as well soon.