This article describes how to configure GitHub Actions to automatically compile LaTeX sources for a static blog built with tools like make4ht and Jekyll. It covers file tracking, automatic build triggering, and committing generated files back to the repository.

You can find the YAML configuration in the .github/workflows/main.yml file.

Contents

1 Problem: Git and Modification Times
1.1 Restoring Timestamps with GitHub Actions
2 Working with Multiple Branches
3 Compiling LaTeX on GitHub
3.1 Using a Marker File to Trigger Compilation
3.2 Compilation with TexLive Action
4 Committing Generated Files Back to GitHub
5 Configure Github Pages
6 Preventing Infinite Build Loops

1 Problem: Git and Modification Times

Git does not preserve file modification times when cloning or checking out repositories. However, tools like make4ht or other build systems may rely on these timestamps to detect changed files. To compile only updated LaTeX sources, we need to restore original modification times from the commit history.

1.1 Restoring Timestamps with GitHub Actions

We can restore modification times using a custom script that extracts timestamps from git history: 

- name: Restore timestamps
  run: |
    git ls-files -z | while read -d ’’ file; do
      if [ -f "$file" ]; then
        timestamp=$(git log --pretty=format:%cd -n 1 --date=iso -- "$file")
        if [ -n "$timestamp" ]; then
          touch -d "$timestamp" "$file"
        fi
      fi
    done

This requires the full commit history, not just the latest commit. You must ensure the following step is included in your GitHub Actions workflow: 

- uses: actions/checkout@v4
  with:
    fetch-depth: 0

This fetches the complete Git history so the script can determine modification times correctly.

2 Working with Multiple Branches

For better organization, we use two branches:

  • main branch: Contains source LaTeX files and build scripts
  • html branch: Contains generated HTML files served by GitHub Pages

The workflow checks out both branches and synchronizes changes from main to html before compilation.

3 Compiling LaTeX on GitHub

It is possible to run the full LaTeX to HTML compilation process directly on GitHub, without needing to generate files locally.

3.1 Using a Marker File to Trigger Compilation

To control whether a file should be rebuilt, we use a marker file named after the source file with the extension .published. It stores the timestamp of the last successful publication.

It is created automatically if you use the staticsite extension, but you can also create it manually, if you want to compile your file only on Github, without local testing.

For example, for a file named tex_filename.tex, create a corresponding marker file: 

$ date +%s > tex_filename.published

This command stores the current UNIX timestamp in the marker file. The build script on the GitHub server can then compare this value with the file’s modification time to decide whether recompilation is needed.

Whether the .published file was created manually or by the staticsite extension, make sure to commit it to the repository—GitHub Actions needs it to be present during the build.

3.2 Compilation with TexLive Action

The compilation process uses the xu-cheng/texlive-action which provides a full TeX Live environment. The workflow changes to the texposts directory and executes the rebuild.sh script. This script handles the compilation of modified LaTeX documents into HTML format by processing only the files that have changed since the last build, ensuring efficient compilation of large documentation projects.

4 Committing Generated Files Back to GitHub

Every build generates HTML and CSS files, and these are automatically committed to the html branch for publishing with GitHub Pages, using the git-auto-commit-action.

A typical workflow step might look like this: 

- name: Autocommit generated files
  uses: stefanzweifel/git-auto-commit-action@v4
  with:
    commit_message: "Save generated files"
    file_pattern: docs/*
    branch: html
    push_options: --force

This commits and pushes the generated files to the html branch automatically, making them available to GitHub Pages.

5 Configure Github Pages

To configure GitHub Pages to serve content from the docs directory in the html branch, follow these steps:

  1. Open your repository on GitHub.
  2. Navigate to the Settings tab.
  3. In the left-hand menu, select Pages.

  4. Under the Source section:

    • Set the branch to html.
    • Set the folder to /docs.
  5. Click Save.

Accessing your blog

Once GitHub Pages is configured, your blog will be available at:

https://username.github.io/repository-name/

For example, if your GitHub username is janedoe and your repository is named tex-blog, the blog will be published at:

https://janedoe.github.io/tex-blog/

6 Preventing Infinite Build Loops

To prevent infinite build loops when generated files are committed back to the repository, configure the workflow to ignore changes in the docs/ directory: 

on:
  push:
    branches: [main]
    paths-ignore:
      - ’docs/**’

This ensures that commits containing only generated files won’t trigger new workflow runs.