Clean TeX Setup on macOS

Context

I regularly use Quarto and pandoc for converting markdown to PDF, but just got a new Mac. Time to set up the TeX ecosystem properly from scratch.

Installing BasicTeX

brew install --cask basictex

Why BasicTeX instead of MacTeX?

• Size: ~90MB vs 4GB
• Sufficient: provides the TeX engines and package manager needed for pandoc/Quarto
• Focused: avoids GUI apps and specialized packages I don’t need

Why Homebrew instead of Quarto’s TinyTeX?

• System-wide: both pandoc and Quarto share the same installation
• No duplication: single install vs. multiple TeX distributions
• PATH simplicity: Homebrew handles it automatically

After installation, refresh your PATH and update the package manager:

# Refresh PATH to find new TeX binaries
eval "$(/usr/libexec/path_helper)"

# Update the TeX package manager
sudo tlmgr update --self
sudo tlmgr update --all

# Set reliable mirror
sudo tlmgr option repository ctan

Note

brew upgrade updates the BasicTeX distribution itself (released annually). Individual TeX packages are updated separately with sudo tlmgr update --all.

Adding Packages

BasicTeX is minimal by design. You will need to install additional packages as you go. Start with what pandoc needs for syntax highlighting and code block line wrapping:

sudo tlmgr install framed fvextra

You will likely hit missing-package errors as your documents grow more complex. They look like this:

! LaTeX Error: File 'bookmark.sty' not found.

The .sty filename tells you what to install. The fix is always the same:

sudo tlmgr install bookmark

Common additions include bookmark, upquote, xurl, and microtype. Install them as errors arise rather than trying to anticipate everything up front.

Pandoc Configuration

Use lualatex, Not pdflatex

Use lualatex as the PDF engine:

--pdf-engine=lualatex

Why?

• Native Unicode support (Latin Extended, box-drawing characters, common symbols)
• System font access on macOS
• Better microtypography support via the microtype package
• Recommended by the LaTeX Project for all new documents

Note

TeX engines handle Latin scripts and common symbols well, but struggle with CJK, Arabic, and emoji. If your documents need broad Unicode coverage, consider Typst as a PDF engine instead - pandoc supports it via --pdf-engine=typst, and it handles emoji and full Unicode natively.

xelatex also handles Unicode and system fonts, but lualatex is the current standard and what Quarto defaults to as of v1.8.

Code Block Line Wrapping

Create header.tex for automatic code wrapping:

\usepackage{fvextra}
\DefineVerbatimEnvironment{Highlighting}{Verbatim}{
  breaklines,
  breakanywhere,
  breaksymbol=,
  commandchars=\\\{\}
}

Without this, long commands, URLs, or code lines overflow page margins. This wraps them while preserving syntax highlighting.

Complete Pandoc Command

pandoc document.md -o document.pdf \
  --pdf-engine=lualatex \
  --syntax-highlighting=tango \
  -V geometry:margin=1in \
  -V fontsize=11pt \
  -V colorlinks=true \
  -V linkcolor=blue \
  -V urlcolor=blue \
  -V mainfont="Palatino" \
  -V monofont="Menlo" \
  --include-in-header=header.tex

Design choices:

• lualatex: Unicode and system font support
• Palatino: ships with macOS, immediately distinguishable from the default LaTeX look. Alternatives: Georgia, Baskerville, Charter
• tango: clean syntax highlighting (alternatives: pygments, kate, espresso)
• 1in margins: standard, readable
• 11pt font: more readable than default 10pt
• Colored links: better UX than boxed links
• Menlo monospace: native macOS font with good Unicode coverage
• header.tex: enables code wrapping

For common conversions, save this as an executable script or alias.

Quarto Configuration

For Quarto projects, the same settings go in YAML front matter instead of command-line flags:

format:
  pdf:
    pdf-engine: lualatex
    highlight-style: tango
    mainfont: "Palatino"
    monofont: "Menlo"
    fontsize: 11pt
    geometry: margin=1in
    colorlinks: true
    linkcolor: blue
    urlcolor: blue
    include-in-header:
      text: |
        \usepackage{fvextra}
        \DefineVerbatimEnvironment{Highlighting}{Verbatim}{
          breaklines,
          breakanywhere,
          breaksymbol=,
          commandchars=\\\{\}
        }

Quarto defaults to lualatex as of v1.8, so the pdf-engine line is optional but explicit.

Troubleshooting

# Check TeX is found
which lualatex
# Should show: /Library/TeX/texbin/lualatex

# Check engine version
lualatex --version

# Quarto should auto-detect it
quarto check

Resources

• Quarto PDF Engines
• Quarto PDF Basics (YAML configuration reference)
• TUG BasicTeX