Streamlining LaTeX Writing: A Guide to Syncing Overleaf, and VimTeX with GitHub

This post, which has stemmed from the necessity to make lecture notes accessible to the students of a course I am TA-ing for, hopes to serve as a practical guide on integrating VimTeX and Overleaf using GitHub for efficient collaboration and writing. The broad goal of this exercise is to equip students with lecture notes, which

1. are accessible over a static link,
2. can be updated by me locally using VimTeX (this article by Gilles Castel explains my obsession with VimTeX),
3. can be proofread by the professor over OverLeaf.

Well, what is wrong with setting up a GitHub-synced Overleaf project with the professor added as a collaborator? This setup allows the changes I make locally to be reflected in the compiled document but has the following cons.

1. It doesn’t address the need to maintain a static link (repeatedly uploading lecture notes to GoogleDrive isn’t the most pleasant chore).
2. The changes made by the professor on Overleaf are only reflected in the compiled document if I have the updates synced to my personal device, compile the .tex file locally, and commit the new document to the main repository (again, not the most pleasant chore).

Fair enough! What’s the solution?

Step 1:

Set up your LaTeX document on Overleaf, add your professor to the project as a collaborator and have the project synced to a GitHub repository. Here’s a guide to that.

Step 2:

Now that you have a GitHub repository, you can commit your local updates (made using your favourite TeX editor, a.k.a VimTeX) to the repository. Goes without saying that updates made via Overleaf can also be committed to the repository.

Step 3:

Finally, we need GitHub to compile the “main” .tex file every time there’s a new commit. We can do this using what’s called a GitHub-Workflow. Make a folder by the name .github/workflows and add the following .yml file to it.

name: Compile LaTeX document

on:
  push:
    branches:
      - main  # Change to your default branch if it's not 'main'

permissions: write-all

jobs:
  build:
    runs-on: ubuntu-latest

    steps:
    - uses: actions/checkout@v4

    - name: Compile LaTeX document
      uses: xu-cheng/latex-action@v3
      with:
        root_file: chapter.tex # Change to your main .tex file if it's not 'chapter.tex'

    - name: Upload PDF file
      uses: actions/upload-artifact@v3
      with:
        name: PDF
        path: chapter.pdf

    - name: Commit and push PDF to repository
      run: |
        git config --global user.name "github-actions[bot]"
        git config --global user.email "github-actions[bot]@users.noreply.github.com"
        git add chapter.pdf # Change to your main .pdf file if it's not 'chapter.pdf'
        git commit -m "Update compiled PDF"
        git push

💡 Pro tip: The compilation on GitHub is pretty slow. If that bugs you, the best you can do is compile locally using a standard TeX compiler (I use MacTeX) for the local commits.

Hope this helps. Happy LaTeX-ing! 🧑‍💻