GitHub Action to compile LaTeX documents.
It runs in a docker container with a full TeXLive environment installed.
If you want to run arbitrary commands in a TeXLive environment, use texlive-action instead.
Each input is provided as a key inside the with section of the action.
-
root_fileThe root LaTeX file to be compiled. This input is required. You can also pass multiple files as a multi-line string to compile multiple documents. Each file path will be interpreted as bash glob pattern. For example:
- uses: xu-cheng/latex-action@v3 with: root_file: | file1.tex file2.tex
-
working_directoryThe working directory for this action.
-
work_in_root_file_dirChange directory into each root file's directory before compiling each documents. This will be helpful if you want to build multiple documents and have the compiler work in each of the corresponding directories.
-
continue_on_errorContinuing to build document even with LaTeX build errors. This will be helpful if you want to build multiple documents regardless of any build error. Noted that even with this input set, this action will always report failure upon any build error. If you want to prevent the GitHub action job also from failure, please refer to the upstream document.
-
compilerThe LaTeX engine to be invoked. By default,
latexmkis used, which automates the process of generating LaTeX documents by issuing the appropriate sequence of commands to be run. -
argsThe extra arguments to be passed to the LaTeX engine. By default, it is
-pdf -file-line-error -halt-on-error -interaction=nonstopmode. This tellslatexmkto usepdflatex. Refer tolatexmkdocument for more information. -
extra_system_packagesThe extra packages to be installed by
apkseparated by space. For example,extra_system_packages: "inkscape"will install the packageinkscapeto allow using SVG images in your LaTeX document. -
extra_fontsInstall extra
.ttf/.otffonts to be used byfontspec. You can also pass multiple files as a multi-line string. Each file path will be interpreted as bash glob pattern. For example:- uses: xu-cheng/latex-action@v3 with: root_file: main.tex extra_fonts: | ./path/to/custom.ttf ./fonts/*.otf
-
pre_compileArbitrary bash codes to be executed before compiling LaTeX documents. For example,
pre_compile: "tlmgr update --self && tlmgr update --all"to update all TeXLive packages. -
post_compileArbitrary bash codes to be executed after compiling LaTeX documents. For example,
post_compile: "latexmk -c"to clean up temporary files. -
texlive_versionThe version of TeXLive to be used. Supported inputs include 2020, 2021, 2022, 2023, 2024, and latest. By default the latest TeXLive is used. This input cannot co-exist with
docker_imageinput. An example to use this input:- uses: xu-cheng/latex-action@v3 with: root_file: main.tex texlive_version: 2022
-
docker_imageCustom which docker image to be used. Only latex-docker images are supported. For example if you want to pin the docker image:
- uses: xu-cheng/latex-action@v3 with: root_file: main.tex docker_image: ghcr.io/xu-cheng/texlive-full:20230801
The following inputs are only valid if the input compiler is not changed.
-
latexmk_shell_escapeInstruct
latexmkto enable--shell-escape. -
latexmk_use_lualatexInstruct
latexmkto use LuaLaTeX. -
latexmk_use_xelatexInstruct
latexmkto use XeLaTeX.
name: Build LaTeX document
on: [push]
jobs:
build_latex:
runs-on: ubuntu-latest
steps:
- name: Set up Git repository
uses: actions/checkout@v4
- name: Compile LaTeX document
uses: xu-cheng/latex-action@v3
with:
root_file: main.tex
- name: Upload PDF file
uses: actions/upload-artifact@v4
with:
name: PDF
path: main.pdfBy default, this action uses pdfLaTeX. If you want to use XeLaTeX or LuaLaTeX, you can set the latexmk_use_xelatex or latexmk_use_lualatex input respectively. For example:
- uses: xu-cheng/latex-action@v3
with:
root_file: main.tex
latexmk_use_xelatex: true- uses: xu-cheng/latex-action@v3
with:
root_file: main.tex
latexmk_use_lualatex: trueAlternatively, you could create a .latexmkrc file. Refer to the latexmk document for more information.
To enable --shell-escape, set the latexmk_shell_escape input.
- uses: xu-cheng/latex-action@v3
with:
root_file: main.tex
latexmk_shell_escape: trueThe PDF file will be in the same folder as that of the LaTeX source in the CI environment. It is up to you on whether to upload it to some places. Here are some example.
-
You can use
@actions/upload-artifactto upload a zip containing the PDF file to the workflow tab. For example you can add- uses: actions/upload-artifact@v4 with: name: PDF path: main.pdf
It will result in a
PDF.zipbeing uploaded withmain.pdfcontained inside. -
You can use
@softprops/action-gh-releaseto upload PDF file to the Github Release. -
You can use normal shell tools such as
scp/git/rsyncto upload PDF file anywhere. For example, you can git push to thegh-pagesbranch in your repo, so you can view the document using Github Pages.
Sometimes you may have custom package (.sty) or class (.cls) files in other directories. If you want to add these directories to the LaTeX input search path, you can add them in TEXINPUTS environment variable. For example:
- name: Download custom template
run: |
curl -OL https://example.com/custom_template.zip
unzip custom_template.zip
- uses: xu-cheng/latex-action@v3
with:
root_file: main.tex
env:
TEXINPUTS: ".:./custom_template//:"Noted that you should NOT use {{ github.workspace }} or $GITHUB_WORKSPACE in TEXINPUTS. This action works in a separated docker container, where the workspace directory is mounted into it. Therefore, the workspace directory inside the docker container is different from github.workspace.
You can find more information of TEXINPUTS here.
This is an upstream issue where xindy.x86_64-linuxmusl is currently missing in TeXLive. To work around it, try this.
- Try to solve the problem by examining the build log.
- Try to build the document locally.
- You can also try to narrow the problem by creating a minimal working example to reproduce the problem.
- Open an issue if you need help. Please include a minimal working example to demonstrate your problem.
MIT
React
Typescript
Django
Laravel
Facebook
Microsoft
Google
Alibaba
D3
Tencent