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
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
```controls
@@ -127,7 +170,7 @@ where: Podcast page → episodes area
does: Queues every episode of the feed for download.
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.
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
- [Library Browsing](user/library-browsing.md) - browsing and searching your library
- [Collections](user/collections.md) - manual and ⚡ smart shelves, books and episodes
- [Podcasts](user/podcasts.md) - feeds, downloads, listening
- [Dashboard](user/dashboard.md)
- [Themes](user/themes.md)
- [Calibre Integration](user/calibre-integration.md)
- [Settings Guide](user/settings-guide.md)
- [Profile Guide](user/profile-guide.md)
- [Admin Guide](user/admin-guide.md)
- [Frontend Guide](user/frontend-guide.md)
### 👨‍💻 For Developers
docs/user/dashboard.md
+45 -35
View File
@@ -1,52 +1,62 @@
# 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%)
- **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
### This Week
### 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
2. Click the **Customize Dashboard** icon button
3. Toggle the collection on or off
4. Click "Save Changes"
1. Pick the library in the **Library** bar (a specific library, or
**All Libraries**) — settings are saved per library
2. Click the **Customize Dashboard** button in the Library bar
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")
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"
## Custom sections
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
- **Arrow Keys**: Scroll carousels horizontally
- **Enter**: Open selected book
- **Tab** moves between shelves and books; **Enter** opens the focused book
- **Arrow keys** scroll the focused shelf sideways
- 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.
### Touch Gestures (Mobile)
- **Swipe**: Drag carousel left/right to scroll
- **Tap**: Open book details
*Finding your way back:* the dashboard is the page with the **Library** bar —
the only place with the **Customize Dashboard** button.
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
- A **sort** dropdown (title, author, date added, page count)
- A **Filters** button that opens the filter drawer (author, tags, series, and more)
- **Save**, **Load**, and **Clear** buttons for filter presets
Saved filters pair naturally with [smart collections](collections.md): a
filter answers "what matches right now?", a smart collection keeps matching
forever.
## How to Save a Filter
## Opening a book
1. Navigate to the **All Books** page
2. Click **Filters** to open the drawer, set your desired filters, and click **Apply Filters**
3. Click the **Save** button in the toolbar
4. Enter a name for your filter (e.g., "My Sci-Fi Books")
5. Click **Save**
Click any cover to open the book's detail page — description, files, your
progress, actions to read or listen, and the places to edit metadata or fix
what a scan guessed wrong. The detail page is the hub: series links,
reviews, bookmarks, and the edit modal all live there.
## Loading Saved Filters
## Series
1. Click the **Load** button to open the **Saved Filters** dropdown
2. Click a filter's name to apply it
3. The filter values are applied instantly, without a page reload
A book's detail page links to its **series page** — every book in that
series, in order, for the same library. Series are one of the fields the
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
2. Click the trash icon next to the filter you want to remove
3. Confirm deletion
**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
*Finding your way back:* **All Books** is the wall-of-covers page with the
**Filters** button; the same toolbar pattern is what you'll see on the
Podcasts page.
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
2. Select **Profile**
3. Edit any fields in the "Account Information" section
4. Click **Save Changes**
5. Changes take effect immediately
| Field | What it does |
| --- | --- |
| **Username** | Your login name — must stay unique |
| **Email Address** | Must stay unique |
| **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)
- **Email** - Your email address (must be unique)
- **First Name** - Optional display name
- **Last Name** - Optional display name
- **Theme** - Your preferred color scheme
About the two theme doors: the profile's **Theme** select offers seven
quick picks. The sidebar's **Appearance** panel offers the full collection —
[Themes and Wood Paneling](themes.md) covers it, including the bookshelf
wood textures, which are per-browser and not part of your account.
## 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
2. Scroll to "Change Password" section
3. Enter your **current password**
4. Enter your **new password**
5. **Confirm** your new password
6. Click **Update Password**
The **Danger Zone** at the bottom holds **Remove My Account**. Deletion
removes your account and everything personal to it — profile, reading
progress and history, device registrations, your collections — and keeps the
libraries themselves, since books belong to the library, not to you. It
cannot be undone.
### Password Requirements
The last administrator cannot delete their own account — one admin must
always remain.
- Minimum 8 characters
- Must contain uppercase, lowercase, number, and special character
- Must match confirmation field
- 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.
Administrators can also edit other users' profiles (including resetting a
password without the current one) from the admin area; that is covered with
the rest of the admin docs.
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
- Installing and upgrading the APK
- Connecting to a self-hosted server over LAN
- The Android 16+ local-network permission
- Troubleshooting login failures
## Where to go
- **[KOReader Setup Guide](devices/koreader-setup.md)** - Complete guide for KOReader
- Installation on Kindle/Kobo/PocketBook
- Plugin setup with server-side device approval
- Progress, bookmark, highlight, and note sync
- OPDS catalog access
- Troubleshooting
| You want to... | Read |
| --- | --- |
| Learn the layout: dashboard, shelves, customizing | [Dashboard](dashboard.md) |
| Browse, search, and sort your books | [Browsing your library](library-browsing.md) |
| Build shelves — by hand or with rules | [Collections](collections.md) |
| 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)
- In the meantime, KOReader works great on Kobo hardware
New here? The usual path is: browse [your library](library-browsing.md),
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
- What is Universal Sync?
- Supported devices
- Book matching and auto-linking
- Conflict resolution
- Best practices
Some screens (user management, server settings, library folders) are admin
territory; [Admin Guide](admin-guide.md) is the door, and the admin docs are
being expanded separately.
## 📚 Calibre Integration
- **[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)
**Looking for developer documentation?** See the
[Developer Portal](../developer/development.md).