diff --git a/docs/developer/ui-controls.md b/docs/developer/ui-controls.md index a839752d..30979624 100644 --- a/docs/developer/ui-controls.md +++ b/docs/developer/ui-controls.md @@ -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 diff --git a/docs/index.md b/docs/index.md index ba14fcd9..d9d32b17 100644 --- a/docs/index.md +++ b/docs/index.md @@ -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 diff --git a/docs/user/dashboard.md b/docs/user/dashboard.md index 68eca8fb..1a2316e0 100644 --- a/docs/user/dashboard.md +++ b/docs/user/dashboard.md @@ -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. diff --git a/docs/user/frontend-guide.md b/docs/user/frontend-guide.md deleted file mode 100644 index d2da31bb..00000000 --- a/docs/user/frontend-guide.md +++ /dev/null @@ -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)_ diff --git a/docs/user/library-browsing.md b/docs/user/library-browsing.md index edf21265..223819cb 100644 --- a/docs/user/library-browsing.md +++ b/docs/user/library-browsing.md @@ -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. diff --git a/docs/user/podcasts.md b/docs/user/podcasts.md new file mode 100644 index 00000000..d0bcbbf8 --- /dev/null +++ b/docs/user/podcasts.md @@ -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. diff --git a/docs/user/profile-guide.md b/docs/user/profile-guide.md index ec8a27c8..ee0b69bb 100644 --- a/docs/user/profile-guide.md +++ b/docs/user/profile-guide.md @@ -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. diff --git a/docs/user/settings-guide.md b/docs/user/settings-guide.md deleted file mode 100644 index 4a2ee24c..00000000 --- a/docs/user/settings-guide.md +++ /dev/null @@ -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)_ diff --git a/docs/user/user-areas.md b/docs/user/user-areas.md deleted file mode 100644 index b6b89889..00000000 --- a/docs/user/user-areas.md +++ /dev/null @@ -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)_ diff --git a/docs/user/user-guide.md b/docs/user/user-guide.md index 792a3911..85b45f93 100644 --- a/docs/user/user-guide.md +++ b/docs/user/user-guide.md @@ -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).