📑
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).

Documentation on the available commands can be found here.

Configuration

fancy-cat can be configured through a JSON configuration file located in one of several locations (primary $XDG_CONFIG_HOME/fancy-cat/config.json, fallback $HOME/.config/fancy-cat/config.json, legacy $HOME/.fancy-cat). An empty configuration file is automatically created in the primary or fallback location on the first run.

An example config.json and documentation can be found here.

Installation

fancy-cat is available in the following repositories:

Build Instructions

Requirements

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

Build

1. Fetch submodules:

git submodule update --init --recursive

2. 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

3. 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)
• ✅ Status bar
• ✅ Page navigation (zoom, prev, next, etc.)

License

AGPL-3.0-or-later

Contributing

Contributions are welcome.