Page Flow for Obsidian

Effortless note reading, inspection, and triage in Obsidian. Scroll page-by-page and seamlessly transition to the next file with single hotkeys.

Inspired by RSS readers and e-book pagers, Page Flow lets you glide through entire folders of notes without ever touching your mouse or trackpad.

---

✨ Key Features

1. 🔄 Hybrid Single-Key Navigation (Scroll or Next / Previous File)

• Forward Navigation:
  • Press your hotkey to scroll down note content by a configurable percentage (default: 85%).
  • When the bottom of the current note is reached, pressing the hotkey again seamlessly opens the next file in the folder, positioning you right at the top.
• Symmetrical Backward Navigation:
  • Scrolling up reaches the top of the current note, then seamlessly opens the previous file—positioned right at the bottom so you can read backwards naturally.
• Fly-by Protection:
  • During rapid scrolling, target reaches the bottom safely while the view smoothly catches up, preventing premature or accidental file switches.

2. 📂 Visual File Explorer Order Tracking

• Naturally follows the visual top-to-bottom file order seen in Obsidian's left sidebar File Explorer.
• Supports manual folder file arrangements and custom sorting modes.
• Strictly scoped to the current folder—never accidentally jumps out into unrelated directories.
• Six additional sorting rules are also available (alphabetical ascending/descending, creation time, modification time).

3. 🚀 Continuous Momentum Physics & Tuning

• Rapid Consecutive Tap Acceleration:
  • Rapidly tapping the hotkey seamlessly ramps up cruising speed without resetting velocity or stuttering.
  • Dynamically scales both velocity and single-tap distance in sync to maintain smooth flight.
• Configurable Queue Cap:
  • Set the maximum queued screens (default: 5.0 screens, range: 1.0 to 15.0). Keeps deceleration crisp and predictable.
• Configurable Acceleration Multiplier:
  • Tune maximum speed from 1.0x (steady, no acceleration) up to 5.0x (ultra-fast cruising). Default is a mild, controllable 2.2x.
• CodeMirror 6 Layout-Shift Resistance:
  • Reliably delivers the intended scroll distance even when CodeMirror dynamically recalculates virtual line heights in long documents.

4. ⌨️ Dedicated Independent Commands

In addition to hybrid navigation, dedicated commands are available for focused workflows:

• Scroll page down / Scroll page up: Pure in-note scrolling without switching files.
• Go to next file in folder / Go to previous file in folder: Instant file navigation regardless of scroll position.

---

⌨️ Recommended Hotkey Setup

Configure your preferred hotkeys in Settings > Hotkeys (search for Page Flow):

Command	Recommended Hotkey	Description
Forward: Scroll down or go to next file	Alt + Space (or PageDown, Alt + J)	Primary forward reading step
Backward: Scroll up or go to previous file	Alt + Shift + Space (or PageUp, Alt + K)	Primary backward review step
Scroll page down	Space / PageDown	In-note scroll only
Scroll page up	Shift + Space / PageUp	In-note scroll only
Go to next file in folder	Alt + Down	Jump to next note
Go to previous file in folder	Alt + Up	Jump to previous note

---

⚙️ Settings & Defaults

Setting	Default	Range / Options	Description
Scroll amount (%)	85%	50% – 100% (step: 5%)	Percentage of viewport height to scroll on each step. Retains 15% context for smooth reading.
Smooth scrolling	ON	Toggle	Animates scrolling smoothly between page steps.
Scroll animation duration (ms)	280 ms	100 – 1,000 ms (step: 20 ms)	Base duration of smooth scroll animation. Accelerates on rapid taps.
Maximum queued scroll (screens)	5.0	1.0 – 15.0 (step: 0.5)	Maximum screens to queue ahead during rapid presses. At 85% scroll, 5 screens allows ~6 rapid taps.
Maximum acceleration multiplier	2.2	1.0x – 5.0x (step: 0.1x)	Maximum cruising velocity multiplier under rapid consecutive key presses.
File sort order	File explorer order	7 choices	Order for navigating folder files. Follows sidebar layout by default.
Loop folder navigation	OFF	Toggle	When reaching the last file, cycles back to the first file.
Boundary threshold (px)	10 px	0 – 50 px (step: 5 px)	Buffer in pixels to detect note top/bottom boundaries.
Reset to default settings	—	Button	Resets all settings back to recommended initial values with one click.

---

📦 Installation

From Obsidian Community Plugins (Recommended once approved)

1. Open Settings > Community plugins.
2. Turn on Community plugins.
3. Click Browse and search for Page Flow.
4. Click Install, then Enable.

Beta Testing via BRAT

1. Install the BRAT plugin from Community plugins.
2. In BRAT settings, click Add Beta plugin.
3. Enter shallow1992/obsidian-page-flow.
4. Enable Page Flow in Community plugins.

---

🛠️ Development & Testing

All builds, tests, and verifications run isolated inside Docker:

# Run unit tests (Vitest)
docker compose run --rm page-flow npm test

# Build production bundle (main.js)
docker compose run --rm page-flow npm run build

# Watch mode for local development
docker compose run --rm page-flow npm run dev

---

🔒 Privacy & Security

• 100% Local & Offline: Page Flow performs zero network requests, contains zero telemetry or tracking code, and never accesses external services.
• Zero Plaintext Secrets: No credentials or tokens are ever stored.
• Safe Read-Only Navigation: Page Flow only navigates active leaves and reads folder contents—it never modifies, deletes, or overwrites your notes.

---

📄 License

MIT License. See LICENSE for details.