pandoc --pdf-engine: Markdown to PDF in CI

pandoc doc.md -o doc.pdf renders Markdown to PDF, by default shelling out to a LaTeX engine like pdflatex.

Generating a PDF from Markdown in CI is straightforward until the LaTeX toolchain is missing. The --pdf-engine flag and which TeX packages are installed determine success.

What it does

pandoc converts the input to PDF by first producing an intermediate (LaTeX by default) and running a PDF engine on it. The engine defaults to pdflatex; --pdf-engine selects another (xelatex, lualatex, wkhtmltopdf, weasyprint, etc.). LaTeX engines need a TeX distribution installed.

Common usage

Terminal

# default engine (needs pdflatex / TeX Live)
pandoc doc.md -o doc.pdf
# Unicode/system fonts: use xelatex
pandoc doc.md --pdf-engine=xelatex -o doc.pdf
# no LaTeX in the image: render via HTML
pandoc doc.md --pdf-engine=weasyprint -o doc.pdf

Options

Flag	What it does
-o <file>	Output file (format inferred from extension)
--pdf-engine=<eng>	PDF engine: pdflatex, xelatex, lualatex, weasyprint, wkhtmltopdf
-V <key>=<val>	Set a template variable, e.g. -V geometry:margin=1in
--toc	Generate a table of contents
--template=<file>	Use a custom LaTeX/HTML template
-f / -t	Force input/output format

In CI

A full TeX Live install is large; install only what you need (e.g. texlive-latex-recommended texlive-xetex on Debian) or switch to a non-LaTeX engine like weasyprint to avoid the dependency entirely. xelatex handles system fonts and Unicode better than pdflatex.

Common errors in CI

"pandoc: pdflatex not found. Please select a different --pdf-engine or install pdflatex" means no TeX engine is installed; install one or use --pdf-engine=weasyprint. "Error producing PDF ... ! LaTeX Error: File <pkg>.sty' not found" means a missing LaTeX package; install the package or a fuller texlive set. "pandoc: command not found" means pandoc itself is missing (apt-get install -y pandoc). Unicode characters that render as boxes mean the engine lacks the font; switch to xelatex with -V mainfont`.