Latex Build

LaTeX Build Automation

Self-Evolving Skill: This skill improves through use. If instructions are wrong, parameters drifted, or a workaround was needed — fix this file immediately, don't defer. Only update for real, reproducible issues.

When to Use This Skill

Use this skill when:

• Compiling LaTeX documents
• Setting up live preview with auto-rebuild
• Managing multi-file projects
• Troubleshooting build failures
• Cleaning build artifacts
• Automating compilation workflows

Quick Reference

Why latexmk?

Industry standard build tool:

• Auto-detects dependencies (bibliography, index, etc.)
• Runs correct number of times (handles cross-references)
• Live preview mode watches for file changes
• Works with Skim for SyncTeX auto-reload
• Bundled with MacTeX (no separate install needed)

---

Basic Usage

One-Time Build

latexmk -pdf document.tex
# Result: document.pdf created

Live Preview (Watch Mode)

latexmk -pvc -pdf document.tex

# What happens:
# - Compiles document initially
# - Watches for file changes
# - Auto-recompiles when files change
# - Auto-reloads PDF in Skim viewer

Stop watching: Press Ctrl+C

---

Quick Reference Card

# Build once
latexmk -pdf document.tex

# Live preview (watch mode)
latexmk -pvc -pdf document.tex

# Build with SyncTeX
latexmk -pdf -synctex=1 document.tex

# Clean artifacts
latexmk -c              # Keep PDF
latexmk -C              # Remove PDF too

# Force rebuild
latexmk -gg -pdf document.tex

# Non-interactive (for CI)
latexmk -pdf -interaction=nonstopmode document.tex

---

Build Checklist

• [ ] Verify latexmk installed: which latexmk
• [ ] Test basic build: latexmk -pdf document.tex
• [ ] Enable SyncTeX: Add -synctex=1 flag
• [ ] Test live preview: latexmk -pvc -pdf document.tex
• [ ] Configure Skim for auto-reload
• [ ] Create Makefile for common tasks (optional)
• [ ] Create .latexmkrc for project-specific settings (optional)
• [ ] Test clean: latexmk -c removes artifacts

---

Reference Documentation

For detailed information, see:

• Common Commands - Build options and output formats
• Multi-File Projects - Automatic dependency tracking for complex documents
• Configuration - .latexmkrc and Makefile integration
• Troubleshooting - Common build issues and solutions
• Advanced Patterns - Parallel builds and CI/CD integration

Official Docs: Run man latexmk or latexmk -help for complete reference

See Also:

• Use latex/setup skill for installing LaTeX and configuring environment
• Use latex/tables skill for creating tables with tabularray

---

Troubleshooting

Post-Execution Reflection

After this skill completes, check before closing:

1. Did the command succeed? — If not, fix the instruction or error table that caused the failure. 2. Did parameters or output change? — If the underlying tool's interface drifted, update Usage examples and Parameters table to match. 3. Was a workaround needed? — If you had to improvise (different flags, extra steps), update this SKILL.md so the next invocation doesn't need the same workaround.

Only update if the issue is real and reproducible — not speculative.

Skill: LaTeX Build Automation

Advanced Patterns

Parallel Builds (Multiple Documents)

# Build all .tex files in directory
latexmk -pdf *.tex

# Watch multiple documents
latexmk -pvc -pdf doc1.tex doc2.tex doc3.tex

Custom Build Script

#!/bin/bash
# build.sh - Custom LaTeX build script

set -e  # Exit on error

echo "Cleaning old build..."
latexmk -C

echo "Building document..."
latexmk -pdf -synctex=1 main.tex

echo "Build complete: main.pdf"
ls -lh main.pdf

CI/CD Integration

# Headless build for CI (no viewer)
latexmk -pdf -interaction=nonstopmode -view=none document.tex

# Check exit code
if [ $? -eq 0 ]; then
  echo "Build successful"
else
  echo "Build failed"
  exit 1
fi

Skill: LaTeX Build Automation

Common Commands

Build Once

# PDF output
latexmk -pdf document.tex

# DVI output
latexmk -dvi document.tex

# PostScript output
latexmk -ps document.tex

Clean Build Artifacts

# Remove auxiliary files (.aux, .log, .synctex.gz, etc.)
latexmk -c

# Also remove PDF output
latexmk -C

# Then rebuild from scratch
latexmk -pdf document.tex

Force Rebuild

# Force rerun of all tools (bibliography, index, etc.)
latexmk -gg -pdf document.tex

Build with Options

/usr/bin/env bash << 'COMMON_COMMANDS_SCRIPT_EOF'
# Enable SyncTeX (for Skim integration)
latexmk -pdf -synctex=1 document.tex

# Use LuaLaTeX instead of pdfLaTeX
latexmk -pdflua document.tex

# Use XeLaTeX
latexmk -pdfxe document.tex

# Verbose output for debugging
latexmk -pdf -verbose document.tex
COMMON_COMMANDS_SCRIPT_EOF

Skill: LaTeX Build Automation

Makefile Integration

Basic Makefile

.PHONY: pdf watch clean

pdf:
	latexmk -pdf main.tex

watch:
	latexmk -pvc -pdf main.tex

clean:
	latexmk -c
	rm -f main.pdf

distclean:
	latexmk -C

Usage

make pdf      # Build once
make watch    # Live preview
make clean    # Remove artifacts

______________________________________________________________________

Configuration (.latexmkrc)

Create .latexmkrc in project directory for custom settings:

Example Configuration

# Use pdflatex by default
$pdf_mode = 1;

# Use lualatex instead
# $pdf_mode = 4;

# Enable SyncTeX
$pdflatex = 'pdflatex -synctex=1 -interaction=nonstopmode %O %S';

# Set PDF viewer (macOS Skim)
$pdf_previewer = 'open -a Skim';

# Continuous mode delay (seconds)
$sleep_time = 1;

# Clean these extensions
@generated_exts = (@generated_exts, 'synctex.gz');

Place in project root, then:

latexmk -pvc main.tex
# Uses settings from .latexmkrc

Evolution Log

Convention: Reverse chronological order (newest on top, oldest at bottom). Prepend new entries.

---

2026-02-26: Initial Evolution Log

Status: Skill is in use and maintained. Track improvements here.

Purpose

This evolution log tracks updates to the skill. Each entry should note:

• What changed (content, structure, tooling)
• Why it changed (bug fix, feature request, best practice)
• Files affected

How to Use

1. When updating SKILL.md or references, add an entry here with the date 2. Keep entries reverse-chronological (newest first) 3. Link to ADRs or GitHub issues when relevant 4. Reference specific line changes when helpful

---

Skill: LaTeX Build Automation

latexmk automatically tracks dependencies!

Project Structure

my-project/
├── main.tex              # Root document
├── chapters/
│   ├── intro.tex
│   ├── methodology.tex
│   └── results.tex
├── figures/
│   └── diagram.pdf
└── bibliography.bib

Root Document (main.tex)

\documentclass{article}
\usepackage{graphicx}

\begin{document}

\input{chapters/intro}
\input{chapters/methodology}
\input{chapters/results}

\bibliographystyle{plain}
\bibliography{bibliography}

\end{document}

Compile Root

# latexmk watches ALL included files
latexmk -pvc -pdf main.tex

# Edit any chapter → automatic rebuild
# Update bibliography.bib → automatic rebuild
# Change figure → automatic rebuild

Skill: LaTeX Build Automation

Troubleshooting

Issue: latexmk Not Found

# Check installation
which latexmk
# Should show: /Library/TeX/texbin/latexmk

# If not found, ensure MacTeX installed
brew install --cask mactex

# Or add to PATH
export PATH="/Library/TeX/texbin:$PATH"

Issue: PDF Not Auto-Reloading in Skim

Check Skim preferences:

1. Skim → Preferences → Sync 1. Check "Check for file changes" 1. Check "Reload automatically"

Verify SyncTeX enabled:

latexmk -pdf -synctex=1 document.tex
# Should create document.synctex.gz

Issue: Build Hangs on Error

# Use non-interactive mode
latexmk -pdf -interaction=nonstopmode document.tex

# Or in .latexmkrc:
$pdflatex = 'pdflatex -interaction=nonstopmode %O %S';

Issue: Bibliography Not Updating

# Force rebuild of all dependencies
latexmk -gg -pdf document.tex

# Or clean and rebuild
latexmk -C && latexmk -pdf document.tex

Issue: Compilation Errors Not Showing

# Use verbose mode
latexmk -pdf -verbose document.tex

# Check log file
less document.log

Issue: Stale Auxiliary Files

# Clean all build artifacts
latexmk -C

# Rebuild from scratch
latexmk -pdf document.tex