LaTeX rarely finishes in one pass. Cross-references need a second run. A bibliography needs BibTeX in between. An index needs makeindex. If you’ve been running these by hand in Terminal — or clicking through a sequence of menu items — this guide sets it up as a single ⌘B.
Why more than one pass
A quick refresher, because knowing why makes the command obvious:
On the first run, LaTeX doesn’t yet know what page Section 3 lands on, so \ref and \cite come out as ??. It writes what it learned into .aux. BibTeX (or makeindex) then reads those files and produces .bbl (or .ind). A second LaTeX run picks those up — and sometimes a third is needed, because inserting the bibliography shifts page numbers, which changes the references again.
Hence: run, process, run, run.
The command box
Open Preferences (⌘,) → Compile. You’ll find one-click templates for the usual engines — xelatex, pdflatex, lualatex, latexmk, BibTeX, makeindex — which is the fastest way to get a working build.
But the templates only fill in the command box; they don’t lock it. The field itself is fully editable, so you can start from a template and modify it, or ignore them entirely and type your own pipeline from scratch. Anything your shell can run, texspark can run. Steps chain with && — meaning each step runs only if the previous one succeeded, so a failure stops the chain instead of cascading nonsense.
Two tokens get substituted before the command reaches the shell:
{file} → main.tex (build target with extension){filename} → main (without extension)
Both are shell-escaped, so spaces in your path won’t break anything. The command runs in the build target’s directory.
Recipes
Bibliography (BibTeX):
xelatex -synctex=1 {file} && bibtex {filename} && xelatex -synctex=1 {file} && xelatex -synctex=1 {file}
Note that BibTeX takes {filename} — no extension — while LaTeX takes {file}. Getting this backwards is the single most common mistake here.
Index (makeindex):
xelatex -synctex=1 {file} && makeindex {filename} && xelatex -synctex=1 {file}
Both, for a book:
xelatex -synctex=1 {file} && bibtex {filename} && makeindex {filename} && xelatex -synctex=1 {file} && xelatex -synctex=1 {file}
Or let latexmk figure it out:
latexmk -xelatex -synctex=1 -interaction=nonstopmode {file}
latexmk decides how many passes are needed and runs BibTeX when appropriate. If your project is standard, this is the least fussy option — and texspark keeps your PDF scroll position through all of latexmk’s rewrites, so a five-pass rebuild doesn’t fling you back to page one.
Keep -synctex=1
Every LaTeX invocation in the chain should carry -synctex=1. That’s what produces the .synctex.gz file next to your PDF, which is what makes ⌘⇧↩ and ⌘-click work. Drop it from the final pass and forward/inverse search quietly stops working.
When a step fails
The chain stops at the first failure, and the bottom panel switches to Issues automatically. Click any error row to jump to the offending line — in the right sub-file, not just the build target.
Two things worth knowing:
- BibTeX errors don’t always surface as LaTeX errors. If your bibliography comes out empty, check the Log tab (next to Terminal and Issues) for BibTeX’s own complaints — a missing
.bib entry usually shows up there.
- If a run leaves things in a strange state, ⌘⇧⌫ sweeps the build directory clean of
.aux, .bbl, .ind, .toc, and friends, leaving your .tex and .pdf alone. Then build fresh.
One target, any chapter
Worth restating: mark your project root as the build target (⌘⇧P) and this chain runs against it no matter which chapter you’re editing. Multi-pass builds and multi-file projects were the two things that used to make me alt-tab to Terminal. Now they’re one keystroke.