Why LuaLaTeX Is Used for CVs and XeLaTeX for Cover Letters in ai-job-search

The ai-job-search repository compiles CVs with LuaLaTeX to avoid font-expansion errors with the fontawesome5 package, while cover letters require XeLaTeX because the cover.cls template depends on fontspec for custom system fonts.

When generating application documents, this repository explicitly separates LaTeX engines by document type. The distinction ensures reliable compilation across different LaTeX distributions, particularly MiKTeX, while supporting modern font features required by each template.

Why LuaLaTeX Is Required for CV Compilation

The CV template relies on the moderncv document class coupled with the fontawesome5 icon font. Standard pdfLaTeX often crashes when processing these Unicode-heavy OpenType fonts.

The Fontawesome5 Font-Expansion Problem

On recent MiKTeX installations, pdflatex frequently fails with font-expansion errors when rendering fontawesome5 glyphs. According to README.md at line 67, "pdflatex often fails on modern MiKTeX installs with fontawesome5 font-expansion errors". LuaLaTeX handles modern Unicode fonts and OpenType features natively, bypassing these specific rendering crashes.

ModernCV Class and Unicode Font Handling

LuaLaTeX processes the stock CV sources located in cv/main_example.tex without the micro-typography issues that plague pdfLaTeX. The engine provides clean access to font expansion and rendering logic required by the moderncv class, making it the default choice for the curriculum vitae pipeline as documented in SETUP.md around line 53.

Why XeLaTeX Is Required for Cover Letters

The cover letter template uses a custom class file that imports system fonts unavailable to traditional LaTeX engines.

Fontspec Dependency in cover.cls

The file cover_letters/cover_example.tex invokes cover.cls, which loads the fontspec package. As noted in SETUP.md, "the cover letter compiles with xelatex because cover.cls requires fontspec". This package mandates an engine capable of understanding system font paths and Unicode encoding—functionality provided by XeLaTeX (or LuaLaTeX, though the project standardizes on XeLaTeX here).

Custom Font Requirements (Lato/Raley)

The cover letter design specifically imports the Lato and Raleway font families. These custom system fonts require the fontspec interface to map TrueType/OpenType files correctly within the document structure, a capability XeLaTeX handles reliably for this specific template architecture.

CI/CD Implementation and Build Commands

The continuous integration pipeline enforces these engine choices through explicit job definitions in .github/workflows/ci.yml (lines 148–161).

To compile documents locally using the repository's prescribed methods:

# Compile the CV with LuaLaTeX

cd cv && lualatex -interaction=nonstopmode -halt-on-error main_example.tex && cd ..

# Compile the cover letter with XeLaTeX

cd cover_letters && xelatex -interaction=nonstopmode -halt-on-error cover_example.tex && cd ..

The CI workflow mirrors these commands exactly, ensuring that cv/main_example.tex always processes through lualatex and cover_letters/cover_example.tex through xelatex to prevent build failures.

Key Configuration Files

Understanding the engine selection requires examining these specific source files:

• cv/main_example.tex – Sample CV source requiring LuaLaTeX for fontawesome5 compatibility
• cover_letters/cover_example.tex – Cover letter source requiring XeLaTeX due to fontspec usage
• SETUP.md – Documents the rationale and compilation commands (line 53)
• .github/workflows/ci.yml – Enforces engine-specific builds (lines 148–161)

Summary

• LuaLaTeX is selected for CV compilation to avoid fontawesome5 font-expansion crashes that occur with pdfLaTeX on modern MiKTeX systems.
• XeLaTeX is required for cover letters because cover.cls uses fontspec to load custom system fonts like Lato and Raleway.
• The CI pipeline explicitly separates build commands in .github/workflows/ci.yml to maintain these requirements.

Frequently Asked Questions

Can I use pdfLaTeX instead of LuaLaTeX for the CV?

No. According to the repository documentation in README.md, pdfLaTeX often fails on modern MiKTeX installations due to font-expansion errors when processing the fontawesome5 icon font used by the moderncv class. LuaLaTeX handles these modern Unicode fonts without errors.

Why doesn't the cover letter use LuaLaTeX instead of XeLaTeX?

While LuaLaTeX also supports fontspec, the cover.cls template was written with XeLaTeX-specific assumptions and conventions. The repository standardizes on XeLaTeX for cover letters to ensure consistent rendering of the Lato and Raleway custom fonts across different environments.

Where are the compilation commands defined in the repository?

The build commands are documented in SETUP.md around line 53 and enforced programmatically in .github/workflows/ci.yml at lines 148–161. The CI workflow explicitly calls lualatex for cv/main_example.tex and xelatex for cover_letters/cover_example.tex.

What fonts cause issues with pdfLaTeX in this setup?

The fontawesome5 icon font causes font-expansion errors when compiled with pdfLaTeX, particularly on recent MiKTeX distributions. Additionally, the cover letter's reliance on system fonts (Lato and Raleway) through fontspec makes pdfLaTeX incompatible for that document type as well.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}