From b4c956aed4189b858ec81a5b808e4411272e1c88 Mon Sep 17 00:00:00 2001 From: John O'Keefe Date: Thu, 17 Sep 2026 20:13:45 -0400 Subject: [PATCH] =?UTF-8?q?docs(user):=20web=20reader=20guide=20=E2=80=94?= =?UTF-8?q?=20navigation,=20touch=20selection,=20highlights?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit User-facing documentation for the rebuilt web reader (§6.5 of the app handoff): swipe-to-page / tap-for-menu touch navigation, long-press word selection with drag extension and handles, the selection popover (color dots, notes with save-together-on-create, copy incl. plain-HTTP LAN, edit/delete by tapping a painted highlight), below-the-selection popover placement rationale, PDF/comic behavior, and annotations drawer. Linked from the user documentation portal and the docs index quick links / quick-find tables. --- docs/index.md | 2 + docs/user/reader-guide.md | 81 +++++++++++++++++++++++++++++++++++++++ docs/user/user-guide.md | 8 ++++ 3 files changed, 91 insertions(+) create mode 100644 docs/user/reader-guide.md diff --git a/docs/index.md b/docs/index.md index b841e0d..fad5475 100644 --- a/docs/index.md +++ b/docs/index.md @@ -77,6 +77,7 @@ Complete guide to Bookhoard documentation. Find what you need quickly. | **Deploy Bookhoard** | [Operations Portal → Troubleshooting](operations/troubleshooting.md) | | **Contribute code** | [Contributing Portal → Development Guide](contributing/development.md) | | **Understand sync** | [User Portal → Sync Guide](user/sync-guide.md) | +| **Read in the browser** | [User Portal → Web Reader Guide](user/reader-guide.md) | --- @@ -90,6 +91,7 @@ Complete guide to Bookhoard documentation. Find what you need quickly. | ...set up KOReader? | [KOReader Setup Guide](user/devices/koreader-setup.md) | | ...use a Kobo? | [Kobo Setup Guide](user/devices/kobo-setup.md) - native sync coming soon; KOReader works today | | ...understand sync? | [Sync Guide](user/sync-guide.md) | +| ...read in the browser? | [Web Reader Guide](user/reader-guide.md) - reading, highlights, notes | | ...resolve conflicts? | [Sync Guide](user/sync-guide.md) - Managing Conflicts | | ...troubleshoot deployment? | [Troubleshooting Guide](operations/troubleshooting.md) | | ...use the API? | [API Reference](developer/api-reference.md) | diff --git a/docs/user/reader-guide.md b/docs/user/reader-guide.md new file mode 100644 index 0000000..83a3c55 --- /dev/null +++ b/docs/user/reader-guide.md @@ -0,0 +1,81 @@ +# Web Reader Guide + +Bookhoard's built-in web reader works in any modern browser — desktop or +mobile — and keeps your position, highlights, bookmarks, and notes in sync +with the Android app and KOReader. + +## Opening a Book + +From your library or book page, click **Read**. The reader opens in an +immersive view with the book's cover, title, and chapter in the top bar +(EPUB) or page number (PDF/comics). + +## Navigation + +### On a phone or tablet (touch) + +| Gesture | Action | +|---|---| +| **Swipe** left / right | Turn the page | +| **Tap** once | Toggle the reader menu (headers, settings, drawers) | +| **Tap** in a corner zone | With the menu open: jump back / forward by chapter | + +Paging is swipe-only by design: taps are reserved for the menu so a page +turn can never fire while you're trying to select text. + +### On desktop + +- Scroll wheel, trackpad, arrow keys, or **Page Up / Page Down** to page +- Click the progress bar (bottom, with the menu open) to jump +- Contents drawer for the table of contents; Pages grid for PDF/comics + +## Text Selection & Highlights + +### Selecting text (touch) + +1. **Press and hold** a word (~half a second) until it highlights +2. **Drag** to extend the selection word by word — it stays on the + visible page +3. **Drag the round handles** (EPUB) to fine-tune the start and end + points +4. Lift your finger and pause — the highlight menu appears **below** the + selection, underneath the browser's own copy menu + +The browser's address bar hides while a selection is active to give the +page room; it returns as soon as the selection is cleared. + +### Creating a highlight or note + +With the selection menu open: + +- **Color dots** — tap one to highlight immediately in that color +- **Pencil** — opens a note; write it and tap **Highlight with note** + to save the highlight and its note together +- **Copy** — copies the selected text (works even over plain HTTP on + your LAN) +- While the note editor is open, you can still change the color — the + popover stays put until you save or cancel + +### Editing or removing a highlight + +Tap anywhere on a painted highlight to reopen it in the menu. From there +you can change its color, edit the note (pencil → **Save note**), or +delete it (trash icon). Tapping anywhere else closes the menu. + +### PDFs and comics + +Text selection works the same way on PDFs. Highlights are stored as +page-anchored rectangles and sync to the Android app. Comics/manga +libraries disable annotation (bookmarks still work). + +## Notes & Bookmarks + +The **annotations drawer** (right side, from the open menu) lists your +highlights, standalone notes, and bookmarks for the book — tap any entry +to jump to it. + +## Where Reading Position Is Stored + +Position, highlights, bookmarks, and notes sync automatically through the +server (see the [Sync Guide](sync-guide.md)). Close the tab whenever you +like — the reader resumes exactly where you left off on any device. diff --git a/docs/user/user-guide.md b/docs/user/user-guide.md index 583e442..c01cc2c 100644 --- a/docs/user/user-guide.md +++ b/docs/user/user-guide.md @@ -36,6 +36,14 @@ Learn how to configure your e-reader devices to sync with Bookhoard: - Troubleshooting - Best practices +## 📖 Reading + +- **[Web Reader Guide](reader-guide.md)** - Reading and annotating in the browser + - Touch navigation (swipe to page, tap for menu) + - Selecting text: long-press, drag, handles + - Highlights, notes, copy, and editing + - PDFs and comics + ## 🎨 Frontend Guide **[Frontend Guide](frontend-guide.md)** - Learn how to use the Bookhoard web interface