October 2, 2026

Making LaTeX scroll sync work with SyncTeX

SyncTeX can jump between source and PDF. We turned its position data into a continuous scroll map, and had to deal with the floats and footnotes that break the raw mapping.

A LaTeX source file and its PDF do not share a coordinate system. One source line can fill several lines on a page, or run over onto the next one. A figure can end up pages away from the line that declared it, and a footnote lands above the paragraph that mentions it.

SyncTeX records where every piece of source ended up in the PDF. Most editors use it for one discrete action: click in one view, jump to the matching place in the other. We wanted the PDF to follow along while you scroll the source. That sounds like a small extension, but the raw SyncTeX records are not a map you can interpolate directly.

Below is the real thing: model_architecture.tex from Attention Is All You Need, 155 lines, compiled with pdfLaTeX. SyncTeX gives us 77 anchors across pages 2 to 6. Drag the slider to see where TeXposit sends the PDF, then switch to the raw sequence.

model_architecture.tex: 77 anchors, pages 2 to 6

Source lines mapped to positions in the PDF77 SyncTeX anchors from one source file connect line numbers to positions across five stacked pages. The monotonic curve drops 16 anchors that land earlier in the PDF than the previous kept one. The selected source line links to its interpolated position.Source linePDF, pages stacked to scale020406080100120140160page 2page 3page 4page 5page 6
kept anchor (61) dropped as out of order (16)

line 60.0 = lines 59 to 82 at t=0.04 → page 4, y=639.2 bp

60.0

Line 60 is a \begin{figure}. LaTeX floats it to the top of page 4, above text from lines 36 to 59. Interpolating the raw anchors, line 60 maps to page 4, y=452, while line 59 sits at y=638. Scroll down one line in the editor and the PDF jumps up by 187 points, almost a quarter of a page. In this file 16 of the 77 anchors do that.

Turn positions into a curve

For each source line that produced visible content, we take a SyncTeX leaf record and store its source line, PDF page and vertical position. That gives us the anchors. In plain prose, sorting them by source line also sorts them in PDF order, but floats, footnotes and margin notes break that.

So we build a monotonic curve. We walk the anchors in source order, keep the ones that continue forward through page and vertical position, and drop the ones that go backward. Then we interpolate between what is left. In the demo that keeps 61 anchors and drops 16, and lines 59 to 82, 23 lines of figure markup, now map to a 19 point move. The curve is blind around a skipped point, but a blind spot beats a jumpy PDF.

We interpolate over fractional source lines, not whole ones. TeXposit finds the line at the centre of the editor viewport, works out how far through that line the centre sits, and uses that fraction between two anchors. On the PDF side we measure the rendered page geometry instead of assuming a page height, so the mapping holds at any zoom level and with mixed page sizes.

We first tried the browser's native smooth scrolling for the PDF. It ran at about 60 frames per second for its whole duration, pdf.js re-rendered the visible pages on every tick, and since the viewer is a same-origin iframe it shares the main thread with Monaco. The editor lagged, and Firefox silently fell back to an instant jump on that container. Now the update is throttled to once every 100 ms, and each one runs a short 280 ms animation of plain scroll position writes that is identical in every browser.

Keep the map with its PDF

TeXposit has two compile paths. The server produces the full LaTeX preview, and Live Preview compiles in the browser with WebAssembly (the Live Preview guide covers when each one is used). Every PDF needs the SyncTeX data from its own compile. Pair a newer browser PDF with an older server mapping and a click lands on the wrong line.

The browser path parses the SyncTeX data that came with its PDF. The server path reads the compressed .synctex.gz on the backend, and the browser fetches that map once per file and caches it. Both produce the same line, page and position anchors, so scroll sync works with either preview.

SyncTeX has another gap. Many engines report a line but no useful column, and the synctex command-line tool can't reliably tell which word on a line you clicked. We parse the raw records ourselves and use their emitted order to estimate the word. Sorting them by x-coordinate looks like the obvious fix, but it scrambles any line that wraps across several visual lines. It is still an estimate, only a tighter one than highlighting the whole line.

Recompile one chapter, keep the whole book

The same page mapping solves a different problem in Live Preview. Once a full book has rendered, an edit inside an \included chapter can compile just that chapter. SyncTeX gives us the chapter's old page range in the full render and its new range in the scoped one, and we splice the new pages into the existing PDF. You keep looking at the whole book instead of a standalone chapter.

This only works when both mappings identify the chapter. If they don't, or the splice fails, we fall back to a full compile rather than show a partial PDF as if it were the whole book. It handles \include chapters, not arbitrary edits to any part of any document.

Where the map still gets rough

Dropping an anchor means less detail around it, and complicated floats can drop a lot. The word position is an estimate, and pages behave differently across engines and layouts. We would like to keep more anchors around floats without letting the curve go backward, which is harder than it sounds. Next up is trying a few approaches on more real books.

Using SyncTeX records as a scroll map takes some extra work, but it gives us measured positions instead of a guess based on document length. The interesting cases are still the ones where reading order and page layout disagree.