https://github.com/freref/fancy-cat
PDF reader for terminal emulators using the Kitty image protocol
https://github.com/freref/fancy-cat
zig zig-package
Last synced: 6 months ago
JSON representation
PDF reader for terminal emulators using the Kitty image protocol
- Host: GitHub
- URL: https://github.com/freref/fancy-cat
- Owner: freref
- License: agpl-3.0
- Created: 2024-11-02T21:31:32.000Z (about 1 year ago)
- Default Branch: master
- Last Pushed: 2025-03-17T19:39:03.000Z (8 months ago)
- Last Synced: 2025-04-03T05:09:42.205Z (7 months ago)
- Topics: zig, zig-package
- Language: Zig
- Homepage:
- Size: 147 KB
- Stars: 326
- Watchers: 5
- Forks: 10
- Open Issues: 16
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
- awesome-zig - freref/fancy-cat
- trackawesomelist - freref/fancy-cat (⭐373) - PDF viewer for your terminal. (Recently Updated / [Jul 27, 2025](/content/2025/07/27/README.md))
README
📑
fancy-cat
PDF viewer for terminals using the Kitty image protocol
## Usage
```sh
fancy-cat
```
### 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
- `:` - 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](./src/config/config.json) and documentation on the config options can be found [here](./docs/config.md)
## Installation
`fancy-cat` is available in the following repositories:
[](https://repology.org/project/fancy-cat/versions)
### Nix
Available as a Nix package [here](https://github.com/freref/fancy-cat-nix).
## Build Instructions
### Requirements
- Zig version `0.14.0`
- 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:
```sh
zig build --release=small
```
> [!NOTE]
> There is a [known issue](https://github.com/freref/fancy-cat/issues/18) 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:
>
> ```sh
> zig build -Dcpu="skylake" --release=small
> ```
3. Install:
```sh
# Add to your PATH
# Linux
mv zig-out/bin/fancy-cat ~/.local/bin/
# macOS
mv zig-out/bin/fancy-cat /usr/local/bin/
```
### Run
```sh
zig build run --
```
## 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](https://spdx.org/licenses/AGPL-3.0-or-later.html)
## Contributing
Contributions are welcome.