User Guide
Everything you need to know to get the most out of railreader2.
Getting Started
Download and install
The AI layout model is bundled in all packages.
- Linux: Download
railreader2-x86_64.AppImagefrom GitHub Releases, make it executable (chmod +x railreader2-x86_64.AppImage), and run it. - Windows (Microsoft Store): Install directly from the Microsoft Store for automatic updates, no SmartScreen warnings, and clean install/uninstall. The Store release may lag behind the GitHub release by a few days due to certification review.
- Windows (standalone installer): Download
railreader2-setup-x64.exefrom GitHub Releases and run it. Optionally associate.pdffiles during setup. This always has the latest version immediately.
Opening a PDF
Use File → Open or press Ctrl+O to open a PDF.
You can also pass a file path as a command-line argument.
When no file is open, a welcome panel shows an Open a PDF… button and
a few quick hints for getting started with rail reading. Once you have opened some documents,
it also lists your recent documents — each with a picture of its first
page, how far you’ve read (“page 41 of 230”) and how many notes it has —
and a box for searching all of them. Click a document to open it
where you left off. To take one off the list, right-click it and choose
Remove from Recent Documents, or use File > Recent Files >
Remove from Recent. This only shortens the list: the document’s notes, portals
and library entry stay.
First steps
Once a PDF is open, you can scroll through pages with PgDn/PgUp,
zoom with +/- or the mouse wheel, and pan by dragging.
When you zoom past 3x, rail mode activates automatically — this is
where the AI-guided reading begins. Press R to start
rail reading at the current zoom instead.
Rail Mode
Rail mode is the core feature of railreader2. When you zoom past the threshold (default 3x), the AI layout analysis detects text blocks and reading order, and navigation locks to those blocks. Non-active regions are dimmed so you can focus on the current block and line.
Line-by-line navigation
Down/S— Next lineUp/W— Previous lineRight/D— Hold to scroll forward along the lineLeft/A— Hold to scroll backwardHome/End— Snap to start/end of current line
When you reach the last line of a block, pressing Down advances to the next
navigable block. At the last block on a page, it advances to the next page. You can also
hold Down/S at the last line of a page to
advance to the next page automatically, without needing to release and re-press the key.
Click to jump
Click on any detected block in rail mode to jump directly to it. The view snaps to the clicked block's first line.
Start rail here (any zoom)
You don't have to zoom past the threshold to rail-read. Press R (or
Rail → Start Rail Here) to start rail mode on the block nearest the
centre of the view at your current zoom — the camera doesn't lurch to a higher
magnification. To choose the starting block yourself, click the Start rail
here button on the toolbar, then click where you want to begin. Press
R again or Escape to leave.
Horizontal scrolling
Holding Right/D scrolls horizontally along the current line with
speed ramping — it starts slow and accelerates. Ctrl + mouse wheel also
scrolls horizontally. The speed ramp time and max speed are configurable in Settings.
Rail toolbar
When rail mode is active, a floating toolbar appears with P (auto-scroll), J (jump mode), F (line focus dim), and H (line highlight) toggle buttons, plus a speed/distance slider.
Free pan (Ctrl+Drag)
Hold Ctrl in rail mode to temporarily break out of rail constraints. While
Ctrl is held, you can pan and zoom freely as if rail mode were inactive, and the
page is drawn clean — the rail dim and line overlay are suppressed so
nothing obscures the figure you're inspecting. When you release Ctrl, the view snaps
back to the exact rail position you left. This is useful for quickly checking a figure, footnote,
or other element outside the current reading flow without losing your place.
To stay in free pan without holding the key, hold Ctrl on its own for about a second
and let go: free pan stays on, and plain drags pan freely (handy while you add notes or highlights
around a figure). Tap Ctrl to snap back. Pressing another key or clicking while holding
Ctrl keeps the usual shortcut and drag behaviour.
Zoom position preservation
Zooming in and out preserves your reading position within the current line. The camera adjusts so the text you were reading stays in view rather than jumping to the block origin.
Reading guide (experimental)
The reading guide is an experimental feature for reading at lower zoom, hidden unless you
tick Enable experimental features under Settings → Reading (shown with
Show advanced settings). Once enabled, turn it on with the Reading guide
toolbar button, Rail → Reading Guide, or K. Click a word, then hold
Shift and nudge the pointer like a joystick to carry a word-and-line highlight along the text
at your reading pace; above the rail threshold the same nudge scrolls the rail. Settings → Reading
→ Reading Guide can switch it to simply marking the word under the pointer instead.
Press K or Escape to leave the mode. It may change or be removed in a later
release.
Shift+D to toggle the debug overlay, which shows
all detected layout blocks with their class labels, confidence scores, and reading order.
Useful for understanding why rail navigation behaves a certain way.
View Rotation
Quarter-turn the whole displayed page — useful for sideways scans or a wide table laid
out in landscape. Rotate with Ctrl+R (clockwise) / Ctrl+Shift+R
(counter-clockwise), from the View → Rotate menu, or from a block's
right-click context menu. Rotation is per-document (shared by every tab or pane viewing the
same file) and persists across sessions.
In rail mode, if the current line lands on a block that's sideways relative to the page's
rotation, a one-time toast points you at U (“Rotate to Read Block”)
— pressing it rotates the whole page just enough to make that block upright and
re-runs layout analysis on it, so you get real per-line detection instead of guessed
geometry. Press U again once it's upright to reset rotation back to 0. A status
bar badge shows the current rotation (e.g. “Rotated 90°”) with a one-click
reset button.
Annotations can't be authored while rotated — the toolbar's Annotate button is greyed out and existing annotations aren't shown, because their stored geometry is always in the page's unrotated frame. Rotate back to 0° to see and edit them again.
Auto-Scroll
Press P in rail mode to toggle semi-automatic auto-scroll. The
view flows through prose line by line on its own — but rather than running unattended
through the whole document, it parks (stops and waits for you) whenever it
reaches something worth pausing on, then continues at your signal. The easy, mechanical part
stays automatic; the “am I done with this?” decision stays yours.
- Where it parks: on arrival at a non-prose block — a display equation, table, figure, or heading — and at the end of a column and a page. Continuous prose flows straight through, even across paragraph breaks.
- Continuing: while parked, press
DorS(orRight/Down) to resume flow. A “Parked — press D to continue” hint appears in the status bar and on-page so a stop never looks like a freeze. - Inspect while parked: pan and zoom (and
Ctrl+drag free-pan) stay fully live while parked, so you can study a parked equation or figure for as long as you like. - Reading beat: within prose, a brief pause is held at the end of every line before moving to the next (default 400 ms). If the move between lines feels too quick, choose a slower Reading pace (Settings → Reading).
- What parks: the set of block types that park is configurable — Settings → Auto-Scroll → Stop and Wait At (headings, equations, tables, figures by default; uncheck any to flow through it).
- Stop: press
Escape,P, or an opposing navigation key (Up,Left) to exit auto-scroll entirely.
The status bar shows an "Auto-Scroll" indicator while flowing and
"Parked — press D to continue" while stopped. Adjust speed with the rail
toolbar slider, [ / ] keys (±5), or Ctrl+[ /
Ctrl+] for fine adjustments (±1); holding D/Right
during flow temporarily boosts speed. Scroll speed is zoom-independent — reading pace stays
consistent at any magnification.
Auto-scroll trigger: Auto-scroll can also start automatically after sustained
horizontal scrolling. If you hold Right/D continuously for long enough,
auto-scroll engages and continues on its own when you release the key.
Jump Mode
Press J in rail mode to toggle jump mode. Instead of
continuous scrolling, Right/D and Left/A
perform saccade-style jumps — advancing by a configurable percentage of the visible width
(default 25%).
Hold Shift with Right or Left to perform a
short jump at half the normal distance. This is useful for fine-grained
positioning within a line.
This mimics natural reading eye movements and is useful for scanning text quickly.
Adjust jump distance with [ / ] or in Settings → Reading (advanced view).
Line Focus & Highlight
Line focus dim
When enabled, line focus dim applies a smooth feathered dimming overlay to the entire page except the active line in rail mode. Non-active lines fade toward the background colour, reducing peripheral distraction while maintaining a clean visual transition.
Toggle with the F key, the F button on the rail toolbar, or in
Settings → Reading → Mark the line you're on. In the advanced view,
dim intensity is adjustable from 0 (off) to 1 (maximum), as is the padding around the active
line (how much extra space stays fully visible).
Line highlight tint
The active line in rail mode can have a configurable colour tint applied as an overlay.
This makes the current line stand out more clearly, especially at high magnification.
Press H to toggle the line highlight independently of line focus dim.
Choose from five presets in Settings → Reading → Highlight colour:
- Auto — Adapts to the active colour effect (amber for Amber, green for HighContrast/HighVisibility, etc.)
- Yellow — Warm yellow highlighter
- Cyan — Cool cyan tint
- Green — Soft green tint
- None — No tint — line is highlighted by dimming only
Opacity is adjustable from 0.0 (invisible) to 1.0 (fully opaque) in the advanced view. The default is Auto at 25% opacity.
Freeze Panes
Pin part of a page in place — like Excel's Freeze Panes — so a header row, a label column, or both stay visible while the rest of the page scrolls under them. It is page-wide and works on any page, not just detected tables, and does not depend on table detection at all.
Open the Freeze button (the snowflake) on the toolbar — always available whenever a page is loaded — and pick a mode:
- Rows — then click in the page to freeze everything above a horizontal guide line.
- Columns — then click to freeze everything left of a vertical guide line.
- Both — then click to freeze above and left of a
crossing point. Press
Zto arm “both” directly.
The pointer shows a guide line while a placement is armed, and the click drops the split exactly where you point — there is no snapping to detected boundaries (which are sometimes wrong). The two axes compose: freeze rows first, then add a column freeze to build up to “both”. Zoom is locked while frozen so the panes and body can't drift apart, and the frozen strips re-render crisply as you read.
Each split pane and tear-off window freezes independently, and a freeze belongs
to the page it was set on — it clears automatically when that view moves to another page.
To release it, click Unfreeze in the Freeze flyout, use the
❄ Frozen — Unfreeze chip that appears in the frozen pane's corner,
or press Z again. Press Escape to cancel a placement you've armed but
not yet dropped.
Colour Effects
Four GPU-accelerated colour filters are available, applied only to PDF content (not the UI).
Access via View → Colour Effect, Settings → Appearance, or press
C to cycle through effects on the focused document.
- Amber Filter: Warm tint that reduces blue light and perceived haze. Good for extended reading.
- High Contrast: White-on-black rendering with an S-curve for maximum contrast. Reduces glare.
- High Visibility: Yellow-on-black for maximum legibility at the cost of colour information.
- Invert: Simple colour inversion for dark backgrounds.
Each document keeps its own colour effect independently — you can have one PDF in Amber and another in High Contrast. The effect is saved with the reading position and restored when you reopen the file.
Each effect has adjustable intensity (0.0 to 1.0). Rail mode overlay colours automatically adapt to the active colour effect for readable contrast.
C to quickly cycle through colour effects. The
status bar briefly shows the active effect name.
Search
Press Ctrl+F to open the Search section of the side panel (one of the
accordion sections, alongside Outline, Bookmarks, Index, Comments, and Portals). Type your query — results
appear automatically after a brief debounce; clicking a result jumps to the match and hands keyboard focus back to the page.
- Results panel: Matches are grouped by page with text snippets showing the match term in context (bolded). Click any result to jump directly to that match.
- Navigate matches:
Enter/Shift+Enterin the search input,F3/Shift+F3globally, or the arrow buttons in the panel. - Case sensitivity: Toggle with the
Aabutton. - Regex: Toggle with the
.*button for regular expression search. - Match count: The panel shows the current match index and total count (e.g. “3 of 42”).
- Clear: Click the clear button (×) to remove all highlights and results, or press
Escape.
Library Search
Library search looks through every PDF you have opened in railreader2 at once. It finds words in the pages, the outline (table of contents), your notes and comments, comments that other people wrote into the PDF, your named bookmarks, file names, and the title, author and keywords stored in the PDF. Use it when you remember what a paper said but not which paper said it.
Open it with Ctrl+Shift+F, File → Search Library…, the
search box on the welcome screen, or Search all documents ↗ in the Search
panel (which carries your search over). The Library window works with no document open, and
stays open while you read.
Typing a search
- Every word must appear on the page (or in the note):
bootstrap confidence band. - Put a phrase in quotes to find the words together:
"wild bootstrap". - End a word with
*to find words that start with it:heterosced*. - Put
-before a word to leave out results that contain it:ridge -lasso. - Capitals and accents don’t matter, and common word endings are matched loosely:
estimatorsalso finds estimation, anddiagnosingfinds diagnosis.
There is no special syntax to get wrong: any other punctuation is treated as ordinary text.
Results
Results are grouped by document, the best match first, with up to three snippets each. Matched words are in bold, and each snippet says where it came from: page 12, outline, your note, reviewer comment (name), bookmark, or OCR text, unverified for text that was read from a scanned page. A note’s colour category is shown too, if you have given its colour a name (Settings > Reading > Annotations, advanced view).
Use the checkboxes to search only page text, notes and comments, the outline, or titles and file names; Only documents with notes; or, once you’ve named a colour, a single colour category.
Click a result, or move to it with the arrow keys and press Enter. The document
opens (or its tab comes to the front) at that page:
- for a note or comment, the note is selected, as in the Comments panel;
- otherwise the Search panel opens with your words highlighted on that page. In a long book the highlighting can take a few seconds to appear.
A comment counts as your note when its author is the name in Settings > Reading > Annotations, or when it has no author and railreader2 saved it into the PDF; anyone else’s is a reviewer comment. (Unsigned notes saved before version 3.89 carry no such mark and count as reviewer comments.)
Which documents are included
- Every PDF is added when you open it. The documents you had opened before this feature existed are added in the background after the app starts; this pauses while you are rail reading. The Library window shows “Indexing 3 of 12…” while it runs.
- Your notes are brought up to date when you close the document.
- Password-protected PDFs are found only by file name: their text is never stored.
- Scanned pages are searchable only if they have a text layer (File → Add a Text Layer) or were read with OCR while you had the document open.
Moved and deleted files
A document whose file is no longer where it was is shown greyed, with two buttons:
- Locate… — choose the file in its new place. It is accepted only if it is the same document (the same contents), and nothing changes otherwise.
- Remove from Library — forgets the document’s search entry. Your notes, bookmarks and portals are kept, and the document comes back if you open it again.
Privacy
The library is stored only on your computer, in library inside the settings folder
(~/.config/railreader2/library on Linux, %APPDATA%\railreader2\library
on Windows). It holds a copy of your documents’ text and notes, and the first-page pictures
shown on the welcome screen. Nothing is sent anywhere. See also the
privacy policy.
Settings > Library (in the advanced view) shows its size and has two buttons. Rebuild Index reads every document you have opened again. Clear Index deletes it: documents come back only as you open them again. Neither touches your PDFs, notes or portals.
AI tools
AI tools such as Claude Code, Claude Desktop and Codex can read your library while you work with them, so you can ask “what did I note about identification in the minimum-wage papers?” without opening a PDF. They connect to railreader2’s MCP server, which comes with the app. It is off until you turn it on.
- Open Settings > Library (advanced view) and find AI Tools. Tick Let AI tools read my library.
- Tick each tool to connect. A switch adds railreader2’s entry to that tool’s own settings, and unticking it removes the entry again; nothing else in the tool’s settings is touched. A tool that isn’t installed is greyed out. Start a new session of the tool afterwards.
- For any other MCP client, Copy Setup copies the entry to paste into its settings.
What a tool can read: your notes and comments (with their replies, colour categories, and whether they are yours or a reviewer’s), your named bookmarks, and the page text of the documents you have opened, with each document’s title, authors and file name. What it can’t: file paths or folder names, the PDF files themselves or any images, and anything at all from password-protected documents. It can only read; it can’t change your documents or notes.
Hiding documents: right-click a document in the Library window (File ▸ Search Library…,
or Ctrl+Shift+F) or a recent document on the start screen and choose
Hide from AI Tools, or use Hide a Folder… under AI Tools to
hide everything in a folder. The same section lists every hidden folder and document, with
Remove and Unhide buttons and Unhide All Documents. A hidden document is treated as if it weren’t in your library.
Turning AI tools off, or hiding a document, applies at once, even to a tool that is already connected.
Where your notes go: what a tool reads is sent to that tool’s AI provider (for example, Anthropic for Claude and OpenAI for Codex) under their terms. The MCP server itself makes no network connection: it talks only to the program that started it. See the privacy policy.
Without an MCP client: Copy Notes for AI in the Comments panel copies the notes it lists as Markdown, to paste into any chat or document.
From the command line: the server is RailReader2.Mcp in the app’s
folder, railreader2-mcp in the Microsoft Store version, and
railreader2-x86_64.AppImage --mcp for the AppImage. Add status,
enable, disable, hide <document> or
hide --folder <dir> (and unhide) to manage it. The command-line
tools’ railreader2-cli mcp is the same server. The Store version keeps its
settings in a private folder the separate command-line tools can’t see, so use
railreader2-mcp there.
Annotations
Toggle Annotation Mode from the toolbar's Annotate button (or
Ctrl+E, the Edit menu, or a block's right-click context menu) to reveal the
annotation tool row.
- Highlight (
1) — Drag over text to highlight. Uses character-level detection for precise selection. - Underline, Strikethrough, and Squiggly — text-markup tools, same drag-over-text gesture as Highlight.
- Pen (
2) — Freehand drawing. - Rectangle (
3) — Draw rectangular outlines or filled regions. - Text Note (
4) — Click to place a note. Shows as a small folded-corner icon; click the icon in browse mode to expand/collapse the popup. Click an existing note in Text Note mode to edit. - Text Box — typewriter-style free text; drag a box, then type its text in the note editor.
- Eraser (
5) — Click on an annotation to remove it.
Number keys 1–5 jump straight to Highlight, Pen, Rectangle,
Text Note, and Eraser respectively; Underline, Strikethrough, Squiggly, and Text Box have no
numeric shortcut — pick them from the toolbar.
Signing your notes. Every note and reply is saved with the name in Settings > Reading > Annotations > Your name, and that name goes into the PDF with them, so people you send the file to can see it. While the name is blank, the first time you start annotating in a session railreader2 offers your computer account’s name in the status bar: choose Use, Another name… to type your own, or Stay unnamed (it won’t ask again). It never fills in a name without asking. The same name is suggested next to the box in Settings.
Tool cursors
Each annotation tool shows a distinct mouse cursor so you always know the active mode:
- Highlight, Underline, Strikethrough, Squiggly, Pen, Rectangle, Text Note, Text Box — crosshair cursor
- Eraser — no-entry cursor
- Text Select — I-beam cursor
- Browse (no tool) — default arrow cursor
Annotation toolbar: colour & thickness
In annotation mode, the toolbar's Colour button opens a flyout with one shared five-colour palette — Yellow, Green, Red, Blue, and Black — used by every colour-capable tool (Highlight, Underline, Squiggly, Strikethrough, Pen, Rectangle, Text Note, and Text Box). Each tool remembers its own last-picked colour independently, so switching tools doesn't change another tool's colour.
The Thickness button opens a flyout with three stroke presets — thin, normal, thick — but only applies to Pen and Rectangle; it's disabled for every other tool.
Annotation z-order
Annotations are drawn in a fixed z-order: highlights appear below freehand strokes and rectangles, which appear below text notes and text boxes. Within each tier, annotations are drawn in the order they were created.
Popup notes
Text notes display as a compact folded-corner icon (16px). In browse mode, click the icon to expand a floating popup showing the full note text with word wrapping. Click again to collapse.
Comments on highlights
Any highlight, underline, strikethrough, or squiggle can carry a comment, like a sticky note attached to the marked text. In browse mode, double-click the highlight to open the same note editor used for text notes; or right-click it and choose Add Comment… (Edit Comment… once it has one), or use Edit → Add/Edit Comment… with the highlight selected. A highlight with a comment shows a small note icon at the end of its first line, and the comment pops up beside it while the highlight is selected. Clearing the text removes the comment. Rectangles and pen strokes take a comment the same way from the right-click menu. Comments appear in the side panel's Comments list and in the Markdown export, and are saved into the PDF as the annotation's contents, so other PDF readers show them too.
Merging overlapping highlights
Highlighting the same passage twice, or extending a highlight by drawing over its end, leaves two overlapping annotations. Right-click one and choose Merge Overlapping Highlights to combine it with every highlight of the same kind and colour that it overlaps into a single annotation (the item only appears when there is something to merge with). Edit → Merge Overlapping Highlights does the same for the selected highlight, or for the Whole Page at once. Turn on Automatically When Drawing in that submenu to merge each new highlight into whatever it overlaps as you draw it. Every merge is one undo step. If two overlapping highlights carry different comments they are left alone — edit or clear one first. A reviewer's highlight that lives inside a read-only or signed PDF can't be merged, because the PDF can't be changed to remove it.
Spell checking in notes
The note editor used by Text Note and Text Box underlines misspelled words as you type.
Right-click an underlined word for suggestions, Add to
Dictionary, or Ignore; press F7 to jump to the next
misspelling and open the same menu. Single letters, all-caps abbreviations, words with
digits, LaTeX commands, and URLs are skipped.
British and American English dictionaries are built in. Turn checking on or off and pick the
dictionary in Settings → Spelling. In the advanced view you can manage
your personal dictionary (words added there are accepted whichever dictionary is selected)
and find the folder for adding other languages — any Hunspell .aff +
.dic pair, such as LibreOffice's dictionaries.
Select, move, and resize
In browse mode (no annotation tool active), click on any annotation to select it (shown with a dashed blue outline). Drag a selected annotation to move it. Text markup (highlight, underline, strikethrough, squiggly) can be selected and deleted but not moved — it belongs to the text it was made on, so dragging over it pans the page as usual. For freehand annotations, 8 resize handles appear on the bounding box — drag a handle to scale proportionally. All move and resize actions support undo/redo.
Delete selected annotation
Press Delete or Backspace in browse mode to remove the selected annotation.
This uses the same undo-supported removal as the eraser.
Copy and paste
Select a text note, text box, rectangle, or pen stroke and press Ctrl+C to copy it
(or Ctrl+X to cut it). Ctrl+V pastes it onto the current page — of
the same document or any other open one. Pasting back onto the page it came from offsets each copy
slightly so it doesn't sit on top of the original. Right-click on the page and choose
Paste Annotation Here to place it at the pointer instead. A pasted annotation is a
new annotation of its own, saved like any other, and Ctrl+Z undoes the paste.
Text markup isn't copied as an annotation; Ctrl+C on a selected highlight copies the
text under it instead. Copying a note or text box also puts its text on the system clipboard, for
pasting into other apps. Right-clicking an annotation offers the same copy, cut, and delete actions.
Pasting is unavailable while the view is rotated.
Undo and redo
Ctrl+Z undoes the last annotation action (including moves, resizes, and deletions).
Ctrl+Y or Ctrl+Shift+Z redoes. Each tab has an independent undo/redo stack.
Persistence
Annotations are saved automatically to internal storage. They load automatically when you reopen the file. When the same PDF is open in multiple tabs, all tabs share the same annotation data — edits in one tab are immediately visible in the other, with independent undo/redo stacks per tab.
Export
Use File → Export with Annotations to create a new PDF with annotations rendered into the pages. The original PDF is not modified.
Use File → Export Annotations as JSON to save all annotations for the current document as a standalone JSON file. This is useful for sharing with other RailReader2 users, backup, or programmatic access to annotation data.
Use File → Import Annotations… to import annotations from a JSON file. Imported annotations are merged with any existing annotations on the active document — your annotations are preserved, and the imported ones are added alongside them. Duplicate bookmarks (same name and page) are skipped.
Moving a reading session to another computer
Use File → Save Reading Package… to bundle the PDF with
everything RailReader2 keeps for it: your annotations and bookmarks, portals, view rotation,
colour filter and the page and zoom you were at. The result is a single
.railreading file you can copy to another computer or send to someone.
Open the package with File → Open (or double-click it, where your system has registered the file type). If that computer already has the same document, RailReader2 offers to add the package to your copy: your notes stay, the package's are added alongside them (ones your copy already has are skipped), and you go to where the package left off. Otherwise it asks where to save the PDF and opens it with everything restored.
A password-protected PDF stays encrypted inside the package, and the password is not included, but your notes are stored as plain text, so RailReader2 asks before packaging one.
PDF Links
Clickable links embedded in PDF documents are fully supported.
Internal links (cross-references)
Clicking an internal link — such as a citation reference, figure number, table of contents entry, or equation reference — navigates directly to the target location. The view scrolls to the exact position specified by the link destination, not just the page. This works in both browse mode and rail mode. In rail mode, links take priority over block-snapping.
External links (URLs)
Clicking an external link (a URL) opens a confirmation dialog showing the full URL. Click
Open to launch it in your default browser, or Cancel to dismiss.
Only http:// and https:// URLs are allowed; other schemes are blocked
for security.
Back and forward
After following a link or jumping to a bookmark, press Alt+Left or
` (backtick) to go back. Press Alt+Right to go forward.
Each tab maintains its own independent navigation history. The back button in the
bookmarks panel also works.
Hover feedback
When the mouse hovers over a clickable link, the cursor changes to a hand pointer. This works in browse mode (when no annotation tool is active).
Text Selection
The floating toolbar in the top-left corner provides three modes:
- Browse — Default pan mode.
- Text Select — Click and drag to select text. Selection uses character-level bounding boxes for precise results.
- Copy — Appears when text is selected. Click to copy, or use
Ctrl+C.
The active mode is shown with a blue highlight on the toolbar button. Press Escape
to cancel selection and return to browse mode.
Bookmarks
Press B to bookmark the current page, or click + Add Bookmark
in the bookmarks panel. A dialog lets you name the bookmark (pre-filled with "Page N").
Managing bookmarks
Press Ctrl+Shift+B to open the Bookmarks section of the side panel.
Each bookmark shows its name and page number.
- Navigate: Click a bookmark to jump to that page (zoom resets to fit the page).
- Rename: Click the Rename button on a bookmark to change its name.
- Delete: Click the Delete button to remove a bookmark.
- Back: After navigating to a bookmark, a “Back to previous location”
button appears at the top of the list. Click it or press
`(backtick) to return to where you were.
Duplicate handling
If you bookmark a page that already has a bookmark, the existing bookmark's name is updated instead of creating a duplicate.
Persistence
Bookmarks are stored in the same annotation file as highlights, notes, and other annotations. They persist across sessions automatically.
Index Pane
Press Ctrl+Shift+I to open the Index pane —
a browsable index of all figures, tables, and equations detected by the layout analysis model.
It is one of the side-panel accordion sections (alongside Outline, Bookmarks, Search, Comments, and Portals).
Background scanning
RailReader2 progressively analyses all pages in the background when idle. As pages are scanned, detected figures, tables, and equations appear in the pane. A progress indicator shows how many pages have been scanned (e.g., “12 of 20 pages scanned”). Background scanning pauses automatically during rail mode to avoid interfering with reading.
Scan All
Background analysis only reaches pages near where you have been reading. To index the entire document at once, click Scan All at the top of the pane — it sweeps every page for figures, tables, and equations and reports progress as it goes. The result is kept with the document, so switching tabs and back does not lose it.
Browsing entries
Each entry shows a thumbnail crop for figures and tables, or extracted text content for equations (Unicode math symbols from the PDF text layer). Use the Figures, Tables, and Equations toggle buttons at the top to filter by category. Click any entry to navigate to that page, or right-click it to open it in the portal pop-out window — a quick way to park a figure on a second monitor while you keep reading; Lock it there to keep it pinned.
Comments
The side panel's Comments section gathers every text note and reviewer comment in the document into one scrollable list, so you can read or jump between them without scrolling the pages.
- Sources: your own text-note annotations and in-PDF reviewer comments — comments authored in other PDF tools (Acrobat, Preview, …) and embedded in the file — appear together.
- Filter: use the All / Reviewer / Yours filter at the top to narrow the list by source.
- Jump: click an entry to navigate to its page; focus returns to the page so you can keep scrolling.
- Review state: for in-PDF reviewer comments, you can change the review state inline from the list.
- Copy Notes for AI: copies the notes the list shows (the filters apply) as Markdown: grouped by page, replies under the note they answer, and the text each highlight marks quoted. Paste it into an AI chat or any document. See also AI tools.
Portals
A portal links a reference in the text — a “see Figure 3”, a “cf. Table 2”, an “(Eq. 7)” — to the figure, table, or equation it points to. Once linked, the target stays in view while you rail-read past the reference, so you never have to scroll away from the paragraph to see what it cites.
The linked target appears in the side panel's Portals section, and — optionally — in a detachable, always-on-top pop-out window you can drag to a second monitor. That pop-out is a live viewport, not a still image — rail reading, freeze panes, and annotation all work inside it, and it re-aims itself as you read on.
Creating a portal
Right-click a detected block on the page and choose Create Portal — Keep This Block In View While Reading. Or use the two-step Set as Portal Target → Link Target to Current Paragraph when it is easier to mark the figure first and find the reference afterwards.
Sources are line-precise: the link fires at the exact line you were on, so several references in one paragraph (line 2 → Figure 3, line 8 → Figure 4) each surface their own target in turn. The shown target stays pinned until you reach a different portal's source, so it never flickers as you scroll.
On-page markers
Subtle, always-on markers show where portals are anchored on the current page: a small gutter dot beside each source line and a corner badge on each target block. The currently-shown portal is drawn accented. Click a marker to act on it — a source jumps to (shows) its target, a target jumps back to its source; a marker that stands for several portals opens a chooser.
Pop-out window
Click Pop out ↗ in the Portals pane (or click the docked preview) to detach the target into a floating, borderless, always-on-top window — useful on a multi-monitor setup. The window hosts a live viewport of the target, so you can rail-read, freeze panes, and annotate inside it just like the main view; it follows the reading position, re-aiming as you cross new references. Drag its top bar to move it, the corner grip to resize; scroll to zoom and drag to pan inside it, double-click to fit. The Pin toggle controls always-on-top, Lock freezes the current target so reading on (or an auto-pin) won't replace it until you unlock, and Dock returns it to the panel. Its size and position are remembered.
Temporary peek
To glance at a block without saving a link, right-click it and choose Open in Portal (Temporary) — or right-click any entry in the Index pane. It opens in the pop-out window only, leaves any saved portal's tracking untouched, and dismisses itself once you read on (unless you Lock it).
Managing portals
The Portals pane lists every portal in the document. Rename a portal inline, click Go to source to jump to and frame its reference, or Delete to remove it. Portals are saved per-document in a sidecar keyed by the PDF's path, so they persist across sessions.
Acknowledgement: the portal concept — and the name — is borrowed from Sioyek, a PDF reader for research papers whose Portals feature inspired this one.
Copy as LaTeX (VLM)
Press Ctrl+L to send the current rail block to a Vision Language Model and
copy the result to the clipboard. You can also right-click any detected
block to open a context menu with Copy as LaTeX,
Copy as Markdown, Copy Description, and
Copy Image options — the same four are on the
Edit menu (Copy Block as LaTeX / Markdown / Description / Image),
acting on the current rail block. The Ctrl+L shortcut auto-selects
the action by block type: equations → LaTeX, tables → Markdown,
figures → description.
Setup
Open Settings > AI Assistant (turn on Show advanced settings first) and configure an OpenAI-compatible API endpoint. Use Test Connection to verify your setup.
Structured JSON output
Under Settings > AI Assistant there's a Use structured JSON schema
responses checkbox (off by default). Enabling it forces capable models
(GPT-4o, Qwen2.5-VL, Gemini) to return a JSON object matching a strict schema,
producing cleaner output — no stray $$ wrappers, code fences, or
prompt echoes. Some local or OCR-specialised models don't reliably support JSON schema
and may return truncated output; disable the checkbox in that case.
Recommended models
- Cloud (OpenAI):
gpt-5.4-nano-2026-03-17— best accuracy for equations and tables. Requires an API key. Note: sends images to external servers. - Local (Ollama):
qwen2.5-vl:7b— good general-purpose vision model, no data leaves your machine - Local (vLLM + LightOnOCR):
lightonai/LightOnOCR-2-1B— specialised OCR model, fast local inference
See the VLM setup guide for detailed instructions on all three options.
CLI Tool
RailReader2 ships a standalone headless CLI for automated PDF extraction.
Download railreader2-cli-linux-x64.tar.gz (Linux) or
railreader2-cli-win-x64.zip (Windows) from
GitHub Releases,
then extract the archive. On Linux, make the binary executable
with chmod +x RailReader2.Cli.
ONNX model
The CLI uses the Docling Heron-INT8 ONNX layout model by default, with PP-DocLayoutV3
available as an alternative. If the GUI is installed, the CLI finds the models automatically
from the shared cache. If the GUI isn't installed, download the models by running
./scripts/download-model.sh from source. The structure command
works without the model but skips layout analysis.
render — export pages as PNG
Renders PDF pages as PNG images, with optional colour effects and annotation overlay.
railreader2-cli render <pdf> [options]
| Option | Description |
|---|---|
--pages <range> | Page range, e.g. "1,3,5-10" (default: all) |
--dpi <int> | Render DPI (default: 300) |
--effect <name> | Colour effect: none, highcontrast, highvisibility, amber, invert |
--intensity <float> | Effect intensity 0.0–1.0 (default: 1.0) |
--annotations | Burn annotations into rendered pages |
--output-dir <path> | Output directory (default: ./screenshots) |
# Render first 5 pages with amber filter
railreader2-cli render paper.pdf --pages 1-5 --effect amber --output-dir ./out
# Render all pages with annotations baked in
railreader2-cli render paper.pdf --annotations --dpi 150
structure — extract document structure
Extracts the PDF outline (table of contents), ONNX layout blocks, and per-block text as JSON.
railreader2-cli structure <pdf> [options]
| Option | Description |
|---|---|
--output <path> | Output JSON file path (default: stdout) |
--include-text | Include extracted text per layout block |
--analyze | Run ONNX layout analysis to detect blocks |
--pages <range> | Page range for analysis (default: all) |
# Full structure with layout analysis and text
railreader2-cli structure paper.pdf --analyze --include-text --output structure.json
# Just the outline (no model needed)
railreader2-cli structure paper.pdf
annotations — export annotations
Exports annotations as rich JSON (with extracted text, layout block correlations, and nearest section headings) or as an annotated PDF.
railreader2-cli annotations <pdf> [options]
| Option | Description |
|---|---|
--output <path> | Output file path (default: stdout for JSON) |
--format <json|pdf> | Export format (default: json) |
--include-text | Extract text under each annotation |
--include-blocks | Correlate annotations with layout blocks (implies ONNX analysis) |
# Rich JSON export with text and layout context
railreader2-cli annotations paper.pdf --include-text --include-blocks --output annotations.json
# Export as annotated PDF
railreader2-cli annotations paper.pdf --format pdf --output paper.annotated.pdf
vlm — transcribe blocks via a vision LLM
Sends detected equation, table, and figure crops to an OpenAI-compatible vision API and writes the transcriptions as JSON. Equations become LaTeX, tables become Markdown, figures become one-sentence descriptions. Uses the same endpoints as the GUI's Copy as LaTeX feature (OpenAI, Ollama, vLLM, LMStudio, etc.).
railreader2-cli vlm <pdf> [options]
| Option | Description |
|---|---|
--classes <list> | Comma-separated subset: equation, table, figure |
--all | Shortcut for all three classes |
--pages <range> | Page range (default: all) |
--page <n> --block <i> | Transcribe a single block by page + block index |
--from-structure <path> | Reuse an existing structure --analyze JSON instead of re-running ONNX |
--endpoint <url> / --model / --api-key | Override AppConfig VLM settings (API key also read from $OPENAI_API_KEY) |
--equation-* / --table-* / --figure-* | Per-class endpoint/model/api-key overrides for mixed routing |
--prompt-style <style> | instruction (default) or ocr |
--concurrency <n> | Parallel VLM requests (default: 1) |
--dump-crops <dir> | Write the PNG crops to disk (useful for debugging) |
--no-structured-output | Disable JSON schema response format (default: on) |
--no-html-to-md | Keep HTML tables as-is (default: convert to Markdown) |
--output <path> | Output JSON file path (default: stdout) |
# Transcribe every equation and table in a paper to LaTeX/Markdown
railreader2-cli vlm paper.pdf --classes equation,table \
--endpoint https://api.openai.com/v1 --model gpt-5.4-nano-2026-03-17 \
--output transcriptions.json
# Mixed routing: local Ollama for equations, OpenAI for figures
railreader2-cli vlm paper.pdf --classes equation,figure \
--equation-endpoint http://localhost:11434/v1 --equation-model qwen2.5-vl:7b \
--figure-endpoint https://api.openai.com/v1 --figure-model gpt-5.4-nano-2026-03-17 \
--output rich.json
# Reuse a pre-computed structure JSON (skip ONNX)
railreader2-cli structure paper.pdf --analyze --output structure.json
railreader2-cli vlm paper.pdf --from-structure structure.json --all --output vlm.json
export — convert PDF to Markdown
Exports a PDF to structured Markdown using layout analysis, VLM transcription, and annotation extraction. Heading hierarchy is resolved by matching detected heading blocks against the PDF outline tree. Degrades gracefully depending on available tools.
railreader2-cli export <pdf> [options]
| Option | Description |
|---|---|
--output <path> | Markdown output file (default: stdout) |
--pages <range> | Page range (e.g. 1,3,5-10) |
--no-page-breaks | Omit page break markers (---) between pages |
--no-vlm | Disable VLM transcription (placeholders instead) |
--no-annotations | Exclude annotations from output |
--figure-dir <dir> | Save figure PNGs and reference them in the Markdown |
--endpoint / --model / --api-key | VLM overrides (same as vlm command) |
--concurrency <n> | Parallel VLM requests (default: 2) |
--prompt-style <style> | instruction (default) or ocr |
--no-structured-output | Disable JSON schema response format |
# Basic export (text + headings, equations/figures as placeholders)
railreader2-cli export paper.pdf --no-vlm --output paper.md
# Full fidelity with VLM (LaTeX equations, Markdown tables, figure descriptions)
railreader2-cli export paper.pdf \
--endpoint https://api.openai.com/v1 --model gpt-5.4-nano-2026-03-17 \
--output paper.md
# Export with figure images saved to disk
railreader2-cli export paper.pdf --figure-dir ./figures --output paper.md
Graceful degradation: With ONNX + VLM, you get full fidelity (headings, LaTeX, pipe tables, figure images). With ONNX only (no VLM), equations and figures become placeholders and tables render as code blocks. Without either, the output is plain text per page with heading markers from the PDF outline.
package / unpack — reading packages
package bundles a PDF with the annotations, bookmarks, portals, rotation and
reading position RailReader2 has stored for it into a .railreading file
(see Moving a reading session to another computer).
unpack checks a package and extracts its PDF and JSON files. It doesn't add
anything to RailReader2's own storage: open the package in the app to restore the session.
railreader2-cli package <pdf> [options]
railreader2-cli unpack <package> [options]
| Option | Description |
|---|---|
--output <path> | package: file to write (default: <name>.railreading beside the PDF) |
--allow-encrypted | package: package a password-protected PDF (it stays encrypted; notes are stored as plain text) |
--password <pwd> | package: password of an encrypted PDF, to read its annotations |
--output-dir <dir> | unpack: where to extract (default: a folder named after the package) |
library — search the library from the command line
library search runs a library search and prints the
matches. library status shows how many documents, pages and notes the library holds
and its size. Both only read the app’s library; they never change it, so they are safe to run
while the app is open.
railreader2-cli library search "wild bootstrap" [--json] [--limit 20]
railreader2-cli library status [--documents]
| Option | Description |
|---|---|
--json | search: print the results as JSON |
--limit <n> | search: the most results to print (default: 20) |
--documents | status: also list every document |
Settings
Press Ctrl+, or use the menu to open Settings. Changes take effect immediately
and are saved automatically to the config file.
Settings opens in a simple view: five pages — Reading, Appearance, Auto-Scroll, Scanned Pages, and Spelling — holding the settings most readers change. Turn on Show advanced settings at the bottom of the window to reveal the fine-tuning controls on those pages and seven more pages: Rendering, Analysis, Layout Model, Performance, Models, AI Assistant, and Library. The switch is remembered. Links from in-app notices that point at an advanced page reveal the advanced view for that visit only.
Colour effect, margin cropping, and the current-line style are kept per document —
C, F, H and the View/Rail menus change only the document
you're looking at. Settings shows the focused document's values; changing one there sets both
that document and the default for documents you open later.
Reading
- Start rail reading at: Zoom level at which rail mode activates (default 3.0×).
- Reading pace: Relaxed, Normal (default) or Brisk. Sets how quickly the view glides between lines, how fast hold-to-scroll moves and accelerates, and the auto-scroll pause at the end of each line, all together. Shows Custom once any of those has been tuned by hand (including with the rail toolbar's speed slider). Advanced: the individual values — line-to-line glide (ms), hold-to-scroll start and top speed, time to reach top speed (s), and auto-scroll line pause (ms, 0 to disable).
- Mark the line you're on: Don't mark it / Highlight it / Dim the other lines /
Highlight and dim — the same two effects as the
HandFkeys. Highlight colour: Auto, Yellow, Cyan, Green, None. Advanced: highlight opacity, dim amount, and the space kept around the line. - Crop page margins: Fit pages to their detected content (see Margin cropping).
- Scroll continuously from page to page: Off by default. Lets browse-mode mouse-wheel scrolling flow smoothly across page boundaries instead of jumping page to page — see Continuous scrolling under Basic Navigation. Takes effect immediately.
- Reading Guide (only shown once experimental features are enabled): how the guide
follows the pointer — steer, point while holding
Shift, or point always — and whether to mark the word being read (see Reading guide). - Advanced: Enable experimental features — shows features that are still rough around the edges and may change or be removed. Currently adds the reading guide.
- Advanced: Jump distance — percentage of the visible width for jump mode (5–80%).
Appearance
- Dark mode: Switch the UI to a dark theme. Takes effect immediately.
- Menu and panel text size: Scales all UI text (default 1.25×).
- Colour effect and Strength: The page colour filter (see Colour Effects).
- Advanced: Motion blur during scroll and zoom, and its amount; Pixel snapping, which quantises the camera to the pixel grid to reduce text shimmer while moving.
Auto-Scroll
- Stop and wait at: Headings, equations and algorithms, tables, figures and charts (all on by default). Unchecked types flow through like prose; column and page breaks always stop. Advanced: the full per-block-type list.
- Also start it by holding D or →: Optionally auto-start auto-scroll after
holding
D/Right. Advanced: the hold time. - Scroll speed is set with the rail toolbar's slider; the end-of-line pause follows Reading pace.
Scanned Pages
A scanned page is a picture of text. It carries no text layer, so everything built on one stops working: line-by-line rail reading, search, text selection, table cells, Markdown export, and VLM grounding. Text recognition (OCR) reads the text back off the image so those features behave as they would on a born-digital page. It is off by default and costs nothing until you turn it on.
- On scanned pages: Do nothing (default) does nothing. Find the lines only detects where the lines of text are without reading them — enough to restore rail mode's line-by-line movement on a scan, though search and selection still have nothing to work with. Read the text detects and recognises the text, restoring every text-dependent feature; pair it with the PP-DocLayout-S layout model (advanced view → Layout Model) for the best results. Changing this drops cached analysis for affected pages, so open scans re-analyse immediately.
- Advanced: Skew correction: Scans are rarely square on the glass, and line detection is exactly the step a tilt breaks — under a degree is enough to fragment a paragraph into a couple of huge rail lines, or to fuse neighbouring lines into one. This measures the page's tilt from the OCR results and compensates when grouping text into lines; square pages are left untouched. On by default, and disabled while scanned pages are set to Do nothing, since the tilt is measured from the OCR results.
- Advanced: Language pack: The bundled recogniser reads Latin-script text well and little else. The optional PP-OCRv6 packs add broad multilingual coverage (Latin + CJK and more) in three tiers. Press Download language pack — files are saved to your config folder, so this works from a read-only AppImage — then restart.
| Pack | Download | Recognition speed |
|---|---|---|
| Tiny | ~6 MB | Fastest |
| Small | ~31 MB | Moderate |
| Medium | ~138 MB | Slowest — a minute or more per scanned page is normal |
Tiny or Small are the right default for reading. Full recognition is CPU-heavy and runs on its own worker thread, separate from layout analysis, so a scanned page's recognition no longer blocks layout analysis of other open documents. It still queues behind any other scanned page already being recognised, though, since OCR itself runs on a single thread. On the Medium pack a page can still take a minute or more — it isn't frozen, and the session log records each page as it completes. (GPU acceleration for OCR speeds up the larger packs considerably.)
Spelling
- Check spelling in notes (on by default) and Dictionary (British and American English bundled). Advanced: the folder for extra Hunspell dictionaries, and your personal dictionary (add or remove words). See Spell checking in notes.
Advanced-only pages
- Rendering — Render quality: Pick a render-DPI preset — Ultra (800 DPI), Quality (600), High (525, the default), Balanced (450), Medium (400), Performance (350), or Custom. Higher presets re-rasterise pages at a greater DPI cap for sharper text and deeper zoom, at the cost of more memory and more frequent re-renders; lower presets favour fluidity. The change applies to the open page immediately — no restart. With Custom, set your own maximum DPI (150–1200) and tier step (the DPI granularity at which the page re-rasterises).
- Analysis: Lookahead pages, background analysis range, and page cache range; Rail stops on (which block types rail mode navigates — toggling doesn't require re-running analysis); Centred block types (which block types are centred horizontally when narrower than the viewport; headings are excluded by default so they stay left-aligned with surrounding text).
- Layout Model: Choose between Docling Heron-INT8 (default, bundled, ~66 MB), PP-DocLayoutV3 (~125 MB, model-supplied reading order), and the lightweight PP-DocLayout-S, with a Download model button. See the layout model guide for trade-offs. Custom layout model: optionally replace the built-in model with your own ONNX (PP-style I/O contract) + class-mapping JSON. Changing the model needs a restart.
- Performance — GPU acceleration: Off by default. A preset picker (CPU only / Faster page navigation / Faster scanned-document OCR) or individual toggles run layout analysis or OCR on your GPU via WebGPU — not both at once, so turning one on turns the other off. Layout on GPU is roughly 8–10× faster on supported hardware and applies only to Docling Heron and PP-DocLayoutV3 (PP-DocLayout-S and any custom model always run on CPU); OCR on GPU mainly helps the larger language packs. Everything falls back to CPU automatically if no compatible GPU is found. Needs a restart. Heron's GPU model is a separate one-time download (the in-app Download GPU model button); PP-DocLayoutV3 needs no extra download.
- Performance — Display GPU (Linux only): on a laptop with both an integrated and a discrete GPU, the window is drawn on the integrated one by default, which can make scrolling stutter on a large or high-resolution window. Prefer the discrete GPU for drawing switches it. Takes effect after a restart.
- Models: Read-only — which layout model, OCR language pack, and accelerators are actually running this session, what a restart would change (Pending), and advisories with a one-click fix for combinations that work against each other.
- AI Assistant: The vision-language-model endpoint for Copy as LaTeX — see Copy as LaTeX (VLM).
- Library: How many documents, pages and notes the library search holds and how much space it takes, with Rebuild Index and Clear Index (see Privacy). AI Tools: let AI tools read your library, connect Claude Code, Claude Desktop or Codex, and hide folders (see AI tools).
Config file
Configuration is stored at ~/.config/railreader2/config.json (Linux) or
%APPDATA%\railreader2\config.json (Windows). You can edit it directly;
restart the app to apply changes.
Troubleshooting
RailReader2 writes a diagnostic log during each session. If you encounter a problem, the log helps developers understand what happened.
The app seems to freeze on a scanned page
Almost always OCR working, not a crash. Full recognition runs on its own worker thread (separate from layout analysis, so it no longer blocks other open documents), but a second scanned page still queues behind one already being recognised — and with the Medium language pack a single page can take a minute or more. Switch to the Tiny or Small pack (Settings → Scanned Pages, advanced view), or set scanned pages to Find the lines only, which restores rail reading on scans without the recognition cost.
“OCR model failed to load”
The selected language pack isn't installed. Open Settings → Scanned Pages with Show advanced settings on, press Download language pack, and restart. Recent versions fall back to the bundled recogniser instead of disabling OCR, so this message means only that your chosen pack is unavailable — not that OCR is broken.
A scan reads as one giant rail line
Line grouping is being defeated by page tilt. Check that Skew correction is enabled (Settings → Scanned Pages, advanced view) and that scanned pages are set to Find the lines only or Read the text — skew is measured from the OCR results, so it can do nothing with OCR off. If it is already on, the page may exceed the ±5° correction limit, or carry two differently-tilted columns, which the correction deliberately declines to guess at.
Rail mode works, but figures and tables aren't recognised
The layout model couldn't be loaded, so railreader2 has fallen back to a simpler layout built from the PDF's text layer. Rail reading still moves line by line, but blocks aren't classified, so anything that depends on block types — auto-scroll stops, the Index pane, semantic jumps, figure portals — has nothing to work with. Settings → Models (advanced view) shows Text-only (no layout model) in this case; download one from Settings → Layout Model if needed. A scan with no text layer also needs OCR for this fallback to find any text.
Exporting the log
- Help → Export Diagnostic Log… opens a save dialog to export a copy of the current session log.
- Help → About shows the log file path at the bottom of the dialog. Click the copy icon next to the path to copy it to the clipboard, then attach the file to a bug report.
Log file location
- Linux:
~/.config/railreader2/session.log - Windows:
%APPDATA%\railreader2\session.log - macOS:
~/Library/Application Support/railreader2/session.log
The log is overwritten at the start of each session. Old .log files are
automatically removed after 7 days by the cleanup service.
Controls & Icons
The toolbar and the panel controls use a set of crisp Lucide vector icons that inherit the theme text colour and scale with the UI font size. Here is what each one does.
| Icon | Name | Action |
|---|---|---|
| Toolbar | ||
| Browse / Pan | Pan the page and click to navigate — the default mode | |
| Text Select | Select text on the page to copy | |
| Copy | Copy the selected text (Ctrl+C) | |
| Start rail here | Click, then click where to begin rail reading at the current zoom (R starts at the view centre) | |
| Freeze | Freeze panes — pin rows, columns, or both while the page scrolls (Freeze Panes) | |
| Annotate | Enter annotation mode (Ctrl+E) | |
| Annotation tools (toolbar, shown in Annotation Mode) | ||
| Highlight | Drag over text to highlight | |
| Underline | Drag over text to underline | |
| Strikethrough | Drag over text to strike through | |
| Squiggly | Drag over text for a squiggly underline | |
| Pen | Freehand drawing | |
| Rectangle | Draw a rectangle outline | |
| Text note | Drop a collapsible popup note | |
| Text box | Drag a box, then type its text (typewriter-style) | |
| Eraser | Erase annotations under the cursor | |
| Colour | Shared 5-colour palette (yellow/green/red/blue/black) for every colour-capable tool | |
| Thickness | Stroke thickness for the pen and rectangle only (thin / normal / thick) | |
| Panel & navigation | ||
| Sidebar | Show or hide the side panel (left of the tab strip) | |
| Add bookmark | Bookmark the current page (Bookmarks section) | |
| Back | Return to your previous location after a jump | |
| Pause | Pause auto-scroll (rail toolbar) | |
| Clear / Close | Clear the search, or close a popup note | |
| Overflow | List all open tabs when the tab bar is full | |
Keyboard Shortcuts
| Key | Action |
|---|---|
| General | |
| Ctrl+O | Open file |
| Ctrl+W | Close tab |
| Ctrl+Tab | Next tab |
| Ctrl+Q | Quit |
| Ctrl+, | Settings |
| Ctrl+M | Toggle minimap |
| Ctrl+Shift+M | Toggle margin cropping |
| Ctrl+Shift+O | Open Outline section |
| Ctrl+Shift+B | Open Bookmarks section |
| Ctrl+Shift+I | Open Index section (figures / tables / equations) |
| Ctrl+Shift+H / G / T / E | Jump to next heading / figure / table / equation |
| Ctrl+L | Copy block as LaTeX (VLM) |
| Ctrl+G | Go to page |
| Ctrl+\ | Split editor (add a pane to the right) |
| Ctrl+Shift+\ | Close the focused pane |
| Ctrl+R / Ctrl+Shift+R | Rotate view clockwise / counter-clockwise |
| F1 | Keyboard shortcuts dialog |
| F11 | Toggle fullscreen |
| Navigation | |
| PgDn / PgUp | Next / previous page |
| Home / End | First / last page |
| Space | Next line (rail) or next page |
| + / - | Zoom in / out |
| 0 | Fit page to window |
| Shift+D | Toggle debug overlay |
| U | Rotate to read the current sideways rail block (press again to reset) |
| Rail Mode | |
| R | Start rail here at the current zoom (press again or Escape to exit) |
| K | Reading guide on/off (experimental; enable it in Settings first) |
| Z | Freeze panes (rows and columns) / unfreeze |
| Down / S | Next line |
| Up / W | Previous line |
| Right / D | Scroll forward (hold) |
| Left / A | Scroll backward (hold) |
| Shift+Right / Shift+Left | Short jump — half distance (jump mode) |
| Home / End | Line start / end |
| P | Toggle auto-scroll (semi-automatic; D/S to continue when parked) |
| J | Toggle jump mode |
| B | Add bookmark for current page |
| Alt+Left / ` (backtick) | Navigate back |
| Alt+Right | Navigate forward |
| C | Cycle colour effect on the focused document |
| F | Toggle line focus dim |
| H | Toggle line highlight |
| [ / ] | Adjust speed or jump distance (±5) |
| Ctrl+[ / Ctrl+] | Fine adjust speed or jump distance (±1) |
| Shift+[ / Shift+] | Adjust blur intensity (±0.05) |
| Ctrl+Shift+[ / ] | Fine adjust blur intensity (±0.01) |
| Ctrl+Drag | Free pan/zoom in rail mode (release to snap back) |
| Hold Ctrl ~1 s | Keep free pan on (tap Ctrl to snap back) |
| Click | Jump to block |
| Search & Annotations | |
| Ctrl+F | Open search panel |
| Ctrl+Shift+F | Search all your documents (Library) |
| F3 / Shift+F3 | Next / previous match |
| Ctrl+E | Toggle annotation mode |
| 1 / 2 / 3 / 4 / 5 | Highlight / Pen / Rectangle / Text Note / Eraser |
| Right-click | Block actions (Copy as LaTeX / Markdown / Description / Image) + toggle Annotation Mode |
| Ctrl+Z | Undo |
| Ctrl+Y / Ctrl+Shift+Z | Redo |
| Delete / Backspace | Delete selected annotation (browse mode) |
| Ctrl+C | Copy selected text, or the selected annotation |
| Ctrl+X | Cut selected annotation |
| Ctrl+V | Paste annotation onto the current page |
| F7 | Next misspelling (in the note editor) |
| Escape | Cancel tool / close search / stop auto-scroll / exit fullscreen |