Skip to content

Home

Jump to bottom
Han edited this page Dec 18, 2025 · 3 revisions

Gorae Wiki

Welcome to Gorae (고래) πŸ‹ β€” a cozy Vim-inspired TUI librarian. This wiki covers setup, configuration, themes, and the everyday workflow.

Quick start

  • Launch Gorae and point it at your PDF library (watch_dir).
  • Browse like Vim/ranger/lf: j/k to move, h/l to navigate directories.
  • Open command mode with :, search with /.
  • Mark papers as Favorite (f) or To-read (t), and track your progress with Reading state (r).

Configuration

Config file location

On first launch, Gorae creates:

  • ~/.config/gorae/config.json or ${XDG_CONFIG_HOME}/gorae/config.json if XDG_CONFIG_HOME is set.

Edit config inside the app:

  • :config β€” open config using your configured editor

Key settings

Common keys you'll likely set:

  • watch_dir β€” root folder Gorae watches (your PDF library)
  • meta_dir β€” metadata storage (SQLite DB)
  • editor β€” editor command (e.g., nvim)
  • pdf_viewer β€” viewer command (e.g., zathura)
  • notes_dir β€” Markdown notes location
  • theme_path β€” path to your active theme file
  • enable_mouse β€” enable mouse inputs (currently support only scroll, double click (left click x2) and go back (right click)).

Helper folders

Gorae can maintain helper folders inside your library so you can browse curated subsets from any file manager (not only inside Gorae):

  • Favorites/
  • To Read/
  • Recently Added/
  • Recently Read/

Themes

Theme file path

Default theme path:

  • ~/.config/gorae/theme.toml

Start from a built-in theme:

cp themes/fancy-dark.toml ~/.config/gorae/theme.toml

Theme structure

Theme TOML is organized like this:

  • [palette] β€” base colors
  • [icons] β€” glyphs (favorite/to-read/read states, etc.)
  • [components.*] β€” per-component styling (headers, lists, preview, status bar, …)

Supported style keys:

  • fg, bg, bold, italic, faint

Palette references are supported:

fg = "palette.accent"
bg = "palette.bg"

Common palette keys:

bg, fg, muted, accent, success, warning, danger, selection

Reloading themes

  • :theme show β€” show active theme path
  • :theme reload β€” reload without restarting (or restart Gorae)

File browsing

Gorae's browsing is inspired by tools like lf and ranger, with Vim-style movement.

Navigation

Key Action
j / k Move down / up
l Enter directory
h Go to parent directory
yy Yank bibtex
yt Yank in-text citation
g Go to top
G Go to bottom
a Create directory
R Rename directory
D Delete file or directory
q / Esc Quit

Arrow keys are also supported.

Selection

Key Action
Space Toggle selection (current item)
v Toggle selection for all PDFs (select all / clear all)

Sorting

Key Action
sy Sort by year
st Sort by title

Metadata and notes

Metadata

  • e β€” open metadata editor for current PDF Inside the editor:

    • e β€” open in external editor (editor setting)
    • n β€” edit the Markdown note for the current PDF (notes_dir)

BibTeX

  • yy β€” copy BibTeX for the current file (cursor item)
  • yt β€” copy in-text citation for the current file (cursor item)

Fetch arXiv / DOI metadata

  • Commands:
    • :autofetch [files...] scans the current file (or specified files) for identifiers.
  • Batch apply:
    • Select multiple files, then run:
    • :autofetch -v applies to the current selection.

Favorites, To-read, reading states

Flags

Key Action
f Toggle Favorite
t Toggle To-read
u Clear flags (opens a prompt)

Reading state

  • r β€” cycle reading state:

Unread β†’ Reading β†’ Read

Search and filters

πŸ”Ž Search

Press / to open search, then type your query.

You can scope the search with flags:

  • -t <title> search in title
  • -a <author> search in author
  • -y <year> filter by year
  • -c <keyword> search in full text (content)
  • --tag <tag> filter by a single tag
  • --tag <t1,t2> filter by multiple tags (comma-separated)

Examples

  • / -t transformer
  • / -a "Yoshua Bengio"
  • / -y 2023 -t diffusion
  • / -c attention
  • / --tag llm,graph

Results view

Key Action
j/k Move
Enter Open selected result
Esc / q Exit results

Quick filters

Key Action
F Show favorites
T Show to-read

you can use yy and yt in the quick filter window.

Command palette and help

  • Status bar shows: mode, current directory, selection summary, last message
  • : β€” command mode
  • :help β€” list available commands

Tips

  • Use helper folders (Favorites/, To Read/, Recently Added/, Recently Read/) in your desktop file manager to browse curated subsets outside Gorae.

If you run into issues or have feature ideas, please open a GitHub issue β€” we'd love to hear from fellow readers. πŸ‹

Clone this wiki locally