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.
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.
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.
For better organization, we use two branches:
The workflow checks out both branches and synchronizes changes from main to html before compilation.
It is possible to run the full LaTeX to HTML compilation process directly on GitHub, without needing to generate files locally.
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.
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.
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.
To configure GitHub Pages to serve content from the docs directory in the html branch, follow these steps:
Under the Source section:
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/
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.
]]>I’ve shown how to use the make4ht staticsite extension in the previous article. In this article, I’ll show how to set it up with Jekyll to create a simple blog.
We assume that the HTML files generated from LaTeX using make4ht are stored in a directory called docs. The LaTeX source files will be located in the _posts subdirectory. You can initialize a new Jekyll site in the docs directory using the following commands:
$ cd docs $ jekyll new .
This command creates a new Jekyll site in the current directory without overwriting existing files.
To improve how Jekyll handles the content, update the _config.yml file with the following options:
show_excerpts: true excerpt_separator: "</p>"
This enables post excerpts and specifies that the excerpt ends at the first closing paragraph tag.
You can modify the default HTML layout by editing files in the _includes and _layouts folders. For example, create a custom layout that uses the styles and metadata provided by your LaTeX output.
Edit the file:
_includes/head.html
In the head.html file, make sure to include both the default Jekyll styles and any additional styles generated by make4ht. Here’s an example of a complete <head> section:
<head>
<meta charset="utf-8">
<meta http-equiv="X-UA-Compatible" content="IE=edge">
<meta name="viewport" content="width=device-width, initial-scale=1">
{%- seo -%}
<link rel="stylesheet" href="{{ "/assets/main.css" | relative_url }}" />
{% for style in page.styles %}
<link rel="stylesheet" href="/css/{{style}}" />
{%- endfor -%}
{%- feed_meta -%}
{%- if jekyll.environment == ’production’ and site.google_analytics -%}
{%- include google-analytics.html -%}
{%- endif -%}
</head>
The loop over page.styles allows for the dynamic inclusion of CSS files exported during the LaTeX to HTML conversion.
To generate clean HTML that is compatible with Jekyll, use the staticsite extension of make4ht. I’ve described how to use it in the previous post.
Using make4ht together with Jekyll allows you to write blog posts in LaTeX while benefiting from static site generation.
]]>This post is part of a series on how to set up TeX4ht, the LaTeX to XML converter, for use with Static Site Generators. In this article, we’ll discuss how to configure it to produce suitable HTML.
The conversion process used by TeX4ht is quite complex. It requires compiling a LaTeX file to a DVI file with special instructions inserted by the tex4ht.sty package. This DVI file is then processed by the tex4ht command, which produces HTML or XML files, along with instructions for the final command, t4ht, which generates CSS files and images.
Traditionally, this process was handled by the htlatex script, but it had many weaknesses. The currently recommended build tool is make4ht. You can find some details about the differences between htlatex and make4ht in the make4ht documentation.
Among the features provided by make4ht are Lua build files, post-processing filters, and extensions. We can use these features to transform HTML files produced by TeX4ht into the format required by static site generators.
Filters can clean up the generated files and fix common issues that are difficult to address at the TeX level. They can be applied either from Lua build files or using make4ht extensions.
make4ht provides an extension that specifically supports static site generators. Let’s demonstrate its usage with a simple example:
\documentclass{article}
\begin{document}
\title{Hello world test}
\author{Michal}
\maketitle
This is my test post.
\end{document}
You can use the following command to generate a file suitable for static site generators:
make4ht -f html5+staticsite filename.tex
By default, the staticsite extension produces a file named as
YYYY-MM-DD-<filename>, so this example might be named 2021-07-25-filename.html.
It’s not an ordinary HTML file, but it contains a YAML header with document
metadata:
--- meta: - charset: ’utf-8’ - name: ’generator’ content: ’TeX4ht (https://tug.org/tex4ht/)’ - name: ’viewport’ content: ’width=device-width,initial-scale=1’ - name: ’src’ content: ’2021-07-18-hello-world.tex’ time: 1626619562 updated: 1627244699 styles: - ’2021-07-18-hello-world.css’ title: ’Hello world test’ --- <p class=’indent’> This is my test post. </p>
Although most static site generators expect Markdown, they also accept HTML files in this format. When staticsite is used for the first time, it creates a file with a .published extension. This file contains a timestamp of the moment it was first used. This timestamp is then used for the date part of the generated filename.
The staticsite extension can copy the generated files to the locations where the static site generator expects to find files to process.
Let’s say we have the following directory structure, suitable for the Jekyll static site generator:
blog/ .. texposts_root/ .... first_post/ ...... first_post.tex .... second_post/ ...... second_post.tex .. docs/_posts/ .. .make4ht
The blog’s main directory contains the file .make4ht, and two directories:
texposts_root and docs/_posts. Jekyll has built-in support for blogs. It uses all
HTML documents contained within the _posts subdirectory. We’ll then use the docs
directory as the source directory for GitHub Pages.
The source LaTeX files are stored in subdirectories of texposts_root. We
want to automatically copy the generated HTML files to docs/_posts/.
The staticsite extension can be configured to do this using the .make4ht
configuration file. This file is used to pass shared configuration to make4ht, such as
specifying that all generated files should be copied to the docs/_posts/
directory.
The basic format of the .make4ht file necessary for the staticsite extension can look like this:
filter_settings "staticsite" {
site_root = "../../docs/_posts/"
header = {
layout="post",
},
}
if mode=="publish" then
Make:enable_extension "staticsite"
Make:htlatex {}
Make:htlatex {}
end
The filter_settings function passes a table with settings for the extension. The
site_root field specifies the path to the directory for the generated files. It can be
specified in a relative form, as in this example. Two .. are necessary because the
output directory is located two levels up in the directory hierarchy from the directory
of the compiled TeX file.
We also specify the build sequence for site generation. If we pass the
--mode publish option to make4ht, the staticsite extension will be enabled, and
LaTeX will be executed twice. This is important because the contents of the \title
and \author commands are only available in the second LaTeX run. They are then
included in the YAML header.
You can now execute the following command in the texposts_root/first_post
directory:
make4ht -m publish first_post.tex
This will automatically load the staticsite extension, thanks to our .make4ht
file, so it’s not necessary to enable it on the command line. The generated HTML and
CSS files will be placed in the docs/_posts/ directory.
In the next post, we will look at how to use this setup with Jekyll to create a simple blog.
The .make4ht file provided in this blog repository also adds a new function that
writes a <input>.published file. This file is used by the staticsite extension to
find the original publication date of a post. You should add the published file to
your source repository so the correct date is used in future updates of the
site.
Instead of compiling documents manually after each change, you can automate the build process using the siterebuild script.
This tool checks all TeX files in your document directory tree for changes and lists only the modified files. This is especially important as your blog grows, as it would be wasteful to compile all source files on every update.
I’ve provided a shell script named rebuild.sh, which is included in the TeX files root directory. It uses siterebuild to automatically compile the changed TeX files:
#!/bin/sh if ! command -v siterebuild &> /dev/null then SITEREBUILD=../siterebuild/siterebuild else SITEREBUILD=siterebuild fi export TEXINPUTS=.:/root/texmf//: $SITEREBUILD -l debug # we use the custom output format for siterebuild, to be able to easily extract directory and filename in the later steps for i in ‘$SITEREBUILD -o %dir@%file‘ do texdir=‘echo $i | cut -d@ -f1 -‘ texfile=‘echo $i | cut -d@ -f2 -‘ # either execute Makefile, or run make4ht directly cd "$texdir" if test -f Makefile; then make else TEXINPUTS=.:/root/texmf//: make4ht -a debug -m publish -l "$texfile" fi cd .. done
It first checks for the availability of the siterebuild command, using either a system-wide installation or a local version from the repository. The script then executes siterebuild with debug logging to identify modified LaTeX files that require recompilation.
Using a custom output format (%dir@%file), it extracts both the directory path
and filename for each changed document. For each detected file, the script navigates
to the corresponding directory and checks for a Makefile. If one is present, it uses
the existing build system; otherwise, it directly invokes make4ht with publishing
options to generate the HTML output.
If you want to change the options for make4ht used for the compilation, you can edit the rebuild.sh file. If you want to change options for only one file, you can create a Makefile in that file’s directory and put the necessary compilation commands in that Makefile.
]]>This is the first post in a series about blogging with LaTeX using TeX4ht. I originally set it up as a showcase of TeX4ht’s features for the TUG 2021 conference. Unfortunately, I didn’t get to present it in the end—I ran out of time during my allocated slot, and I also didn’t manage to finish all the posts I had planned by the deadline. Fast forward to July 2025, and I thought, why not finally complete this series? Better late than never, right?
I really enjoy writing my documents in LaTeX, and I want to offer a solid alternative to other markup languages like Markdown or HTML. The beauty of LaTeX lies in its incredible flexibility—it lets you structure your documents exactly how you want, without being tied down by the limitations of more rigid systems. Whether you’re writing a quick report or a full-blown book, LaTeX gives you the tools to make it look polished and professional.
Of course, LaTeX isn’t for everyone, and that’s totally fine! Some people prefer the instant visual feedback you get with WYSIWYG editors like Word or Google Docs, and there’s absolutely nothing wrong with that. Others might like the simplicity of plain text but find LaTeX’s syntax too complicated or even a bit ugly—and hey, that’s fair too. Markdown and other lightweight markup languages are great alternatives, and there’s no shame in using them.
Let’s be honest, LaTeX can be pretty complex, and a lot of people won’t even scratch the surface of what it can do. And that’s okay—not everyone needs that level of control or customization. Personally, though, I’ve never been a fan of Word or Markdown. Word feels too restrictive for my taste, and Markdown, while simple, just doesn’t give me the power I need. That’s why I’ve turned to LaTeX as my go-to tool. It’s my way of creating an alternative for myself and others who feel the same way—people who want more flexibility and precision without being tied down by the limitations of other tools.
One of the coolest things about LaTeX is how customizable it is. You can create your own environments and commands, which is a game-changer when it comes to organizing your content. This is super handy for big projects like theses or books, where you need everything to be consistent, but it’s also great for smaller stuff like articles or essays. Plus, once you’ve set up your custom commands, you can reuse them across different documents, saving you a ton of time.
Another reason I love LaTeX is the sheer number of packages available. These packages let you do pretty much anything you can think of. Need to draw diagrams? Check out TikZ or PGFPlots. Writing a math-heavy paper? Amsmath has got your back. Managing references? BibLaTeX makes it a breeze. The possibilities are endless, and it’s one of the reasons LaTeX is so powerful.
Now, some people say that converting LaTeX to HTML is a pain, but honestly, it’s not that hard if you know what you’re doing. I’m the author of TeX4ht, a tool that makes this process a lot smoother. It’s a great way to make your content more accessible online without losing the precision and beauty of LaTeX.
In the upcoming posts, we’ll dive into how TeX4ht works and how to configure it to generate HTML files that play nicely with static site generators. After that, I’ll share how I used Jekyll to build this series of posts. Finally, we’ll wrap things up by exploring how to use GitHub Actions to automatically rebuild your website whenever you update your LaTeX documents.
Here is an outline of the steps we’ll cover:
If you’re curious to check out the source code for this blog, you can find it at this link: https://github.com/michal-h21/testblog.
Notable files and directories include: