How to Compile Cover Letters with XeLaTeX to Support fontspec

To compile cover letters with XeLaTeX and support the fontspec package, run xelatex -interaction=nonstopmode -output-driver=xdvipdfmx cover_example.tex from the cover_letters/ directory, executing the command twice to resolve all references.

The ai-job-search repository includes a custom LaTeX class located at cover_letters/cover.cls that uses modern OpenType fonts through the fontspec package. Because fontspec requires an engine capable of accessing system fonts, the compilation process must use XeLaTeX rather than traditional pdfLaTeX.

Why XeLaTeX is Required for fontspec

The fontspec package provides an interface for loading OpenType and TrueType fonts in LaTeX documents. Unlike pdfLaTeX, which relies on complex font metric files and limited to 8-bit encodings, XeLaTeX contains the native capability to load system fonts directly. In cover_letters/cover.cls, the class loads the Raleway and Lato font families using \setmainfont with explicit path declarations to the bundled OpenFonts/ directory. This configuration strictly requires an XeTeX-based engine to parse the .otf font files and generate the PDF output.

Prerequisites and Font Setup

Before compiling, ensure you have a complete TeX Live 2023 (or later) installation that includes XeLaTeX and the fontspec package. The repository bundles the necessary fonts internally, so no external font installation is required.

The relevant file structure includes:

• cover_letters/cover.cls – The custom class definition that imports fontspec
• cover_letters/OpenFonts/fonts/raleway/ – Contains Raleway-Regular.otf, Raleway-Bold.otf, and Raleway-Italic.otf
• cover_letters/OpenFonts/fonts/lato/ – Contains the Lato font family variants

Because cover.cls automatically adds the OpenFonts/ path to the font search directories using the Path parameter in \setmainfont, the compilation process finds these fonts without additional configuration.

Step-by-Step Compilation Process

Manual Compilation

Navigate to the cover_letters/ directory and execute XeLaTeX with specific driver flags to ensure proper PDF generation:

cd cover_letters
xelatex -interaction=nonstopmode -output-driver=xdvipdfmx cover_example.tex
xelatex -interaction=nonstopmode -output-driver=xdvipdfmx cover_example.tex

The -interaction=nonstopmode flag prevents the compiler from halting on interactive prompts, while -output-driver=xdvipdfmx ensures the correct PDF backend processes the XeTeX output. Running the command twice resolves cross-references and ensures the table of contents and other dynamic elements are fully populated.

Makefile Automation

For repeated compilations, create a Makefile in the cover_letters/ directory with the following content:

.PHONY: all clean
all: cover.pdf

cover.pdf: cover_example.tex cover.cls
    xelatex -interaction=nonstopmode $<
    xelatex -interaction=nonstopmode $<

clean:
    rm -f *.aux *.log *.pdf *.xdv

Execute make to generate cover.pdf automatically with the required two-pass compilation.

How the cover.cls Class Loads Fonts

The font configuration in cover_letters/cover.cls demonstrates the specific implementation that necessitates XeLaTeX:

\setmainfont[Path=OpenFonts/fonts/raleway/,%
  Extension=.otf,%
  UprightFont=*-Regular,%
  BoldFont=*-Bold,%
  ItalicFont=*-Italic]{Raleway}

This declaration explicitly references the .otf files in the relative path OpenFonts/fonts/raleway/. The fontspec package processes these OpenType font definitions only when using XeLaTeX or LuaLaTeX, as these engines contain the underlying font loader libraries required to parse the OpenType specifications.

Summary

• Use XeLaTeX exclusively when compiling documents that use the cover.cls class, as fontspec requires OpenType font handling capabilities.
• Include the driver flag -output-driver=xdvipdfmx to ensure proper PDF generation from XeTeX output.
• Compile twice to resolve references and generate the final document structure.
• No system font installation is necessary because the repository bundles Raleway and Lato in the OpenFonts/ directory.

Frequently Asked Questions

Can I use LuaLaTeX instead of XeLaTeX?

Yes, LuaLaTeX also supports the fontspec package and can load OpenType fonts. However, the specific compilation examples in the repository target XeLaTeX. If using LuaLaTeX, replace xelatex with lualatex in the commands, though you may omit the -output-driver=xdvipdfmx flag as LuaLaTeX handles PDF generation differently.

Why do I need to run XeLaTeX twice?

The first pass writes auxiliary files containing cross-reference data, page numbers, and other dynamic content. The second pass reads these auxiliary files to resolve references and finalize the layout. If you skip the second compilation, hyperlinks and the table of contents may display incorrectly or as question marks.

Do I need to install the Raleway and Lato fonts system-wide?

No. The cover.cls file uses the Path option in \setmainfont to point directly to the OpenFonts/fonts/ directory within the repository. This self-contained approach means the fonts load from the relative path regardless of whether they are installed in your operating system's font directories.

How do I troubleshoot "font not found" errors?

First, verify you are running XeLaTeX and not pdfLaTeX. Second, confirm you are executing the command from within the cover_letters/ directory so the relative Path=OpenFonts/fonts/raleway/ declaration resolves correctly. If errors persist, check that the OpenFonts/ directory exists and contains the .otf files as committed in the repository.

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