Latex Setup

LaTeX Environment Setup

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:

• Installing LaTeX on a new machine
• Setting up MacTeX distribution
• Configuring Skim PDF viewer with SyncTeX
• Verifying LaTeX installation
• Troubleshooting missing packages

Quick Reference

Recommended Stack

---

Quick Start

Install MacTeX

brew install --cask mactex
# Size: ~4.5 GB (includes everything)

Verify Installation

tex --version
# Expected: TeX 3.141592653 (TeX Live 2025)

pdflatex --version
latexmk --version

Test Compilation

echo '\documentclass{article}\begin{document}Hello World!\end{document}' > test.tex
pdflatex test.tex
ls test.pdf  # Verify PDF created

---

Post-Installation Checklist

• [ ] Verify tex --version shows TeX Live 2025
• [ ] Verify latexmk --version shows 4.86a+
• [ ] Verify pdflatex test.tex creates PDF
• [ ] Install Skim if using mactex-no-gui
• [ ] Test SyncTeX: compile with -synctex=1 flag
• [ ] Configure Skim preferences for editor integration
• [ ] Add /Library/TeX/texbin to PATH if needed
• [ ] Test package installation: sudo tlmgr install <package>

---

Reference Documentation

For detailed information, see:

• Installation - Full MacTeX vs lightweight options, Skim installation
• Verification - Check installation, verify PATH, test compilation
• Package Management - Check, install, search for packages with tlmgr
• Skim Configuration - Enable SyncTeX, configure preferences for editor integration
• Troubleshooting - PATH issues, tlmgr problems, permissions

See Also:

• Build Workflows: Use latex/build skill for latexmk automation
• Table Creation: Use latex/tables skill for tabularray usage

---

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.

Modern LaTeX Workflow for macOS (2025)

Purpose: Production-ready LaTeX stack for professional PDF generation with perfect table alignment

Status: ✅ Installed and configured (October 2025)

______________________________________________________________________

Stack Overview

______________________________________________________________________

Why This Stack?

latexmk

• Auto-detects dependencies, runs correct number of times
• Continuous preview mode (-pvc) watches files
• Actively maintained (latest Dec 2024)
• Industry standard, bundled with MacTeX

Skim

• Only macOS viewer with full SyncTeX support
• Auto-reloads when PDF changes
• Forward/inverse search (click PDF ↔ LaTeX source)
• Open source, actively maintained

TeXShop

• Native macOS integrated IDE
• Editor + viewer in one window
• One-click typesetting
• Bundled with MacTeX

tabularray

• Modern LaTeX3 package
• Replaces old packages (tabular, tabularx, longtable, booktabs)
• Critical: Proper fixed-width column support

______________________________________________________________________

Installation

1. Install MacTeX

brew install --cask mactex-no-gui

After installation, update PATH:

/usr/bin/env bash << 'REFERENCE_SCRIPT_EOF'
eval "$(/usr/libexec/path_helper)"
REFERENCE_SCRIPT_EOF

Verify:

which pdflatex
# Should output: /Library/TeX/texbin/pdflatex

2. Install Skim

brew install --cask skim

Configure auto-reload:

defaults write -app Skim SKAutoReloadFileUpdate -boolean true

3. Install TeXShop (Optional but Recommended)

brew install --cask texshop

______________________________________________________________________

Configuration

Create .latexmkrc in Project Directory

# latexmk configuration for macOS with Skim

# Use pdflatex by default
$pdf_mode = 1;

# Use Skim as PDF previewer
$pdf_previewer = 'open -a Skim';

# Enable synctex for forward/inverse search
$pdflatex = '/Library/TeX/texbin/pdflatex -synctex=1 -interaction=nonstopmode %O %S';

# Continuous preview update method
$preview_continuous_mode = 1;

# Clean up auxiliary files
$clean_ext = 'synctex.gz synctex.gz(busy) run.xml tex.bbl bcf fdb_latexmk run tdo %R-blx.bib';

# Extra options
$bibtex_use = 2;  # Run bibtex/biber when needed
$force_mode = 1;  # Force completion even with errors

Global config: Copy to ~/.latexmkrc for all projects

______________________________________________________________________

Usage

Workflow 1: latexmk + Skim (Terminal-based)

Start continuous preview:

cd /path/to/project
latexmk -pdf -pvc document.tex

This will:

1. Compile your document 1. Open it in Skim 1. Watch for changes and auto-recompile 1. Skim auto-updates when PDF changes

Edit in Helix/VS Code/any editor

• Save file → automatic recompilation (typically \<1 second)
• Skim updates instantly

Stop watching:

# Press Ctrl+C in terminal

One-time compilation:

latexmk -pdf document.tex

Clean auxiliary files:

latexmk -c document.tex  # Keep PDF
latexmk -C document.tex  # Remove PDF too

______________________________________________________________________

Workflow 2: TeXShop (Integrated IDE)

1. Open .tex file in TeXShop 1. Two windows appear: Editor (left) + PDF preview (right) 1. Click "Typeset" button (or Cmd+T) 1. Preview updates automatically

Advantages:

• All-in-one solution
• No terminal needed
• Native macOS experience

Disadvantages:

• Manual typesetting (not continuous)
• Less flexible than Helix/VS Code

______________________________________________________________________

Table Alignment: Critical Best Practices

❌ WRONG: Using X-columns with fixed width

\begin{tblr}{
  colspec={X[4.8cm,l]X[1,l]},  % BROKEN - X-columns are flexible!
}

Problem: X-columns ignore fixed widths in narrow containers (minipage), causing misalignment.

✅ CORRECT: Using p-columns for fixed width

% Define width once
\newlength{\shortcutcolwidth}
\setlength{\shortcutcolwidth}{3.8cm}

\begin{tblr}{
  colspec={p{\shortcutcolwidth}X[l]},  % CORRECT - p{} guarantees width
  row{1}={font=\bfseries},
  hline{2}={0.5pt},
  rowsep=2pt,
}
  Shortcut & Action \\
  \texttt{Cmd+N} & New Window \\
  \texttt{Cmd+Q} & Quit \\
\end{tblr}

Why this works:

• p{3.8cm} = absolute fixed width, honored regardless of content
• X[l] = flexible width, takes remaining space
• All tables using same \shortcutcolwidth = perfect alignment

Key Principles

1. Use `p{width}` for columns that must align vertically 1. Use `X[align]` for flexible columns 1. Define widths with `\newlength` for consistency 1. Never use `X[width,align]` syntax - it's unreliable

______________________________________________________________________

SyncTeX: Forward and Inverse Search

Forward Search: LaTeX → PDF

Command line:

displayline <line-number> <pdf-file> <tex-file>

Example:

displayline 42 document.pdf document.tex

This highlights the PDF location for line 42 in your .tex file.

Inverse Search: PDF → LaTeX

In Skim:

1. Cmd+Shift+Click on any text in PDF 1. Your editor jumps to corresponding line in .tex file

Configuration (Skim → Preferences → Sync):

• Preset: Custom
• Command: /opt/homebrew/bin/hx (for Helix)
• Arguments: %file:%line

______________________________________________________________________

Editor Integration

Helix

Add to ~/.config/helix/languages.toml:

[[language]]
name = "latex"
auto-format = false
formatter = { command = "latexindent", args = ["-"] }

[language-server.texlab.config.build]
executable = "latexmk"
args = ["-pdf", "-interaction=nonstopmode", "-synctex=1", "%f"]

[language-server.texlab.config.forwardSearch]
executable = "displayline"
args = ["%l", "%p", "%f"]

VS Code

Install: LaTeX Workshop extension

• Auto-compiles with latexmk
• Built-in SyncTeX
• 10M+ downloads

Vim/Neovim

Use: VimTeX plugin

• Full latexmk integration
• SyncTeX with Skim works out-of-box

______________________________________________________________________

Common LaTeX Packages for Cheat Sheets

\documentclass[8pt,landscape]{extarticle}
\usepackage[margin=0.4in]{geometry}
\usepackage{tabularray}          % Modern tables
\usepackage{charter}             % Professional serif font for print
\usepackage[scaled=0.95]{helvet} % Helvetica for headers
\usepackage[T1]{fontenc}         % Better font encoding
\usepackage{microtype}           % Micro-typography improvements
\usepackage{xcolor}              % Colors

% Tabularray booktabs integration
\UseTblrLibrary{booktabs}

% No page numbers
\pagestyle{empty}

______________________________________________________________________

Troubleshooting

Skim not auto-reloading

Fix:

defaults write -app Skim SKAutoReloadFileUpdate -boolean true

Or: Skim → Preferences → Sync → "Check for file changes" enabled

latexmk can't find pdflatex

Fix: Use absolute path in .latexmkrc:

$pdflatex = '/Library/TeX/texbin/pdflatex -synctex=1 -interaction=nonstopmode %O %S';

Compilation errors

Check log file:

tail -50 document.log

Tables misaligned

Symptom: "shortcut" text appearing in tables, columns not aligned

Cause: Using X[width,l] or problematic theme names

Fix: Use p{width}X[l] pattern (see Table Alignment section)

Force clean rebuild

latexmk -C document.tex  # Remove all generated files
latexmk -pdf -pvc document.tex  # Rebuild from scratch

______________________________________________________________________

Version Control: .gitignore for LaTeX

# LaTeX auxiliary files
*.aux
*.fdb_latexmk
*.fls
*.log
*.out
*.synctex.gz
*.synctex.gz(busy)
*.toc
*.lof
*.lot
*.bbl
*.blg
*.bcf
*.run.xml

# Keep configuration
!.latexmkrc

______________________________________________________________________

Resources

• latexmk manual: texdoc latexmk or https://ctan.org/pkg/latexmk
• Skim homepage: https://skim-app.sourceforge.io/
• tabularray manual: texdoc tabularray or https://ctan.org/pkg/tabularray
• SyncTeX docs: texdoc synctex
• TeXShop: Bundled documentation in Help menu

______________________________________________________________________

Real-World Example: iTerm2 Cheat Sheet

Files:

• Source: /tmp/iTerm2-keybindings-fixed.tex
• Config: /tmp/.latexmkrc
• Output: ~/Downloads/iTerm2-keybindings-FIXED.pdf

Key features:

• Landscape US Letter (11×8.5")
• 3-column layout with minipages
• 12 tables with perfect vertical alignment
• Charter font (8pt) for readability
• All shortcuts in fixed-width p{3.8cm} columns

Workflow:

cd /tmp
latexmk -pdf -pvc iTerm2-keybindings-fixed.tex

Edit in Helix → Save → See changes in \<1 second

______________________________________________________________________

Summary

This LaTeX workflow provides:

✅ Fast: Compilation typically \<1 second ✅ Precise: Pixel-perfect table alignment with tabularray ✅ Interactive: SyncTeX forward/inverse search ✅ Future-proof: All tools actively maintained (2024-2025) ✅ Standard: Industry-standard toolchain ✅ Free: 100% open-source

Bottom line: Professional PDF generation with reliable table alignment, unlike Typst's broken X-column implementation.

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 Environment Setup

Installation

Option 1: Full MacTeX (Recommended)

# Download from mactex.org
# Or install via Homebrew:
brew install --cask mactex

# Size: ~4.5 GB (includes everything)
# Includes: TeX Live 2025, TeXShop, BibDesk, LaTeXiT, Skim

Option 2: Lightweight (No GUI Tools)

# Smaller install without GUI tools
brew install mactex-no-gui

# Size: ~2 GB
# Includes: TeX Live 2025, latexmk, but no TeXShop/BibDesk

Install Skim Separately (if using no-gui)

brew install --cask skim

# Why Skim?
# - ONLY macOS PDF viewer with full SyncTeX support
# - Forward search: LaTeX source → PDF location
# - Inverse search: PDF → LaTeX source
# - Auto-reload on PDF changes

Skill: LaTeX Environment Setup

Package Management

Check if Package Installed

# Use kpsewhich to find package
kpsewhich tabularray.sty
# If found: /usr/local/texlive/2025/texmf-dist/tex/latex/tabularray/tabularray.sty
# If not found: (empty output)

Install Missing Package

# Update TeX Live package manager
sudo tlmgr update --self

# Install specific package
sudo tlmgr install tabularray

# Verify installation
kpsewhich tabularray.sty

Search for Packages

# Search for package by name
tlmgr search --global tabularray

# List all installed packages
tlmgr list --only-installed

Skill: LaTeX Environment Setup

Skim Configuration

Enable SyncTeX

In LaTeX compilation:

# Add -synctex=1 flag
pdflatex -synctex=1 document.tex

# Or use latexmk (automatically enables SyncTeX)
latexmk -pdf document.tex

Skim Preferences

1. Skim → Preferences → Sync 1. Preset: Custom 1. Command: Path to editor executable 1. Arguments: Depends on editor (e.g., for VS Code: --goto %file:%line)

For Helix:

Command: /usr/local/bin/hx
Arguments: %file:%line

Skill: LaTeX Environment Setup

Troubleshooting

Issue: TeX binaries not in PATH

# Add to ~/.zshrc or ~/.bash_profile
export PATH="/Library/TeX/texbin:$PATH"

# Reload shell
source ~/.zshrc

Issue: sudo required for tlmgr

# This is normal for system-wide MacTeX installation
# Use sudo for package management:
sudo tlmgr install <package>

Issue: Package not found

# Update tlmgr database
sudo tlmgr update --self --all

# Search for package
tlmgr search --global <package-name>

# Install
sudo tlmgr install <package-name>

Issue: Permission errors

/usr/bin/env bash << 'TROUBLESHOOTING_SCRIPT_EOF'
# Fix permissions on TeX Live directory
sudo chown -R $(whoami):staff /usr/local/texlive/2025/texmf-var
TROUBLESHOOTING_SCRIPT_EOF

Skill: LaTeX Environment Setup

Verification

Check Installation

# Check TeX version
tex --version
# Expected: TeX 3.141592653 (TeX Live 2025)

# Check pdflatex
pdflatex --version

# Check latexmk
latexmk --version
# Expected: Latexmk, John Collins, version 4.86a

Verify PATH

# TeX binaries should be in PATH
which pdflatex
# Expected: /Library/TeX/texbin/pdflatex

# Check environment
echo $PATH | grep -o '/Library/TeX/texbin'

Test Basic Compilation

# Create test document
cat > test.tex <<'EOF'
\documentclass{article}
\begin{document}
Hello World!
\end{document}
EOF

# Compile
pdflatex test.tex

# Verify PDF created
ls test.pdf