latex-action
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.
Inputs
Each input is provided as a key inside the with
section of the action.
-
root_file
The 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. For example:
- uses: xu-cheng/latex-action@v2 with: root_file: | file1.tex file2.tex
-
glob_root_file
If set, interpret the
root_file
input as bash glob pattern. For example:- uses: xu-cheng/latex-action@v2 with: root_file: "*.tex" glob_root_file: true
-
working_directory
The working directory for this action.
-
work_in_root_file_dir
Change 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_error
Continuing 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.
-
compiler
The LaTeX engine to be invoked. By default,
latexmk
is used, which 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 LaTeX engine. By default, it is
-pdf -file-line-error -halt-on-error -interaction=nonstopmode
. This tellslatexmk
to usepdflatex
. Refer tolatexmk
document for more information. -
extra_system_packages
The extra packages to be installed by
apk
separated by space. For example,extra_system_packages: "inkscape"
will install the packageinkscape
to allow using SVG images in your LaTeX document. -
extra_fonts
Install extra
.ttf
/.otf
fonts to be used byfontspec
. You can also pass multiple files as a multi-line string. Each file path will be interpreted as glob pattern. For example:- uses: xu-cheng/latex-action@v2 with: root_file: main.tex extra_fonts: | ./path/to/custom.ttf ./fonts/*.otf
-
pre_compile
Arbitrary 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_compile
Arbitrary bash codes to be executed after compiling LaTeX documents. For example,
post_compile: "latexmk -c"
to clean up temporary files.
The following inputs are only valid if the input compiler
is not changed.
-
latexmk_shell_escape
Instruct
latexmk
to enable--shell-escape
. -
latexmk_use_lualatex
Instruct
latexmk
to use LuaLaTeX. -
latexmk_use_xelatex
Instruct
latexmk
to use XeLaTeX.
Example
name: Build LaTeX document
on: [push]
jobs:
build_latex:
runs-on: ubuntu-latest
steps:
- name: Set up Git repository
uses: actions/checkout@v3
- name: Compile LaTeX document
uses: xu-cheng/latex-action@v2
with:
root_file: main.tex
- name: Upload PDF file
uses: actions/upload-artifact@v3
with:
name: PDF
path: main.pdf
FAQs
How to use XeLaTeX or LuaLaTeX instead of pdfLaTeX?
By 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@v2
with:
root_file: main.tex
latexmk_use_xelatex: true
- uses: xu-cheng/latex-action@v2
with:
root_file: main.tex
latexmk_use_lualatex: true
Alternatively, you could create a .latexmkrc
file. Refer to the latexmk
document for more information.
--shell-escape
?
How to enable To enable --shell-escape
, set the latexmk_shell_escape
input.
- uses: xu-cheng/latex-action@v2
with:
root_file: main.tex
latexmk_shell_escape: true
Where is the PDF file? How to upload it?
The 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-artifact
to upload a zip containing the PDF file to the workflow tab. For example you can add- uses: actions/upload-artifact@v3 with: name: PDF path: main.pdf
It will result in a
PDF.zip
being uploaded withmain.pdf
contained inside. -
You can use
@softprops/action-gh-release
to upload PDF file to the Github Release. -
You can use normal shell tools such as
scp
/git
/rsync
to upload PDF file anywhere. For example, you can git push to thegh-pages
branch in your repo, so you can view the document using Github Pages.
How to add additional paths to the LaTeX input search path?
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@v2
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.
How to use old versions of TeXLive?
By default, this action always uses the latest docker image that contains the latest TeXLive updates. If you want to use old versions of TeXLive, you can change the action version tag accordingly. Currently, three last old versions of TeXLive are supported.
- uses: xu-cheng/latex-action@v2 # TeXLive 2023
- uses: xu-cheng/latex-action@v2-texlive2022 # TeXLive 2022
- uses: xu-cheng/latex-action@v2-texlive2021 # TeXLive 2021
- uses: xu-cheng/latex-action@v2-texlive2020 # TeXLive 2020
xindy
cannot be found.
It fails due to This is an upstream issue where xindy.x86_64-linuxmusl
is currently missing in TeXLive. To work around it, try this.
It fails to build the document, how to solve it?
- 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.
License
MIT