Chapter 4
Automated HTML Output
This chapter explains how GitHub Actions is used to automatically generate and
publish an HTML version of the handout whenever changes are pushed to the main
branch.
The output is built using make4ht and published to the gh-pages branch, making it easy to share a web-readable version of the talk.
Key parts of the workflow that builds and publishes the HTML:
- name: Run make4ht
uses: xu-cheng/texlive-action/full@v1
with:
run: |
make4ht -lj index -a debug -d out book.tex
- name: Publish the web pages
uses: peaceiris/actions-gh-pages@v3
with:
github_token: ${{ secrets.GITHUB_TOKEN }}
publish_dir: ./out
The workflow is defined in the .github/workflows/main.yml file. You can edit this file to customize the build process, such as changing the options passed to make4ht.
It uses two GitHub Actions: xu-cheng/texlive-action and peaceiris/actions-gh-pages. The first one lets you use any command available in the TeX Live installation, such as make4ht or lualatex. The second one publishes the contents of a specified directory to the gh-pages branch of your repository, which is used by GitHub Pages to serve static content.
4.1 Automatic HTML Build
Changes pushed to main branch trigger a GitHub Actions workflow that:
- Compiles handout.tex to HTML using make4ht
- Publishes the output to the gh-pages branch
The following command is used for the compilation:
make4ht -lj index -a debug -d out handout.tex
This builds the HTML into the out/ folder, which is then published using the peaceiris/actions-gh-pages action, specified by the publish_dir setting.
- The -lj index option is a shorthand for -l -j index
- The -j index option sets the HTML output filename to index.html
-
This lets you use clean URLs like:
https://username.github.io/repo/
There’s no need to specify the filename in the link — GitHub Pages automatically looks for index.html by default. This makes it easier to share the presentation and helps avoid broken links due to filename mismatches.
For example, this book is available at: https://michal-h21.github.io/tex4ht-booksite/.