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 Compiling LaTeX on GitHub
2.1 Using a Marker File to Trigger Compilation
3 Committing Generated Files Back to GitHub
4 Configure Github Pages

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

The git-restore-mtime-action can be used to recover accurate modification times for files in a GitHub workflow.

To function correctly, it 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@v2
  with:
    fetch-depth: 0

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

2 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.

2.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 Committing Generated Files Back to GitHub

Every build generates HTML and CSS files, and these are automatically committed to the repository for publishing (e.g., with GitHub Pages), using the git-auto-commit-action.

A typical workflow step might look like this: 

- uses: stefanzweifel/git-auto-commit-action@v5
  with:
    commit_message: "Update generated HTML files"
    branch: main

This commits and pushes the generated files to the main branch automatically, making them available to GitHub Pages or other deployment mechanisms.

After each build, it’s important to pull the latest changes from GitHub into your local repository. These changes include newly generated or updated files (e.g., in docs/_posts/) that were committed automatically by the GitHub Actions workflow.

If you also generate the same output files locally, there is a risk of merge conflicts, since your local versions may differ from the ones produced on the server (even if logically equivalent).

4 Configure Github Pages

To configure GitHub Pages to serve content from the docs directory in the main 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 main.
    • 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/