Building LaTeX to PDF

Sublime Text

For all the years I’ve been using Sublime Text to write my reports in LaTeX, creating a build system had escaped my list of to-dos. Build systems are handy: they enable building (compiling, type-setting) from within Sublime Text. Here are a couple of steps for MacOS:

1. Select Tools > Build System > New Build System… and replace the entire pre-populated JSON instruction with the following:

   {
       "cmd": ["/Library/TeX/texbin/xelatex", "$file"],
       "selector": "text.tex.latex"
   }
   

   To explain the above, I use xelatex as my type-setting system. Finding the path of xelatex is as easy as running a query at command line like so:

   $ which xelatex
   

2. Save it as LaTeX.sublime-build. (It will be saved under the folder ~/Library/Application Support/Sublime Text 3/Packages/User/.)

3. This above allows one to type-set (or build) by pressing ⌘ + B.

A minor wrinkle with the build system is that unlike running xelatex from Terminal, building from within Sublime Text does not recognise artefacts (like class and style files) placed within ~/texmf folder, and so common resources require a full path. Following is an example. Note, e.g., ckunte.sty (style) file has been given a full path like so:

\usepackage{/Users/ckunte/texmf/ckunte}

Same goes for any resource within ~/texmf/ckunte.sty. For instance, I use a custom pythonhighlight.sty within ~/texmf/ckunte.sty. That needs to have a full path as well:

\usepackage{/Users/ckunte/texmf/pythonhighlight}

I am still figuring out how to replicate this on a hybrid system on my work machine with Sublime Text as native app in Windows 10, while xelatex is only accessible via Cygwin. Worst case scenario, I will have to stick to my old ways, which is to write in Sublime Text, and type-set via command line.

Via WSL

Build (using Ctrl+B) is possible via Windows Subsystem for Linux (WSL) v2. My LaTeX.sublime-build looks like so in Windows 10:

{
    "cmd" : ["bash", "-c", "/usr/local/texlive/2022/bin/x86_64-linux/xelatex ${file_name}"],
    "shell" : true,
    "working_dir" : "${file_path}",
    "selector" : "text.tex.latex"
}

For a successful compilation, any user style called must have the full path to custom styles, e.g. \usepackage{/home/ckunte/texmf/ckunte}.

GitHub Actions

Compiling a latex document (or a project) requires an actions workflow. A workflow is a set of instructions to be carried out as actions in a container provided by GitHub. These instructions are to be based inside a subfolder of the repository like so .github/workflows/compile-release.yml, whose contents are as below:

name: Build LaTeX document
on: 
  push:
    tags:
      - "v*.*.*"

jobs:
  build_latex:
    runs-on: ubuntu-latest
    steps:
      - name: Set up Git repository
        uses: actions/checkout@v3
      - name: Compile LaTeX document
        uses: xu-cheng/latex-action@v2
        with:
          root_file: test.tex
          latexmk_use_xelatex: true
      - name: release
        uses: softprops/action-gh-release@v1
        if: startsWith(github.ref, 'refs/tags/')
        with:
          files: |
            test.pdf

To minimise actions for every commit, the build is triggered only when a commit has a tag number attached to it in a format e.g. v1.0.3, and the tag is push to origin — in this case to GitHub.