GitHub Action to compile LaTeX documents.
This actions runs on docker using a maximal TeXLive environment installed.
-
root_file
The root LaTeX file to be compiled. This input is required.
-
working_directory
The working directory for the latex compiler to be invoked.
-
compiler
The LaTeX engine to be used. By default
latexmk
is used.latexmk
automates the process of generating LaTeX documents by issuing the appropriate sequence of commands to be run. -
args
The extra arguments to be passed to the compiler. By default, it is
-pdf -latexoption=-file-line-error -latexoption=-interaction=nonstopmode
. This tellslatexmk
to usepdflatex
. Refer tolatexmk
document for more information. -
extra_system_packages
The extra packages to be installed by
apt-get
separated by space. -
extra_font_packages
The extra fonts such as some chinese fonts, please package them as a ZIP format.
with: extra_font_packages: fonts # means fonts.zip
Note that by default latexmk
is used.
latexmk
automates the process of generating LaTeX documents by issuing the appropriate sequence of commands to be run.
name: Build LaTeX document
on: [push]
jobs:
build_latex:
runs-on: ubuntu-latest
steps:
- name: Set up Git repository
uses: actions/checkout@v2
- name: Compile LaTeX document
uses: dante-ev/latex-action@latest
with:
root_file: main.tex
This is required if one does not trust latexmk and wants to build "by hand"
name: Build LaTeX document
on: [push]
jobs:
build_latex:
runs-on: ubuntu-latest
steps:
- name: Set up Git repository
uses: actions/checkout@v2
- name: example-class-relations--svg
uses: dante-ev/latex-action@latest
with:
root_file: example-class-relations--svg.tex
compiler: lualatex
args: -interaction=nonstopmode -shell-escape
In a "real" document, one would have to encode all steps one after another:
name: Build LaTeX document
on: [push]
jobs:
build_latex:
runs-on: ubuntu-latest
steps:
- name: Set up Git repository
uses: actions/checkout@v2
- name: pdflatex main
uses: dante-ev/latex-action@latest
with:
root_file: main.tex
compiler: pdflatex
args: -interaction=nonstopmode -shell-escape
- name: bibtex main
uses: dante-ev/latex-action@latest
with:
root_file: main.aux
compiler: bibtex
args:
- name: pdflatex main
uses: dante-ev/latex-action@latest
with:
root_file: main.tex
compiler: pdflatex
args: -interaction=nonstopmode -shell-escape
When using a custom shell script for building, one can pass this as follows:
name: Build LaTeX document
on: [push]
jobs:
build_latex:
runs-on: ubuntu-latest
steps:
- name: Set up Git repository
uses: actions/checkout@v2
- name: release.sh
uses: dante-ev/latex-action@latest
with:
entrypoint: ./release.sh
Real life example: https://github.com/koppor/plantuml/blob/main/.github/workflows/build-and-publish.yml
By default, this action uses pdfLaTeX. If you want to use XeLaTeX or LuaLaTeX, you can set the args
to -xelatex -latexoption=-file-line-error -latexoption=-interaction=nonstopmode
or -lualatex -latexoption=-file-line-error -latexoption=-interaction=nonstopmode
respectively. Alternatively, you could create a .latexmkrc
file. Refer to the latexmk
document for more information.
Please mind that it is not recommend to change the compiler
parameter, as the by default used latexmk
has the advantage of determinating the (re)compilation steps automatically and executes them.
To enable --shell-escape
, you should add it to args
. For example, set args
to -pdf -latexoption=-file-line-error -latexoption=-interaction=nonstopmode -latexoption=-shell-escape
when using pdfLaTeX.
The initial code is from xu-cheng/latex-action. The idea there is to initially provide all packages instead of using texliveonfly. Using a full installation, this action also offers to use packages such as pax, which require other tooling such as perl. More reasoning is given in ADR-0002.
You can try to use caching, though be careful as sometimes a LaTeX document needs to be rebuilt completly in order to have a proper result.
Here is an example that rebuilds uses the cache at most once a day. The files to cache are taken from the well-known GitHub .gitignore
templates:
# https://github.com/actions/cache#creating-a-cache-key
# http://man7.org/linux/man-pages/man1/date.1.html
- name: Get Date
id: get-date
run: |
echo "::set-output name=date::$(/bin/date -u "+%Y%m%d")"
shell: bash
- name: Cache
uses: actions/[email protected]
with:
# A list of files, directories, and wildcard patterns to cache and restore
path: |
*.aux
*.lof
*.lot
*.fls
*.out
*.toc
*.fmt
*.fot
*.cb
*.cb2
.*.lb
*.bbl
*.bcf
*.blg
*-blx.aux
*-blx.bib
*.run.xml
key: ${{ runner.os }}-${{ steps.get-date.outputs.date }}
Please use an appropriate GitHub action. One option is upload-artifact, which collects the build artifacts and stores them into a GitHub space. Another option is to use rsync via action-rsyncer.
@latest
points to the latest release of DANTE e.V.'s docker-texlive@edge
is the latest development version of DANTE e.V.'s docker-texlive
MIT