A Kitty terminal PDF viewer with Vim-like keybindings and classical GUI-like usage.
Note that the colours in the overview above are corrupted because of GIF compression.
There are multiple in-terminal PDF viewers for the Kitty terminal but the main problem is that the end-user can interact only by viewing one page at a time. The user may have the need to zoom in and out of the PDF document to view details in the document. Another problem is viewing continuous content which is split between multiple pages. Therefore it was decided to develop such PDF viewer which can operates in the same way as a classical GUI PDF viewer but that can additionally be controlled by powerful and customizable Vim-like keybindings.
- Control using mouse/touchpad/keyboard
- File watch
- Toggling of alpha and/or inverse color modes
- Mouse clicking and link hovering
- Customization of keybindings
- URI path annotation bar
- Multi-threaded
- Cross-platform
- ..
- General high customizability
- Cargo
- Rust
- Kitty >= 0.31.0
The project is easily built and installed using Cargo:
$ cargo build --release && cargo install -path .Another method is to download the pre-compiled binaries here.
To view a PDF file simply execute:
$ meowpdf <PATH TO PDF FILE>One of the key-features of MeowPDF is it's high customizability. MeowPDF allows customization based on the following parameters:
- Scroll speed
- Static render precision for PDF pages
- Memory limit on rendered PDF pages
- Default document scale on enter (will be replaced by a dynamic one soon)
- Minimal allowed zoom out amount on the document
- Zoom amount
- Margin amount on the bottom of PDF pages
- Preloaded pages before and after the first displayed page
- Vertical scroll inversion
- Keybindings
- URI annotation bar
The configuration TOML file is found in ~/.config/meowpdf.
The default keybindings are listed bellow:
- q/Q: Quit
- Ctrl+a: Toggles alpha on PDF pages (Makes white background of PDF pages transparent)
- Ctrl+o: Toggles color inversion on PDF pages
- C: Center the viewer
- gg: Jumps to the first page of the PDF document
- G: Jumps to the last page of the PDF document
- h/<left>: Move the document left
- j/<down>: Move the document down
- k/<up>: Move the document up
- l/<right>: Move the document right
- +: Zoom in
- -: Zoom out
The keybindings can be customized by modifying the [bindings] section in the configuration file. The syntax for expressing key combinations is the same as of keybinds-rs. The actions that keys can be bound to are the following:
ToggleAlpha: Toggles the alpha color mode.ToggleInverse: Toggles the inverse color mode.CenterViewer: Centers the viewer.MoveUp: Moves the viewer up.MoveLeft: Moves the viewer left.MoveRight: Moves the viewer right.MoveDown: Moves the viewer down.ZoomIn: Zooms in the viewer.ZoomOut: Zooms out the viewer.JumpFirstPage: Jumps to the first page of the document.JumpLastPage: Jumps to the last page of the document.Quit: Quits the document.
Warning
Be aware that character keys such as a, b, ... can not be combined with the Shift modifier explicitely. Capitalize the characters instead.
The URI annotation bar shows up when hovering a mouse event hovers a link in the PDF document. That bar displays the path of the hovered link.
The URI bar can be customized by modifying the [viewer.uri_hint] section in the configuration file. The following parameters can be set and modified:
enabled(true/false): Enables the URI annotation bar.background(string): Sets the background color of the URI annotation bar.foreground(string): Sets the foreground color of the URI annotation bar.width(f32): Sets the maximum width of the bar as a factor based off the current terminal size.
The allowed color strings are listed here.
Note
The minimal URI bar width is currently 5 column cells.
- Remove heavy and inefficient regex dependency and move to nested switches.
- Implement or find a standard on parsing stdin key inputs.
- Allow for link clicking using the mouse.
- Allow custom remapping of keybindings.
- Command bar to manually jump to different pages and search for text
- Implement auto-scaling of the PDF document on opening based on terminal size.
- Develop a customizable Vim-like bar illustrating page & document metrics.
All contributions are welcome to this project.
MeowPDF is available under MIT.
- Logo was made using Peeking Cat Vectors by Vecteezy.
- README design was inspired from areg-sdk.