A workflow for LaTeX projects in GitHub

Continuous Integration and a preview deployment for LaTeX documents

Finishing my Bachelor Thesis I worked with a large LaTeX document spanning multiple files and throughout multiple documents. I did not find a very good solution about how to compile LaTeX Documents locally the best way even though there are very simple and convenient ways. Reproducing the build process on other devices without an unpleasent install of texlive on every device and having build checks on commits to Pull Requests are useful for collaboration and managing complexity. With the template repository I am aiming to solve the following Problems:

• Setup of a great beginner-friendly LaTeX IDE
• Checking build of LaTeX project on commits
• Managing multiple LaTeX documents in one repository
• Enabling Reviewers to always get the latest version of the documents

Setting up your IDE

I find it very useful to write LaTeX Documents in a development environment that has a split screen view where I can see the code on the left and the compiled PDF on the right. For years, I worked with the LaTeX editor Gummi. For my Thesis I wanted to set up a real IDE, so I could handle all my codebase in one place.

I read multiple tutorials how to set up VSCode with LaTeX workshop the best. I work from multiple machines with different operating systems all the time, so the setup should not be too complicated. Most helpful for me was this Tutorial about how to set up LaTeX with VSCode and Docker. This tutorial makes use of the VSCode extension LaTeX Workshop and a Docker image. The docker image is used by the extension to compile the LaTeX project instead of a local installation of texlive. This makes it much easier to handle different installations and versions.

Using the VSCode workspace setting configurations with the files .vscode/settings and vscode/extensions I preconfigured the tools to work out of the box using pdflatex (which I found to be the most standard compiler).

Continuous checks on commits

When committing the LaTeX code to the repo you want to make sure everything works also on the other machines. This is why I included GitHub actions that use the same docker image that is used locally to compile the LaTeX documents also in the commit checks on every commit on a Pull Request. To save GitHub Action runner minutes only LaTeX projects that have been changed in a PR will be checked.

The success of a build will be indicated by a green check mark. If there were problems during the build a red x will be displayed.

Releasing documents continuously

The template repo enables you to share the most recent version with a link at all times. Not just in the release section of the repo there is a download link to the newest version on the main branch as a PDF. There is even a GitHub Pages static website that can automatically be deployed with every release. Here the newest version is embedded as HTML and will be immediately displayed in a compatible browser.

This enables you to show progress fast also to non-technical reviewers that might not have the time or knowledge to check out your project and build it themselves to read your Documents.