# How to Compile Cover Letters with XeLaTeX to Support fontspec

> Compile cover letters with XeLaTeX and the fontspec package. Learn the command to automatically generate your documents and resolve all references efficiently.

- Repository: [Mads Lorentzen/ai-job-search](https://github.com/MadsLorentzen/ai-job-search)
- Tags: how-to-guide
- Published: 2026-07-12

---

**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:

```bash
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:

```make
.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:

```latex
\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.