How LaTeX PDF Compilation Works for CVs and Cover Letters Using LuaLaTeX and XeLaTeX

The ai-job-search repository employs LuaLaTeX for CV compilation to circumvent font-expansion bugs in the moderncv class, while mandating XeLaTeX for cover letters to enable system font loading via the fontspec package.

The MadsLorentzen/ai-job-search project provides production-ready LaTeX templates that demonstrate engine-specific PDF generation for job application materials. Understanding how LaTeX PDF compilation leverages LuaLaTeX and XeLaTeX differently ensures your CV and cover letter render with the intended typography and layout constraints.

Engine Selection Strategy

The repository assigns specific engines to each document type based on font handling requirements and package compatibility.

CV Compilation with LuaLaTeX

The CV template (cv/main_example.tex) utilizes the moderncv document class and explicitly recommends the command lualatex main_example.tex (line 6). LuaLaTeX was chosen specifically to avoid font-expansion bugs that frequently occur when using pdfLaTeX with the fontawesome5 package. This engine provides stable font metric calculations for the CV's icon set without requiring system font installation.

Cover Letter Compilation with XeLaTeX

The cover letter template (cover_letters/cover_example.tex) requires XeLaTeX to support the fontspec package, which loads the Raleway-Medium OpenType font from the local file system. Line 6 of the template explicitly enforces XeLaTeX to guarantee a strict single-page layout, while line 40 contains the \fontspec[Path = OpenFonts/fonts/raleway/]{Raleway-Medium} directive that embeds the custom typeface.

Step-by-Step Compilation Flow

The build process follows a consistent workflow from source to PDF:

1. Pre-processing: Replace placeholder tokens (e.g., [YOUR NAME], [Company]) manually or via the provided /setup script.
2. Engine Selection: Invoke lualatex for the CV and xelatex for the cover letter based on their respective font requirements.
3. Document Class Loading: The CV loads \documentclass[11pt,a4paper,sans]{moderncv}, while the cover letter loads \documentclass[]{cover} referencing the custom cover.cls file.
4. Font Resolution: LuaLaTeX processes standard LaTeX fonts for the CV; XeLaTeX locates and embeds the Raleway-Medium OpenType file for the cover letter.
5. PDF Generation: The engine parses macros, resolves cross-references, and outputs the final PDF. The cover letter template enforces a single-page constraint validated by CI tests.

Critical Source Files and Templates

The repository organizes templates by document type with distinct compilation requirements:

• cv/main_example.tex: Master CV template utilizing the moderncv class; must be compiled with LuaLaTeX to avoid font expansion issues with fontawesome5 icons.
• cover_letters/cover_example.tex: Cover letter template requiring XeLaTeX for fontspec support and single-page layout enforcement.
• cover.cls: Custom document class referenced by the cover letter that defines the \lettercontent macro, header/footer styling, and page geometry constraints.

Practical Compilation Commands

Execute these commands from the repository root to generate PDFs:

# Compile CV with LuaLaTeX

cd cv
lualatex main_example.tex

# Compile Cover Letter with XeLaTeX

cd ../cover_letters
xelatex cover_example.tex

Run the command twice if bibliography entries or cross-references need resolution.

Summary

• LuaLaTeX handles the CV in cv/main_example.tex to prevent fontawesome5 rendering issues with moderncv.
• XeLaTeX is mandatory for cover_letters/cover_example.tex to load Raleway-Medium via fontspec and maintain single-page layout.
• The custom cover.cls defines the letter structure, while moderncv manages the CV formatting.
• Both templates support automated processing through the setup script or manual compilation workflows.

Frequently Asked Questions

Why does the CV use LuaLaTeX instead of pdfLaTeX?

The moderncv class combined with the fontawesome5 package generates font-expansion bugs under pdfLaTeX that distort icon rendering. LuaLaTeX processes these font metrics correctly while maintaining PDF/A compatibility, as noted in the template comments at line 6 of cv/main_example.tex.

Can I compile the cover letter with LuaLaTeX instead of XeLaTeX?

While LuaLaTeX technically supports fontspec, the cover letter template explicitly enforces XeLaTeX to ensure consistent single-page layout behavior. The CI pipeline validates that the output PDF contains exactly one page, and XeLaTeX's font handling proves more predictable for this specific typography constraint.

How does the template handle the Raleway-Medium font?

The cover letter loads the font using \fontspec[Path = OpenFonts/fonts/raleway/]{Raleway-Medium} at line 40 of cover_example.tex, requiring XeLaTeX to access the OpenType file system path. This approach embeds the font directly into the PDF without requiring system-wide font installation.

What triggers the single-page restriction for cover letters?

The custom cover.cls class configures geometry and spacing parameters that constrain content to one page, validated by automated tests. This design choice reflects industry standards for cover letter length, enforced through the XeLaTeX compilation process to ensure layout consistency.

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