macOS and Linux

A PDF viewer for your terminal that reloads on every build.

Run it in a pane next to your editor while you write LaTeX.

~/paper
Page 1 of the compiled sample paper, Heat Flow in a Thin Rod

Illustration of your editor and termleaf paper.pdf in two panes. The page is a real render of the source.

Features

Live reload

When latexmk -pvc, texlab or tectonic writes the PDF, termleaf redraws it on the same page.

Broken builds

If a build leaves the PDF broken, termleaf keeps showing the last good page.

Image rendering

MuPDF renders each page, and termleaf draws it with Kitty graphics, Sixel or iTerm2 images.

Keys and mouse

Vim keys move between pages, and the mouse scrolls, zooms and follows links.

Install

termleaf runs on macOS and Linux. Download the latest release.

Installs a prebuilt binary from the backyardbit tap.

$ brew install backyardbit/tap/termleaf
Usage
$ termleaf thesis.pdf

The file must exist when termleaf starts.

Terminal support

termleaf needs a terminal that can show images. It picks the protocol from what the terminal reports.

TerminalProtocolScrolling
Kitty, GhosttyKitty graphicssmooth
herdr inside Kitty or GhosttyKitty graphicssmooth
foot, xterm -ti vt340, mlterm, Windows Terminal (from WSL or SSH)Sixelrepaints the page area
tmux 3.6 or later built with Sixel, inside a Sixel terminalSixelrepaints the page area
WezTerm, iTerm2, KonsoleiTerm2 imagesrepaints the page area

With Kitty graphics, each piece of a page is sent once and scrolling only moves it. Sixel and iTerm2 images are one picture of the whole page area, sent again on every scroll, zoom and page change, which is slower, especially over SSH. --graphics kitty|sixel|iterm2 overrides the choice. In other terminals, termleaf exits with an error.

Keys and mouse

Keyboard
KeyAction
j / knext / previous page (takes a count, e.g. 5j)
Ctrl-D / Ctrl-Uscroll down / up half a pane (takes a count)
PgDn / PgUpscroll down / up a whole pane (takes a count)
↓ / ↑scroll down / up three rows (takes a count)
h / l, ← / →pan left / right (takes a count)
gg / Gfirst / last page
<n>G <n>gg :<n>go to page n
:$last page
+ / -zoom in / out (= also zooms in; takes a count)
s / afit width / fit page
eopen the source line under the pointer in your editor
/, then Entersearch PDF text
n / Nnext / previous match, wrapping at the ends (counts work)
Esccancel a search prompt, or dismiss search results
Ctrl-O / Ctrl-I (or Tab)jump back / forward through links followed, gg, G, :<n>, search matches and the table of contents (takes a count)
tshow / hide the table of contents (j / k move, Enter jumps, t, q or Esc close)
F :follow :nofollowfollow your editor on / off
q :q Ctrl-Cquit
Mouse
InputAction
wheelscroll
shift + wheel, sideways swipepan left / right
Ctrl + wheelzoom at the pointer
dragpan
clickfollow a link (\ref, citations, table of contents), or open a web or mail link (\url, \href) in your browser
double-clickswitch between fit width and fit page
Alt + click, Ctrl + clickopen the source line under the click in your editor
pinchzoom at the pointer

Pinch to zoom needs an OS permission. On macOS, the terminal app needs Input Monitoring. On Linux, your user must be in the input group. termleaf --no-pinch turns it off. Details are in the README.

SyncTeX

Build with -synctex=1 (for example latexmk -pdf -synctex=1 -pvc). e or Alt + click opens the source line in your editor. Follow is on by default: as you move through a .tex file, termleaf shows the page with your cursor's line. F, :follow and :nofollow switch it, and termleaf --no-follow starts with it off.

EditorInverse searchFollowSetup
Neovimover its RPC socketover its RPC socketnone
Helixtyped keys, in a multiplexerreads its statusline, in a multiplexernone
Vimtyped keys, in a multiplexerthe Vim snippetcontrib/termleaf.vim, for follow only

Multiplexers: tmux, herdr, zellij 0.44 or later, GNU screen, kitty windows (with remote control on) and WezTerm panes. The editor runs in the same one as termleaf. Anywhere else, only Neovim works. termleaf --follow file.tex:line sends a position from scripts and editor keys. The README has the details and Helix's limits.