README file from
GithubPage 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)
- Open Settings > Community plugins.
- Turn on Community plugins.
- Click Browse and search for
Page Flow. - Click Install, then Enable.
Beta Testing via BRAT
- Install the BRAT plugin from Community plugins.
- In BRAT settings, click Add Beta plugin.
- Enter
shallow1992/obsidian-page-flow. - 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.