You ⌘-click a line in the PDF and the editor lands three pages away. Or nothing happens at all. SyncTeX is one of those features that either works invisibly or fails confusingly, with not much in between.
Here’s what it’s actually doing, and the four reasons it goes wrong.
What SyncTeX is
When TeX typesets your document, it normally throws away the connection between source and output. A line of .tex becomes ink on a page and the relationship is forgotten.
SyncTeX keeps a record of it. Compile with the flag on and you get a .synctex.gz file next to your PDF — a compressed map from source positions to page coordinates, and back. Your editor reads that map to answer two questions: “the cursor is on line 412, where is that in the PDF?” (forward search) and “the user clicked here on page 87, where did it come from?” (inverse search).
Everything that goes wrong is a problem with that map — it’s missing, it’s stale, or it points somewhere your editor can’t follow.
Nothing happens at all
The map doesn’t exist. Check the folder your PDF is in — if there’s no .synctex.gz (or an uncompressed .synctex), the flag isn’t on. Add it to your compile command:
xelatex -synctex=1 main.texWith latexmk, add it to the engine options rather than latexmk itself:
latexmk -pdf -pdflatex="pdflatex -synctex=1 -interaction=nonstopmode" main.texOne thing that catches people: some build scripts clean aux files afterwards and sweep the .synctex.gz away with them. If the file appears during the build and vanishes when it finishes, that’s your culprit.
It jumps, but to the wrong line
The map is stale. It describes the document as it was at the last compile, and you’ve edited since. Add twenty lines near the top and every position below shifts by twenty — SyncTeX has no idea.
Rebuild and the offset disappears. If it persists after a clean rebuild, the map is genuinely confused rather than out of date, which usually means one of the cases below.
It lands in the wrong file
This is the multi-file case, and it’s where editors differ most.
SyncTeX itself handles it fine. The map records which file each piece of text came from, so a paragraph pulled in through \include{chapters/ch7} is tagged as belonging to ch7.tex, not to main.tex. The information is there.
What varies is whether your editor acts on it. Some read only the file they compiled and land you at the corresponding line of main.tex — which is meaningless, since main.tex is forty lines of preamble and a list of includes. Others open the right file but lose the build target, so your next ⌘B tries to compile a chapter with no \documentclass.
If your jumps consistently land in the root file, that’s not SyncTeX failing. That’s the editor ignoring what the map already knows.
The paths are wrong
Rarer, but worth knowing. The map stores file paths as TeX saw them at compile time, relative to the working directory. If you compile from one directory and open the PDF from another — a build script that cds somewhere, an output directory set with -output-directory, a project moved after building — the paths no longer resolve.
Symptom: jumps work for the root file but silently fail for anything included. Fix: compile from the directory your source lives in, or rebuild in place after moving things.
How texspark handles it
The default build commands in texspark include -synctex=1, so the map is there without you thinking about it, and builds run in the build target’s own directory — which keeps the recorded paths resolvable.
For the multi-file case: ⌘-clicking the PDF opens the sub-file the text actually came from, at the right line, however many \include levels deep it sits. The build target stays on your project root, so ⌘B from that sub-file still compiles the whole document. Forward search (⌘⇧↩) works the same way in reverse, from any chapter.
If something here doesn’t match what you’re seeing, email support@texspark.io — it goes straight to the developer.
Leave a Reply