# Bookokrat
Bookokrat is a terminal-based EPUB reader with a split-view library and reader, full MathML and image rendering, automatic bookmarks, inline annotations, and customizable themes.
## Demo
## What You Can Do
- Browse every EPUB in the current directory, drill into the table of contents, and resume exactly where you left off.
- Search inside the current chapter or across the whole book, jump through a per-book history, and inspect reading statistics.
- Highlight text, attach comments, copy snippets or entire chapters, and toggle the raw HTML source for debugging.
- Open images in-place, follow internal anchors, launch external links in your browser, and hand off the book to your system viewer.
- Customize with multiple color themes, adjustable margins, and zen mode; settings persist across sessions.
- Enter a Vim-style normal mode in the reader for precise motions, visual selection, and yanking to clipboard.
- Load EPUB bundles (exploded `.epub` directories, including Apple Books exports) without repackaging.
- Read complex HTML tables and rich cell content with improved rendering and image support.
## Installation
### Homebrew (macOS)
```bash
brew install bookokrat
```
### Pre-built Binaries (Linux)
Download from [GitHub Releases](https://github.com/bugzmanov/bookokrat/releases):
```bash
# x86_64 (Intel/AMD)
curl -LO https://github.com/bugzmanov/bookokrat/releases/latest/download/bookokrat-v0.2.2-x86_64-unknown-linux-musl.tar.gz
tar -xzf bookokrat-v0.2.2-x86_64-unknown-linux-musl.tar.gz
sudo mv bookokrat /usr/local/bin/
```
### Cargo (all platforms)
Build from source. Requires [Rust](https://rustup.rs) and a C compiler/linker.
<details>
<summary>Prerequisites (click to expand)</summary>
**Linux (Ubuntu/Debian):**
```bash
sudo apt update && sudo apt install build-essential
```
**Linux (Fedora/RHEL):**
```bash
sudo dnf install gcc make
```
**macOS:**
```bash
xcode-select --install
```
**Windows:**
Install [Visual Studio Build Tools](https://visualstudio.microsoft.com/downloads/#build-tools-for-visual-studio-2022) with the "Desktop development with C++" workload.
</details>
```bash
cargo install bookokrat
```
### Getting Started
Navigate to a directory with EPUB files and run `bookokrat`. Use `j/k` to navigate, `Enter` to open a book, and `?` for help.
## Keyboard Reference
Bookokrat follows Vim-style keybindings throughout the interface for consistent, efficient navigation.
### Global Commands
- `q` - Quit application
- `Tab` - Switch focus between library/TOC and content panels
- `Esc` - Clear selection/search or dismiss popups
- `Ctrl+z` - Toggle zen mode (hide sidebar/status bar)
- `?` - Show help screen
- `Space+t` - Open theme selector
- `+` / `-` - Increase/decrease content margins
### Navigation (Vim-style)
- `j/k` - Move down/up (works in all lists and reader)
- `h/l` - Collapse/expand in TOC; previous/next chapter in reader
- `Ctrl+d` / `Ctrl+u` - Scroll half-page down/up
- `gg` - Jump to top
- `G` - Jump to bottom
- `Ctrl+o` / `Ctrl+i` - Jump backward/forward in history
### Search
- `/` - Start search (filter in library/TOC; search in reader)
- `n` / `N` - Jump to next/previous match
- `Space+f` - Reopen last book-wide search
- `Space+F` - Start fresh book-wide search
### Library & TOC Panel
- `Enter` - Open highlighted book or heading
- `h` / `l` - Collapse/expand entry
- `H` / `L` - Collapse/expand all
### Reader Panel
- `h` / `l` - Previous/next chapter
- `Space+s` - Toggle raw HTML view
- `Space+c` - Copy entire chapter
- `Space+z` - Copy debug transcript
- `c` or `Ctrl+C` - Copy selection
- `p` - Toggle profiler overlay
- `n` - Toggle normal mode (Vim motions, visual selection, yanking)
- `v` / `V` (normal mode) - Enter visual character/line selection; `y` to yank, `Esc` to exit
### Comments & Annotations
- `a` - Create or edit comment on selection
- `d` - Delete comment under cursor
### Popups & External Actions
- `Space+h` - Toggle reading history popup
- `Space+d` - Show book statistics popup
- `Space+a` - Open comments/annotations viewer
- `Space+o` - Open current book in OS viewer
- `Enter` - Open image popup (when on image) or activate popup selection
### Popup Navigation
All popups (search results, reading history, book stats) support:
- `j/k` - Move up/down
- `Ctrl+d` / `Ctrl+u` - Half-page scroll
- `gg` / `G` - Jump to top/bottom
- `Enter` - Activate selection
- `Esc` - Close popup
## Image Rendering
Bookokrat automatically selects the best image protocol for your terminal:
| **Kitty** | Kitty | Native support |
| **Ghostty** | Kitty | Native support |
| **iTerm2** | Sixel | Native protocol causes flickering; Kitty buggy in recent betas |
| **WezTerm** | iTerm2 | Kitty is buggy ([#986](https://github.com/wezterm/wezterm/issues/986)); Sixel broken on Windows ([#5758](https://github.com/wezterm/wezterm/issues/5758)); some flickering expected |
| **Alacritty** | Halfblocks | No graphics protocol support ([#910](https://github.com/alacritty/alacritty/issues/910)) |
| **Others** | Auto-detected | Kitty > Sixel > iTerm2 > Halfblocks |
**Experience by terminal:**
- **Excellent:** Kitty, Ghostty, iTerm2
- **Good:** WezTerm (some flickering)
- **Basic:** Alacritty, Linux default terminals (Halfblocks fallback)
- **No images:** macOS Terminal.app (no graphics protocol support)
If images look wrong, check `bookokrat.log` for the detected protocol. Experiencing issues not covered above? Just [open an issue](https://github.com/bugzmanov/bookokrat/issues) — happy to help!
## Mouse Support
- Scroll with the wheel over either pane; Bookokrat batches rapid wheel events for smooth scrolling.
- Single-click focuses a pane; double-click in the library opens the selection; double-click in the reader selects a word; triple-click selects the paragraph.
- Click-and-drag to highlight text; release on a hyperlink to open it; drag past the viewport edges to auto-scroll.
- Click images to open the zoom popup; click again or press any key to close; clicking history or stats entries activates them immediately.
## Attribution
This project is based on [bookrat](https://github.com/dmitrysobolev/bookrat) by Dmitry Sobolev, licensed under the MIT License.