diff --git a/docs/user/collections.md b/docs/user/collections.md index 81418f7b..60662f2a 100644 --- a/docs/user/collections.md +++ b/docs/user/collections.md @@ -1,42 +1,118 @@ # Collections -Collections allow you to organize books across multiple libraries. +A collection is a personal shelf you name yourself. You put your books and +podcast episodes on it, and it appears as a section on your dashboard. -## Viewing Collections +That is the whole idea. Everything below is variations on it. -### From Collections Page +## The one pattern, four flavors -Navigate to **Collections** (sidebar navigation) to see all your collections. Clicking on a collection shows ALL books in that collection across all libraries. +Every collection behaves the same way on the outside: it has a name, an icon, +a color, and a list of items. The flavors differ in how items *join*: -### From Dashboard +| Flavor | How items join | Right for | +| --- | --- | --- | +| **Static** | You pick each item by hand | Curated lists — "books for the trip", "new house ideas" | +| **⚡ Smart** (books) | Rules match books live, forever | "everything by Asimov", "still not started", "over 400 pages" | +| **⚡ Smart** (podcast episodes) | Rules match episodes live — and they can play back-to-back | "catch up on my feeds", "episodes to finish" | +| **System** (built-in) | Bookhoard maintains them | Continue Reading, Recently Added, Recently Read, Not Started, Continue Series | -When viewing a specific library's dashboard, collections only show books from that library. Clicking "View All" preserves this context and shows only books from that library in the collection. +A collection holds **books and podcast episodes** — mix them if you like. -### Library Filtering +The **⚡ Smart** badge means the same thing everywhere it appears: *membership +is matched by rules right now — always current, nothing to refresh*. -- **No filter** (`/collections/favorites`): Shows all books across all libraries -- **With filter** (`/collections/favorites?library_id=xxx`): Shows only books from the specified library +## Creating a collection -## Creating Collections +1. Open the **Collections** page (sidebar navigation) +2. Click **New Collection** +3. Choose the **Type**: + - **Static** — pick items by hand + - **⚡ Smart** — match by rules, always live +4. If you picked **⚡ Smart**, choose the **Rules scope**: **📚 Books** or + **🎧 Podcast episodes** +5. Fill in the rest: **Name**, **Description**, an **Icon** you can search or + pick, and a **Color** +6. Click **Create Collection** -1. Go to **Collections** (sidebar navigation) -2. Click **New Collection** (top-right) — or **Create Your First Collection** if the list is empty -3. Fill in the details: - - **Name** - Collection name - - **Description** - Optional description - - **Icon** - Pick from the icon grid - - **Color** - Pick a color swatch -4. Click **Create Collection** +Starting from a completely empty account? The button **Create Your First +Collection** does the same thing. -## Managing Collections +## Adding items by hand (Static collections) -Each collection in the list has icon buttons on its card: +1. Open the collection from the **Collections** page +2. Click **Add Items** +3. Pick the tab for what you want: + - **📚 Books** — searchable by the **Search books...** box, and the + **Author** and **Genre** boxes + - **🎧 Episodes** — the episodes of the feeds you subscribe to +4. Click one or more items — a checkmark marks what you picked; the bottom + of the window counts them for you +5. Click **Add Selected** -- **Edit** - Opens the edit form to change name, description, icon, or color. Click **Update Collection** to save. -- **Delete** - Removes the collection after a confirmation prompt. +To take items out, check them on the collection page and click +**Remove Selected** (it asks first). -Deleted a system collection by mistake? The **Restore System** button on the Collections page brings back system collections. +While checking what is in the collection, the **Search within collection...** +box narrows the view — it never removes anything. -### Dashboard Sections +## Rules (how ⚡ Smart collections work) -Collections appear as sections on your dashboard. Show, hide, and reorder them from the dashboard's **Customize Dashboard** settings (see [Dashboard](dashboard.md)). +A smart collection keeps its own list of rules, the same rules that power the +filter drawer. On the collection's page, click **Edit Rules** to open the +rules editor: build your groups and rules in the **Filter tree**, then click +**Apply to Collection**. From that point the collection matches those rules +by itself — add a book that matches and it appears without you doing +anything. + +Rules live in one guide, so this page does not repeat them. The full how-to +walks through groups, ALL/ANY, and value picking in +[Filters — the complete guide](filters/index.md), ready-made examples are in +the [cookbook](filters/cookbook.md), and +[every filter field](filters/fields.md) lists what you can ask about. + +*Finding it again later:* open any collection's page and look for the +**Edit Rules** button; the **⚡ Smart** badge in the page title marks a +collection that is already matching. + +## Playing an episode collection + +When a collection holds a downloaded episode, it grows a **Play as Sequence** +button: the episodes play one after another. Next to it, the order picker +decides the sequence — **Feed order**, **Feed order (reversed)**, +**Oldest first (pub date)**, or **Newest first (pub date)**. Your choice is +remembered on the collection. + +## Changing a collection + +The pencil button on a collection card, or the edit control on the +collection page, opens the edit form: + +- Change the **Name**, **Description**, **Icon**, **Color** +- **Hide finished books (reading-queue mode)** — finished books drop off + this shelf, which keeps a to-read list short +- **Show Up Next strip** — show the collection's Up Next strip where it is + used + +Click **Update Collection** to save. Deleting a collection asks first, and +deleting only removes the shelf — never the books or episodes inside it. + +## System collections + +The five built-in shelves — **Continue Reading**, **Recently Added**, +**Recently Read**, **Not Started**, **Continue Series** — work like any +collection on the outside, but Bookhoard decides their membership by what +happens while you read. They appear on your dashboard automatically. + +Deleted one and want it back? Click **Restore System** on the **Collections** +page, pick the shelf from the list, and click **Restore**. + +## Your dashboard shelves + +Collections appear as sections on your dashboard, and you choose which ones +show and in what order from the dashboard's own settings. That page's +details live in [Dashboard](dashboard.md). + +*Finding your way back:* **Collections** is the sidebar page whose top has +the only **New Collection** button — from a dashboard shelf's **View All**, +the collection detail page is the place with **Add Items**.