Bookhoard/bookhoard
0
0 Fork 0
Code Issues 1 Pull Requests Actions Packages Projects Releases 69 Wiki Activity

docs(user): dashboard, browsing, profile rewrites + new podcasts guide; trash stubs

Browse Source 
Ground-truthed against the templates this pass:
- dashboard.md: real section kinds (system shelves incl. Continue
  Series, user collections, custom sections via /custom-section
  builder), Customize Dashboard panel semantics (per-library, drag,
  switches, 10-50 items, Save Changes), Refresh, This Week widget,
  per-item Read/Listen and progress-conflict resolve actions. The old
  page listed a wrong shelf set and never mentioned custom sections.
- library-browsing.md: the file was secretly titled 'Saving Custom
  Filters' and covered nothing else. Now the browsing page: All Books
  toolbar (search, Sort, Filters -> drawer hand-off, Save/Load/Clear
  saved filters), book detail as hub, series pages, podcasts split.
- profile-guide.md: field table ground-truthed from profile_form.templ
  (username/email DO remain editable there), audio defaults (speed,
  resume rewind, keep awake), timezone rendering contract, both theme
  doors (7-pick select vs 37-theme Appearance panel), Change Password
  with live checks, Danger Zone/Remove My Account + last-admin rule.
- podcasts.md NEW: the Podcasts page had zero documentation. Subscribing
  (Add Feed -> RSS URL, library, back-catalog download, download order,
  Add & Subscribe), Continue/All Feeds, Download All, player + Play as
  Sequence cross-link.
- Trashed user-areas.md, frontend-guide.md, settings-guide.md: stubs
  whose planned content now exists as real pages (or duplicates
  profile-guide). user-guide.md rewritten as the plain-language front
  door with a go-here-when table; index.md rows updated to match.
- ui-controls.md: 10 new gate-checked entries for every newly cited
  control (Add & Subscribe via templ-entity fragment).
This commit is contained in:
John O'Keefe committed 2026-11-02 10:07:28 -05:00
1 parent ceed3ddeae
commit 9e2f216af5
10 files changed
+244 -288
Download Patch File Download Diff File Expand all files Collapse all files

No files matched your search

docs/developer/ui-controls.md
+44 -1
View File
@@ -27,6 +27,49 @@ Form-field labels inside a single modal (Name, Description…) are cited
inline in docs and not tracked here; this list carries the controls people inline in docs and not tracked here; this list carries the controls people
navigate by. navigate by.
## Dashboard, profile & podcasts
```controls
label: Customize Dashboard
where: Library bar on the dashboard (button); opens the Customize Dashboard panel
does: Opens per-library shelf arrangement — drag order, show/hide switches, items per section.
label: Save Changes
where: Customize Dashboard panel → submit
does: Saves that library's shelf arrangement.
label: Refresh
where: Library bar on the dashboard (button)
does: Re-reads libraries without a full page reload.
note: icon button with a tooltip title
label: Create Custom Section
where: the custom-section builder page (/custom-section) → page title
does: Page where a dashboard shelf is defined by filter rules or hand-picked books.
label: Update Password
where: profile page → Change Password → submit
does: Saves the new password after live requirement checks.
label: Remove My Account
where: profile page → Danger Zone
does: Deletes the account and all personal data after confirmation; blocked for the last admin.
label: Add Feed
where: Podcasts page
does: Opens the Add Podcast Feed panel.
label: Add & Subscribe
where: Add Podcast Feed panel → submit
does: Subscribes the feed and starts watching it for new episodes.
also: Add & Subscribe
note: templ source stores the ampersand entity; the rendered label reads "Add & Subscribe"
label: Download all episodes now
where: Add Podcast Feed panel
does: Grabs the feed's back catalog immediately on subscribe.
```
## Collections ## Collections
```controls ```controls
@@ -127,7 +170,7 @@ where: Podcast page → episodes area
does: Queues every episode of the feed for download. does: Queues every episode of the feed for download.
label: Download order label: Download order
where: Podcast page → feed settings where: Add Podcast Feed panel; podcast feed settings
does: Sets the ordering used when feed episodes are downloaded. does: Sets the ordering used when feed episodes are downloaded.
label: Match ALL / Group ANY header label: Match ALL / Group ANY header
docs/index.md
+1 -2
View File
@@ -27,13 +27,12 @@ Complete guide to Bookhoard documentation. Find what you need quickly.
- [Reader Guide](user/reader-guide.md) - reading, highlights, notes - [Reader Guide](user/reader-guide.md) - reading, highlights, notes
- [Library Browsing](user/library-browsing.md) - browsing and searching your library - [Library Browsing](user/library-browsing.md) - browsing and searching your library
- [Collections](user/collections.md) - manual and ⚡ smart shelves, books and episodes - [Collections](user/collections.md) - manual and ⚡ smart shelves, books and episodes
- [Podcasts](user/podcasts.md) - feeds, downloads, listening
- [Dashboard](user/dashboard.md) - [Dashboard](user/dashboard.md)
- [Themes](user/themes.md) - [Themes](user/themes.md)
- [Calibre Integration](user/calibre-integration.md) - [Calibre Integration](user/calibre-integration.md)
- [Settings Guide](user/settings-guide.md)
- [Profile Guide](user/profile-guide.md) - [Profile Guide](user/profile-guide.md)
- [Admin Guide](user/admin-guide.md) - [Admin Guide](user/admin-guide.md)
- [Frontend Guide](user/frontend-guide.md)
### 👨‍💻 For Developers ### 👨‍💻 For Developers
docs/user/dashboard.md
+45 -35
View File
@@ -1,52 +1,62 @@
# Dashboard # Dashboard
The Bookhoard dashboard provides a Carousel-style horizontal carousel interface for browsing your book library. The dashboard is your home screen: horizontal shelves ("sections") of your
books, one row after another. What each shelf contains depends on the library
you are looking at — including the **All Libraries** view, which mixes
everything you can see.
## Sections ## The three kinds of section
### Smart Sections | Kind | What fills it |
| --- | --- |
| **System shelves** | Bookhoard maintains them from your reading: **Continue Reading**, **Recently Added**, **Recently Read**, **Not Started**, **Continue Series** |
| **Your collections** | Every collection you create appears as its own shelf |
| **Custom sections** | Shelves you define yourself — by filter rules or by hand-picking books |
Smart sections are automatically generated based on your reading activity: System shelves and collections are covered by their own guides (see
[Sync Guide](sync-guide.md) for what "continue reading" means across devices,
and [Collections](collections.md) for the shelves you build). This page is
about arranging the rows.
- **Continue Reading**: Books you're currently reading (progress between 0-100%) ### This Week
- **In Progress**: Books you've started (progress > 0%)
- **Recently Added**: Newest items added to this library
- **Recently Read**: Books you've completed (100% progress)
- **Not Started**: Books you haven't read yet
### User Collections The dashboard also shows a small **This Week** summary — your reading time
and activity for the week so far. Click it to expand the detail.
Your collections appear as sections on the dashboard. To show or hide a collection's section: ## Customizing your shelves
1. Select the library in the **Library** bar 1. Pick the library in the **Library** bar (a specific library, or
2. Click the **Customize Dashboard** icon button **All Libraries**) — settings are saved per library
3. Toggle the collection on or off 2. Click the **Customize Dashboard** button in the Library bar
4. Click "Save Changes" 3. In the **Customize Dashboard** panel: drag sections into the order you
want, switch sections on or off, and set how many items each section
shows (10–50)
4. Click **Save Changes**
### Customizing Your Dashboard The **Refresh** button next to it re-reads your libraries without a full
page reload.
1. In the **Library** bar below the top bar, select the library you want to customize (a specific library, not "All Libraries") ## Custom sections
2. Click the **Customize Dashboard** icon button at the right end of the Library bar (next to Refresh)
3. **Drag sections** to reorder them
4. **Toggle visibility** with the switches
5. **Adjust items per section** (10-50 items)
6. Click "Save Changes"
Settings are saved per library. A custom section is a shelf whose contents you define — either with the same
filter rules the **Filters** drawer uses, or by picking the books yourself.
You build one on the **Create Custom Section** page (at `/custom-section` on
your server); once saved it behaves like any other shelf and can be ordered
and hidden with everything else.
### Library Switching ## Reading and listening from the dashboard
Use the **Library** dropdown in the bar below the top bar to switch between libraries (including "All Libraries"). Each library has its own dashboard settings. Point at a shelf and chevron buttons appear to scroll it. Every item carries
a direct action: **Read** opens the web reader, **Listen** opens the audio
player. If the same book has conflicting progress from two devices, the item
grows a resolve action that takes you to conflict resolution — see the
[Sync Guide](sync-guide.md).
### Keyboard Navigation ## Keyboard and touch
- **Tab**: Navigate between sections and books - **Tab** moves between shelves and books; **Enter** opens the focused book
- **Arrow Keys**: Scroll carousels horizontally - **Arrow keys** scroll the focused shelf sideways
- **Enter**: Open selected book - On touch: swipe a shelf to scroll it, tap a cover to open it
Hovering a carousel shows chevron buttons on either side for scrolling. *Finding your way back:* the dashboard is the page with the **Library** bar —
the only place with the **Customize Dashboard** button.
### Touch Gestures (Mobile)
- **Swipe**: Drag carousel left/right to scroll
- **Tap**: Open book details
docs/user/frontend-guide.md
-16
View File
@@ -1,16 +0,0 @@
# Frontend Guide
**Coming Soon**
This guide will cover:
- Navigating the Bookhoard web interface
- Browsing and searching your library
- Managing collections
- Viewing reading progress
- Using notes and highlights
- Personalizing your experience
---
_In the meantime, check out our [Device Setup Guides](devices/android-app.md) and [KOReader setup](devices/koreader-setup.md)_
docs/user/library-browsing.md
+32 -47
View File
@@ -1,58 +1,43 @@
# Saving Custom Filters # Browsing your library
The bookshelf (**All Books**) page lets you save custom filter presets for quick access. Everything starts from the **All Books** page: every book you can see in the
current library, as a wall of covers. From there you narrow, sort, and open.
## Bookshelf Toolbar ## The All Books toolbar
The All Books page has a toolbar with: - The **search box** finds titles, authors, and more as you type
- The **Sort** dropdown orders the wall (title, author, date added, page
count, and more)
- The **Filters** button opens the filter drawer — authors, tags, series,
progress, and every other field (the full how-to lives in
[Filters — the complete guide](filters/index.md); this page sticks to
browsing)
- **Save**, **Load**, and **Clear** manage your saved filters: capture the
current drawer state under a name, re-apply it any time, and delete ones
you no longer want. Saved filters are private to your account.
- A **search input** for quick text searches Saved filters pair naturally with [smart collections](collections.md): a
- A **sort** dropdown (title, author, date added, page count) filter answers "what matches right now?", a smart collection keeps matching
- A **Filters** button that opens the filter drawer (author, tags, series, and more) forever.
- **Save**, **Load**, and **Clear** buttons for filter presets
## How to Save a Filter ## Opening a book
1. Navigate to the **All Books** page Click any cover to open the book's detail page — description, files, your
2. Click **Filters** to open the drawer, set your desired filters, and click **Apply Filters** progress, actions to read or listen, and the places to edit metadata or fix
3. Click the **Save** button in the toolbar what a scan guessed wrong. The detail page is the hub: series links,
4. Enter a name for your filter (e.g., "My Sci-Fi Books") reviews, bookmarks, and the edit modal all live there.
5. Click **Save**
## Loading Saved Filters ## Series
1. Click the **Load** button to open the **Saved Filters** dropdown A book's detail page links to its **series page** — every book in that
2. Click a filter's name to apply it series, in order, for the same library. Series are one of the fields the
3. The filter values are applied instantly, without a page reload filter drawer can match on too.
## Managing Saved Filters ## Podcasts are separate
**Delete a filter:** Podcast feeds and episodes live on the **Podcasts** page, not the book wall —
see [Podcasts](podcasts.md).
1. Click the **Load** button to open the **Saved Filters** dropdown *Finding your way back:* **All Books** is the wall-of-covers page with the
2. Click the trash icon next to the filter you want to remove **Filters** button; the same toolbar pattern is what you'll see on the
3. Confirm deletion Podcasts page.
**Filter Privacy:**
Saved filters are **private to your account**. Other users cannot see or modify your filters.
## Common Use Cases
**Reading by Genre:**
1. Filter by tag: "Science Fiction"
2. Save as "Sci-Fi Books"
3. Quickly access all your sci-fi collection anytime
**Author Collections:**
1. Filter by author: "Isaac Asimov"
2. Save as "Asimov Books"
3. Switch between different author collections instantly
**Series Tracking:**
1. Filter by series: "Foundation"
2. Save as "Foundation Series"
3. Track your progress through a series
docs/user/podcasts.md
+47
View File
@@ -0,0 +1,47 @@
# Podcasts
Bookhoard is not just books: it also runs your podcast subscriptions. You
subscribe to feeds, episodes download for offline listening, and you can
play a run of episodes back-to-back — a feed, or a hand-picked sequence.
## The Podcasts page
Open **Podcasts** from the sidebar. The page is your subscriptions:
- **Continue** — the episode you were in the middle of, ready to resume
- **All Feeds** — every feed you subscribe to
- **Search** narrows your feeds and episodes
- Each feed's page holds its episodes, with **Download All** for grabbing
everything at once
Subscriptions live in your **Podcasts library** (feeds manage it themselves —
you won't see it in the regular library switcher, and it never mixes into
the book wall on **All Books**).
## Subscribing to a feed
1. Click **Add Feed** on the Podcasts page
2. In the **Add Podcast Feed** panel, paste the show's **RSS feed URL**
3. Choose the **Library** the podcast belongs to
4. Optionally: check **Download all episodes now** to grab the back catalog
immediately, and pick the **Download order** for new episodes — **Feed
order**, **Feed order (reversed)**, **Oldest first (pub date)**, or
**Newest first (pub date)**
5. Click **Add & Subscribe**
From then on Bookhoard watches the feed: new episodes appear as the show
publishes them, downloaded according to the order you picked.
## Playing episodes
Click an episode to open the audio player. The player keeps your place,
supports bookmarks, a chapter list where the show provides chapters, and
playback speed — the same speed and resume-rewind defaults you set on your
[profile](profile-guide.md) apply here.
To play many episodes in a row, use a collection: episode collections have a
**Play as Sequence** button and their own listening order — see
[Collections](collections.md).
*Finding your way back:* **Podcasts** is the sidebar page whose header reads
"Your subscriptions" — the only page with the **Add Feed** button.
docs/user/profile-guide.md
+37 -87
View File
@@ -1,99 +1,49 @@
# Profile Management Guide # Your profile
## Updating Your Profile Your profile page holds everything that is about *you* rather than your
books: account details, playback preferences, your password, and — if you
ever need it — account deletion.
Your profile contains your account information and preferences. Open it from the sidebar: click your **username** at the bottom, then
**Profile**.
### How to Update ## Account information
1. Click on your **username** at the bottom of the sidebar to expand the account menu | Field | What it does |
2. Select **Profile** | --- | --- |
3. Edit any fields in the "Account Information" section | **Username** | Your login name — must stay unique |
4. Click **Save Changes** | **Email Address** | Must stay unique |
5. Changes take effect immediately | **First Name / Last Name** | Optional display names |
| **Theme** | A quick theme picker (seven favorites — see below for the full set) |
| **Default Playback Speed** | The speed audiobook playback starts at |
| **Resume Rewind** | Jumps back a few seconds when you resume playback (**Off (exact resume)**, 5, or 10 seconds) |
| **Keep Screen Awake** | Stops the screen sleeping during playback |
| **Timezone** | All times the server shows you (activity, stats, history) are rendered in this zone |
### Fields You Can Update Changes save from the form's save button and apply immediately.
- **Username** - Your login name (must be unique) About the two theme doors: the profile's **Theme** select offers seven
- **Email** - Your email address (must be unique) quick picks. The sidebar's **Appearance** panel offers the full collection —
- **First Name** - Optional display name [Themes and Wood Paneling](themes.md) covers it, including the bookshelf
- **Last Name** - Optional display name wood textures, which are per-browser and not part of your account.
- **Theme** - Your preferred color scheme
## Changing Your Password ## Changing your password
Regular password changes are recommended for account security. On the same page, the **Change Password** section asks for your **Current
Password**, a **New Password**, and **Confirm New Password**. The
requirements are checked as you type; click **Update Password** to save.
### How to Change ## Deleting your account
1. Go to **Profile** page The **Danger Zone** at the bottom holds **Remove My Account**. Deletion
2. Scroll to "Change Password" section removes your account and everything personal to it — profile, reading
3. Enter your **current password** progress and history, device registrations, your collections — and keeps the
4. Enter your **new password** libraries themselves, since books belong to the library, not to you. It
5. **Confirm** your new password cannot be undone.
6. Click **Update Password**
### Password Requirements The last administrator cannot delete their own account — one admin must
always remain.
- Minimum 8 characters Administrators can also edit other users' profiles (including resetting a
- Must contain uppercase, lowercase, number, and special character password without the current one) from the admin area; that is covered with
- Must match confirmation field the rest of the admin docs.
- Current password must be correct
## Deleting Your Account
**⚠️ WARNING:** This action cannot be undone.
### What Gets Deleted
When you delete your account:
- Your profile information
- Reading progress and history
- Device connections
- Collection preferences
- All personal data
### What Stays
- Library books (media belongs to the library, not you)
- System settings
- Other users' accounts
### How to Delete
1. Go to **Profile** page
2. Scroll to "Danger Zone" (bottom of page)
3. Click **Remove My Account**
4. Confirm the deletion prompt
**Note:** If you're the last admin, you cannot delete your account for security reasons.
## Theme Options
Personalize your reading experience with different color themes.
### Quick Theme Switch
1. In the sidebar, open the **Appearance** panel (palette icon, near the bottom)
2. Select a theme from the list; your active theme is marked with a checkmark
3. Changes apply instantly
For the full theme list and bookshelf background (wood) options, see [Themes and Wood Paneling](themes.md).
### Available Themes
- **Tokyo Night** (default) - Blue/purple accents
- **Dracula** - Purple/pink tones
- **Nord** - Arctic, bluish-gray
- **Solarized Dark** - Warm, precise contrast
- **Monokai** - Classic vibrant colors
- **One Dark Pro** - Atom editor inspired
- **Material Dark** - Google Material Design
- **Catppuccin Mocha / Macchiato / Frappé / Latte** - Soothing pastel palettes (Latte is light)
## For Admin Users
If you're an administrator, you can also manage other users' profiles from the admin panel.
See [Admin User Management](admin-guide.md) for details.
docs/user/settings-guide.md
-15
View File
@@ -1,15 +0,0 @@
# Settings Guide
**Coming Soon**
This guide will cover:
- Account settings
- Display preferences (themes, fonts)
- Sync configuration
- Device management
- Privacy options
---
_In the meantime, check out our [Device Setup Guides](devices/android-app.md) and [KOReader setup](devices/koreader-setup.md)_
docs/user/user-areas.md
-15
View File
@@ -1,15 +0,0 @@
# User Areas Guide
**Coming Soon**
This guide will cover:
- Managing your personal library
- Uploading and organizing books
- Creating and managing collections
- Syncing across devices
- Personal settings
---
_In the meantime, check out our [Sync Guide](sync-guide.md)_
docs/user/user-guide.md
+38 -70
View File
@@ -1,79 +1,47 @@
# User Documentation # Bookhoard — start here
Welcome to the Bookhoard user documentation. This section contains guides for using Bookhoard features, setting up devices, and configuring sync. Bookhoard is a self-hosted home for the things you read and hear: your book
libraries live on your own server, you read them in the browser or on your
devices, and everything keeps track of where you are.
## 📱 Device Setup The moving parts, in one breath:
Learn how to configure your e-reader devices to sync with Bookhoard: - **Libraries** hold your books (and your podcasts run as feeds of their own)
- The **dashboard** is your home screen — shelves that update themselves
- **Collections** are shelves you build, by hand or by rules
- **Filters** answer "which books match?" — the same rules power saved
filters, smart collections, and dashboard shelves
- **Devices** — the Android app, KOReader on e-readers, and stock Kobo
firmware — stay in step with the server through **sync**
- Your **profile** holds your preferences: theme, playback defaults, password
- **[Android App Guide](devices/android-app.md)** - The native Android client ## Where to go
- Installing and upgrading the APK
- Connecting to a self-hosted server over LAN
- The Android 16+ local-network permission
- Troubleshooting login failures
- **[KOReader Setup Guide](devices/koreader-setup.md)** - Complete guide for KOReader | You want to... | Read |
- Installation on Kindle/Kobo/PocketBook | --- | --- |
- Plugin setup with server-side device approval | Learn the layout: dashboard, shelves, customizing | [Dashboard](dashboard.md) |
- Progress, bookmark, highlight, and note sync | Browse, search, and sort your books | [Browsing your library](library-browsing.md) |
- OPDS catalog access | Build shelves — by hand or with rules | [Collections](collections.md) |
- Troubleshooting | Narrow with rules, save them, reuse them | [Filters — the complete guide](filters/index.md) |
| Subscribe to shows, download, listen | [Podcasts](podcasts.md) |
| Read and annotate in the browser | [Web Reader Guide](reader-guide.md) |
| Change themes and bookshelf textures | [Themes and Wood Paneling](themes.md) |
| Edit your account, password, playback defaults | [Your profile](profile-guide.md) |
| Get the Android app talking to your server | [Android App](devices/android-app.md) |
| Use KOReader on an e-reader | [KOReader Setup](devices/koreader-setup.md) |
| Use a Kobo | [Kobo Setup](devices/kobo-setup.md) |
| Understand how it all stays in sync | [Universal Sync Guide](sync-guide.md) |
| Import from Calibre | [Calibre Integration](calibre-integration.md) |
- **[Kobo Setup Guide](devices/kobo-setup.md)** - Native Kobo sync (coming soon) New here? The usual path is: browse [your library](library-browsing.md),
- In the meantime, KOReader works great on Kobo hardware open a book, and let the [dashboard](dashboard.md) keep track of you. Sync
comes when you add a [device](devices/android-app.md).
## 🔄 Sync Configuration ## A note on admins
- **[Universal Sync Guide](sync-guide.md)** - Understanding and using sync features Some screens (user management, server settings, library folders) are admin
- What is Universal Sync? territory; [Admin Guide](admin-guide.md) is the door, and the admin docs are
- Supported devices being expanded separately.
- Book matching and auto-linking
- Conflict resolution
- Best practices
## 📚 Calibre Integration **Looking for developer documentation?** See the
[Developer Portal](../developer/development.md).
- **[Calibre Integration Guide](calibre-integration.md)** - Integrating with Calibre libraries
- What is Calibre?
- Automatic metadata import
- Setting up your Calibre library
- Supported metadata and file types
- Workflow examples
- 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
- _Coming Soon_
## 👤 User Areas
**[User Areas Guide](user-areas.md)** - Managing your personal library and settings
- _Coming Soon_
## ⚙️ Settings
**[Settings Guide](settings-guide.md)** - Configuring your Bookhoard preferences
- _Coming Soon_
## 🔐 Admin Features
**[Admin Guide](admin-guide.md)** - Administrative functions and management
- _Coming Soon_
---
**Looking for developer documentation?** See the [Developer Portal](../developer/development.md)