GitHub - araaha/yavcpdf: Yet Another Vibecoded PDF Viewer - built on PdfCraft's render engine


yavcpdf is a PDF viewer you drive from the keyboard. The whole window is the document, with a status line at the bottom. It uses PdfCraft's render engine, and its annotation and form writers for :export.

smart-jump.mp4
  • Vim-like Keys such as j, gg and G, counts like 10j and 42G, / search, marks, and every binding rebindable in a TOML file
  • Every command in reach : opens a menu of the commands and of nearly every action, each with its keys on the right, filtered as you type
  • Hints Select words, follow links and delete annotations by typing a label
  • Smart jump and overview Go to, or peek at, the figure, table, equation, section or citation a reference names, even where the PDF made no link
  • Portals Mark a place, go to another and come back
  • Annotations Highlight, draw, sticky notes, and fill & sign are kept beside the PDF and written into a copy on demand
  • Forms Fill in the text fields, check boxes, radio buttons and drop-downs of a PDF form by hint or click, and write the answers into a copy on demand
  • Live reload The PDF reloads when the file changes, and so does the configuration

yavcpdf is built for Linux x86_64 (X11 and Wayland), Windows x86_64, and a universal macOS app.

Arch Linux (AUR)

Build it from source with yavcpdf, or install the release binary with yavcpdf-bin, using your AUR helper:

yay -S yavcpdf        # or yavcpdf-bin

OR

paru -S yavcpdf       # or yavcpdf-bin

The two packages conflict with each other. Both install /usr/bin/yavcpdf, yavcpdf.desktop, the reference configuration at /usr/share/doc/yavcpdf/config.toml, and this documentation in /usr/share/doc/yavcpdf/.

Nix

The repository is a flake that builds yavcpdf from source for x86_64 and aarch64 Linux. Try it without installing:

nix run github:araaha/yavcpdf -- file.pdf

Install it into your profile:

nix profile install github:araaha/yavcpdf

On NixOS or with Home Manager, add the flake as an input and use its package (or overlays.default, which adds pkgs.yavcpdf):

{
  inputs = {
    nixpkgs.url = "github:NixOS/nixpkgs/nixos-unstable";
    yavcpdf.url = "github:araaha/yavcpdf";
    yavcpdf.inputs.nixpkgs.follows = "nixpkgs";
  };

  outputs = { nixpkgs, yavcpdf, ... }: {
    nixosConfigurations.myhost = nixpkgs.lib.nixosSystem {
      system = "x86_64-linux";
      modules = [
        ({ pkgs, ... }: {
          environment.systemPackages = [ yavcpdf.packages.${pkgs.stdenv.hostPlatform.system}.default ];
        })
      ];
    };
  };
}

For Home Manager, put the same package in home.packages. Releases after 0.7.0 include the flake: append a tag, as in github:araaha/yavcpdf/vX.Y.Z, to pin one.

The package installs yavcpdf.desktop, the icon, the reference configuration at share/doc/yavcpdf/config.toml, and this documentation in share/doc/yavcpdf/. The binary is wrapped so it finds the OpenGL, Wayland, X11, xkbcommon and dbus libraries it loads at run time, and fc-match and xdg-open. The file chooser still needs xdg-desktop-portal with a backend, which NixOS sets up with xdg.portal.enable.

On other distributions, the OpenGL from Nix can't find your system's GPU drivers, which NixOS keeps in /run/opengl-driver, and yavcpdf stops with "Found no glutin configs". Start it through nixGL:

nix run --impure github:nix-community/nixGL -- yavcpdf file.pdf

or install yavcpdf another way on those systems.

nix develop opens a shell with Rust, clippy, rustfmt and rust-analyzer, in which cargo run works.

Binary releases

Download yavcpdf-vX.Y.Z-x86_64-linux.tar.gz from the releases page, together with its .sha256 file. Each archive contains the yavcpdf binary, yavcpdf.desktop, this README.md, the docs/ folder, the reference configuration config.toml, LICENSE-MIT, LICENSE-APACHE, NOTICE, ATTRIBUTION.md and the licenses/ directory. The binary is built on Ubuntu 22.04, so it runs on systems with that glibc (2.35) or newer.

At run time it needs OpenGL/EGL drivers, Wayland or X11 libraries (libwayland, libX11, libXcursor, libXi, libXrender, libxkbcommon and libxkbcommon-x11), dbus and fontconfig (fc-match). Optional: xdg-desktop-portal with a backend for the file chooser, and xdg-utils (xdg-open) for links.

Windows

Download yavcpdf-vX.Y.Z-x86_64-windows.zip from the releases page, together with its .sha256 file. Unzip it anywhere and run yavcpdf.exe; with no file given it opens the last document, or a blank page if there is none, where :open or :e open a file. To make it your PDF viewer, right-click a PDF, choose Open with → Choose another app, pick yavcpdf.exe and tick "Always use this app". Links open in your default browser. Windows may show a SmartScreen warning for the unsigned program: choose "More info", then "Run anyway".

macOS

Download yavcpdf-vX.Y.Z-universal-macos.zip (one build for Apple silicon and Intel) from the releases page, together with its .sha256 file. Unzip it and move yavcpdf.app to /Applications. The app is ad-hoc signed but not notarized, so Gatekeeper blocks the first launch: open System Settings → Privacy & Security and click "Open Anyway", or run

xattr -dr com.apple.quarantine /Applications/yavcpdf.app

Run it from Terminal with a file:

/Applications/yavcpdf.app/Contents/MacOS/yavcpdf file.pdf
open -a yavcpdf --args /absolute/path/to/file.pdf

Use an absolute path with open: LaunchServices starts the app with / as its working directory.

Double-clicking a PDF in Finder and "Open With" do not open files in yavcpdf yet, so run it from Terminal with a file, or launch the app on its own, which opens the last document, or a blank page if there is none, where :open or :e open a file.

Settings folders and fonts on each system

config.toml and the per-document data (annotations, signature) live in:

System Settings and data
Linux ~/.config/yavcpdf/ and ~/.local/share/yavcpdf/
Windows %APPDATA%\yavcpdf\ for both (%USERPROFILE%\AppData\Roaming if APPDATA is unset)
macOS ~/Library/Application Support/yavcpdf/ for both

On every system $XDG_CONFIG_HOME and $XDG_DATA_HOME win when set.

The font setting is looked up with fontconfig's fc-match. Windows and macOS don't have it, so the built-in font is used there unless you install fontconfig (for example brew install fontconfig); a missing fc-match is not an error. fc-match installed by Homebrew lives in /opt/homebrew/bin, which is not on PATH for an app started from Finder or the Dock, so the font setting only takes effect when yavcpdf is started from a terminal.

From source

These build instructions are for Linux. Building needs Rust 1.95 or newer. The build fetches PdfCraft and the egui and winit forks it patches in from GitHub, so it needs network access. The run-time needs are the same as for the binary release: OpenGL/EGL drivers, Wayland or X11 libraries, dbus and fontconfig, and optionally xdg-desktop-portal and xdg-utils.

git clone https://github.com/araaha/yavcpdf.git
cd yavcpdf
cargo build --release --locked

Then install it by hand:

install -Dm755 target/release/yavcpdf ~/.local/bin/yavcpdf
install -Dm644 assets/yavcpdf.desktop ~/.local/share/applications/yavcpdf.desktop
xdg-mime default yavcpdf.desktop application/pdf    # to make it the default

With no file, yavcpdf reopens the last document. If that file is gone or won't open (the reason is in the status bar), or there is none, it opens a blank page instead, where :open or :e open a file; a file named on the command line that won't open is an error. The blank page lists the recent files that still exist: type a row's label, or move with j/k and press Enter, or click; Esc closes the list and :recent shows it again, over a document too. It reloads the PDF when the file changes. A password-protected PDF opens a password menu. On Windows, and on macOS when not started from a terminal, --help and argument errors show in a dialog, as do fatal errors. An argument error prints only the error and the usage line; --help has the full text.

Option Effect
--page N Open at page N
--password PW The password of an encrypted PDF; without it, or if it is wrong, a menu asks for the password
--geometry WxH[+X+Y] Set the window's inner size in points, and optionally its position
--fullscreen / --no-fullscreen Override view.fullscreen for this launch
--statusbar / --no-statusbar Override statusbar.visible for this launch
-h, --help Print the options and the paths of the configuration and data
-V, --version Print the version

The last of the fullscreen or the status bar options given wins. view.fullscreen and statusbar.visible only take effect at startup; a configuration reload does not apply them again.

--geometry 1000x700 sets the size, and --geometry 1000x700+40+30 also sets the position. Width and height are 1 to 16384 and the offsets are 0 to 16384. Negative offsets are not supported, so X11's offsets from the right or bottom edge do not work. On Wayland the compositor decides where a window goes, so +X+Y may be ignored.

Tip

Press : to see nearly every action with its keys, and type to filter them.

Keys Action
h j k l Scroll
J / K Next / previous page
g g / G First page / end; NG goes to page N
=, + / - / W / H Zoom in / zoom out / fit width / fit height
/ / ?, n / N Search forward / backward, next / previous match
Tab Table of contents
g d / g o Smart jump / overview, by hint
F / v / i Follow a link / select text / fill in a form field, by hint
Alt+O / Alt+I Jump back / forward
t h / t n / t f Highlight, sticky note, fill & sign tool
u / U Undo / redo
: / q Command menu / quit

Every key, every : command and the editing keys of the bars are in docs/keys.md, and each can be rebound under [keys].

Each feature in a few lines, with a demo. The full description of each is in docs/features.md.

m and a letter mark a place and ' and the letter come back to it. M names a bookmark and g b lists them to jump to, filter or delete. Both are kept per document between sessions.

marks.mp4
bookmarks.mp4

More: Keys

Smart jump and references

g d follows a reference such as Figure 3, Eq. (4) or [12] to what it names, even where the PDF has no link; the video at the top shows it. g r goes the other way: pick a caption, heading, equation or bibliography entry and every place that refers to it is highlighted, for n and N to step through.

references.mp4

More: Smart jump

g o shows what a reference points at in a window over the page, so you can read a figure or a citation without losing your place. Enter goes there and Esc closes it.

overview.mp4

More: Overview

Tab opens the document's outline, or one read from its printed contents pages when it has none. / filters it and Enter goes to the entry.

table-of-contents.mp4

More: Table of contents

Highlight, draw, erase and add sticky notes from the hotbar tools. They are kept beside the PDF, not in it. g a lists them, and :export writes them into a copy.

highlights.mp4

More: Annotations

Fill & sign from the keyboard

a and a letter (n note, T text, D date, C check, X cross, O dot, L line, S signature) cut the page into a grid of hints. Pick a cell, nudge the preview with h j k l, resize it with [ and ], and press Enter to place it. The signature is drawn once on a pad and kept for every document.

place-by-keyboard.mp4
signing.mp4

More: Annotations

i labels the fields of a PDF form: type into text fields, toggle check boxes, pick radio buttons and drop-down options, press buttons and sign signature fields. The values are kept beside the PDF and :export writes them into a copy that stays fillable. Scripts in the form are never run.

forms.mp4

More: Forms

Press p where you are reading, go somewhere else and press p again: the view comes back, and a small window keeps showing the other place.

portals.mp4

More: Portals

With no file given, yavcpdf reopens the last document. :recent, or the blank page when there is none, lists the recent files to pick from by label, with j k and Enter, or a click.

recent-files.mp4

More: Opening files

: lists the commands and nearly every action, each with its keys, filtered as you type: letters in order are enough, so tgl finds toggle_links. Arguments such as file names and themes are completed too.

command-menu.mp4

More: Commands and the : menu

Themes and live configuration

config.toml is reloaded while the viewer runs, so a change shows at once. T cycles through the themes, which set every colour and whether the pages are recoloured.

live-config.mp4

More: Configuration

Also: presentation mode (F5), hints for words and links, password-protected PDFs, writing a copy with or without a password and searching the selected text on the web.

  • Keys and commands: every key, every : command and the : menu, and the editing keys of the bars
  • Features: presentation mode, hints, smart jump, overview, table of contents, annotations, forms, portals, opening files, passwords and exporting
  • Configuration: config.toml, key bindings, searching the web, themes, and what is stored where

The viewer uses PdfCraft's engine crates (https://github.com/storytold/pdfcraft), pinned to a commit in Cargo.toml. To update, run scripts/update-pdfcraft.sh [rev]; without a rev it takes the current main. It changes every pdfcraft rev in Cargo.toml together, compares [patch.crates-io] with PdfCraft's, and runs the tests and clippy. If it reports a difference in the patch list, change [patch.crates-io] to match upstream's and run it again.

yavcpdf is based on PdfCraft by the ArtCraft team. It is not made, sponsored or endorsed by them.

  • Writing annotations or form values into the PDF itself; they leave only through :export
  • JavaScript in PDFs (form scripts, formatting and validation), submitting a form, password and signature fields
  • More than one document per window
  • Printing
  • Text in scanned documents; there is no OCR, and smart jump needs text
  • zathura is a plugin-based document viewer with a minimal interface and vim-like keys.
  • sioyek is a PDF viewer for research papers, with a command menu, smart jump and portals.
  • mupdf is a lightweight PDF viewer and library with a small interface.
  • yavcpdf is a small, keyboard-driven viewer with annotations that are drawn and exported into the PDF, fill & sign, and fillable forms.

yavcpdf is free software, licensed under either of MIT or Apache-2.0, at your option.

It is based on PdfCraft and bundles third-party material under its own licenses. See NOTICE, ATTRIBUTION.md and licenses/.