zpdf

A minimal terminal PDF viewer for LaTeX workflows in Ghostty + Zellij.

Build

cargo build --release
cargo install --path . --force

The second command installs zpdf into Cargo's binary directory so Helix can invoke it from a key binding.

Requires:

• Rust toolchain
• poppler (provides pdftoppm and pdfinfo)
• A terminal that supports the Kitty Graphics Protocol (e.g. Ghostty)
• Zellij 0.45.0 or newer when running inside Zellij
• latexmk plus a TeX Live engine when opening .tex files

Usage

zpdf document.pdf
zpdf document.pdf --page 12
zpdf document.tex
zpdf chinese-document.tex --engine xelatex

Keyboard controls

Key	Action
j / Down	next page
k / Up	previous page
g	first page
G	last page
Ctrl-d	jump forward 10 pages
Ctrl-u	jump backward 10 pages
PageDown	next page
PageUp	previous page
r	reload PDF
+	zoom in
-	zoom out
=	reset zoom
q / Ctrl-c	quit

LaTeX workflow

# Pane 1
helix main.tex

# Pane 2
zpdf main.tex

When given a .tex file, zpdf performs the initial build, starts latexmk in continuous mode with a 100 ms source polling interval, and stops it when the viewer exits. Compiler output is written to main.latexmk.log. Use --engine xelatex for Chinese documents or --engine lualatex for LuaLaTeX projects.

On Arch-based systems, XeLaTeX and Chinese documents also need the recommended OpenType fonts (and Chinese language support):

sudo pacman -S --needed texlive-xetex texlive-langchinese texlive-fontsrecommended

When given a .pdf file, zpdf only watches and displays that PDF.

Forward SyncTeX search from Helix

Add the following binding to ~/.config/helix/config.toml:

[keys.normal.space]
l = [
  ":write",
  ":noop %sh{zpdf sync --source \"%{buffer_name}\" --line %{cursor_line} --column %{cursor_column}}",
]

With zpdf main.tex running in the preview pane, press Space-l in Helix. The viewer waits for the saved source to compile, jumps to the matching PDF page, highlights the matching text box in yellow, and marks SyncTeX's reference point in orange for 2.5 seconds. The command also works from a chapter included by the main document.

Test PDF

A simple test PDF can be generated without LaTeX:

python3 gen_test_pdf.py test.pdf

Project status

This is the v0.1 MVP. It intentionally keeps dependencies and features minimal:

• Open / render / display PDF pages via Kitty Graphics Protocol
• Compile and continuously watch LaTeX sources through latexmk
• Page navigation
• Two-worker priority render queue with directional page prefetching
• Bounded, ready-to-display page cache
• Fit-to-pane rendering
• Terminal resize handling
• File watching with auto-reload
• Forward SyncTeX search with a temporary position highlight

Not yet implemented: search, text selection, annotations, links, bookmarks, continuous scroll, mouse support, or multiple open files.