📑
fancy-cat

PDF viewer for terminals using the Kitty image protocol

Usage

fancy-cat <path-to-pdf> <optional-page-number>

Commands

fancy-cat uses a modal interface similar to Neovim. There are two modes: view mode and command mode. To enter command mode you type : by default (this can be changed in the config file)

Available Commands

• :<page-number> - jump to the specified page number
• :q - quit the application

Configuration

fancy-cat can be configured through a JSON config file located at ~/.config/fancy-cat/config.json. The file is automatically created on the first run with default settings.

The default config.json can be found here and documentation on the config options can be found here

Installation

Arch Linux

fancy-cat is available as a package in the AUR (link). You can install it using an AUR helper (e.g., paru):

paru -S fancy-cat

Nix

Available as a Nix package here.

Build Instructions

Requirements

• Zig version 0.13.0
• Terminal emulator with the Kitty image protocol (e.g. Kitty, Ghostty, WezTerm, etc.)

Build

1. Fetch submodules:

git submodule update --init --recursive

2. Fetch dependencies:

zig build --fetch

3. Build the project:

zig build --release=small

Note

There is a known issue with some processors; if the build fails on step 7/10 with the error LLVM ERROR: Do not know how to expand the result of this operator! then try the command below instead:

zig build -Dcpu="skylake" --release=small

4. Install:

# Add to your PATH
# Linux
mv zig-out/bin/fancy-cat ~/.local/bin/

# macOS
mv zig-out/bin/fancy-cat /usr/local/bin/

Run

zig build run -- <path-to-pdf> <optional-page-number>

Features

• ✅ Filewatch (hot-reload)
• ✅ Runtime config
• ✅ Custom keymappings
• ✅ Modal interface
• ✅ Commands
• ✅ Colorize mode (dark-mode)
• ✅ Page navigation (zoom, etc.)
• ✅ Status bar

Contributing

Contributions are welcome.