diff --git a/docs/admin/archived-items.md b/docs/admin/archived-items.md index dbc88b73..45e319dd 100644 --- a/docs/admin/archived-items.md +++ b/docs/admin/archived-items.md @@ -16,8 +16,8 @@ then — or after — the reader's history is preserved, so a file that comes back (or a move the scanner detects automatically) restores the item with its reading data intact. -You reach this page from the Libraries page, which shows an **Archived -items** banner with the count whenever anything is archived. +You reach this page from the [Libraries](libraries.md) page, which shows +an **Archived items** banner with the count whenever anything is archived. ## What the page shows diff --git a/docs/admin/libraries.md b/docs/admin/libraries.md index febe3c1f..f2669d85 100644 --- a/docs/admin/libraries.md +++ b/docs/admin/libraries.md @@ -1,32 +1,108 @@ + + # Libraries -## Adding Library Folders +The Libraries page is where a Bookhoard instance is defined: what +libraries exist, which folders on the server they read from, who can see +them, and how they get scanned. Everything here is admin-only — regular +users just see the result. -When creating or managing a library, you can add folders containing your media files (ebooks, comics, manga). +## Creating a library -### Using the Folder Browser +**Create Library** opens a modal with three fields: -The admin library page includes a folder browser to help you select folders on the server: +- **Library Name** (required) — what users see in their sidebar +- **Description** (optional) +- **Library Type** (required) — book, comic, audiobook, podcast; the type + drives how the scanner parses files and how the reader presents them -1. Open the **Administration** panel in the sidebar (admins only) and go to **Libraries** -2. Click a library in the list to expand its panel -3. Find the **Folders** section -4. Click **Browse** next to the folder path input — this opens the **Browse Folders** dialog -5. Navigate through the server's filesystem -6. Select a folder; it fills the path input, then click **Add** +A library with no folders can't scan — add at least one folder (below) +before expecting anything to appear in it. -### Security +## The library card -- The folder browser only shows directories (not files) -- Path traversal is protected (cannot access parent directories with `..`) -- Only admin users can browse the filesystem +Each library renders as a card: name, description, a type chip, a folder +count, and two controls: -### Manual Entry +- **Force Rescan** — starts a force scan of this one library: every file + re-read and re-extracted, hashes recomputed. This is the heavy, + thorough pass ([Scanning](scanning.md) explains force vs. shallow and + when each is worth it). If a scan is already running for the library, + the click tells you instead of stacking a second one. +- **Manage** — opens the library's panel, where everything else lives. -Alternatively, you can manually type the full server path if you know it: +## The library panel -``` -/home/user/books -/media/external/ebooks -/var/lib/manga -``` +### Folders + +Folders are the server-side directories the scanner walks. Each one shows +its path with two icon actions: **Scan this folder** (a shallow scan +scoped to just that folder's subtree — the quick "I just dropped files +here" button) and remove-from-library (confirm-guarded). + +Adding one: type a path, or click **Browse** to walk the server's +filesystem in a modal (up with `..`, into a folder by clicking it, +**Select This Folder** to fill the input), then **Add**. + +Two things worth knowing: + +- **Removing a folder only unregisters it.** The mapping is deleted; + files on disk and existing catalog items are untouched. If no remaining + folder covers those files, later library-wide scans will treat them as + missing — the [Archived Items](archived-items.md) lifecycle takes over, + history kept. +- **Podcast download folders are feed-managed.** The scanner refuses to + scan them by hand; the podcast feed system owns their contents. + +### User Access + +One checkbox per user. Checked (the default) means the library is visible +to them; unchecking hides it from their browsing, apps, and OPDS — +enforced in the database, so every listing obeys. Hiding a library never +destroys anything: the user simply can't see it. + +### Processing issues + +When the library has items the scanner couldn't process, a link here +shows the count and leads to its +[Processing Issues](library-processing-issues.md) page. + +### Edit Details and Delete Library + +**Edit Details** changes the name and description. The library type is +fixed at creation — it can't be edited later. + +**Delete Library** is the destructive one, and its confirm dialog says +precisely what it does: + +- **Permanently removed, no archive or undo:** the library, its folder + mappings, and all book records — with their reading progress, + highlights, notes, bookmarks, and ratings. +- **Not touched:** media files on disk. Delete the library, keep the + files; re-create the library later and scan them fresh (with empty + reading history). + +## The archived banner + +When any library has archived (missing-file) items, this page shows a +banner with the total count and two shortcuts: **View Archived** (the +[Archived Items](archived-items.md) page) and **Purge Archived Now** (the +same permanent wipe the archived page's Purge All Archived performs). + +## Every scan entry point, at a glance + +| Where | Control | Kind | +| --- | --- | --- | +| This page, library card | **Force Rescan** | Force, this library | +| This page, folder row | **Scan this folder** | Shallow, that folder | +| Admin dashboard | **Force Rescan All Libraries** | Force, everything | +| Settings → Scanning | **Auto-Scan** | Shallow, automatic | +| A book's page | **Rescan** | Force, that one item | + +Full semantics for each: [Scanning](scanning.md). diff --git a/docs/admin/library-processing-issues.md b/docs/admin/library-processing-issues.md index e1e0a5ad..226209f3 100644 --- a/docs/admin/library-processing-issues.md +++ b/docs/admin/library-processing-issues.md @@ -11,7 +11,8 @@ Processing Issues is each library's ledger of items the scanner could not fully process — a corrupt file, an unsupported format, metadata that wouldn't parse. It is per-library: you reach it from that library's panel -on the Libraries page (the link only appears when the library has issues). +on the [Libraries](libraries.md) page (the link only appears when the +library has issues). ## What's on the page diff --git a/docs/developer/ui-controls.md b/docs/developer/ui-controls.md index c41cb48f..2294c79c 100644 --- a/docs/developer/ui-controls.md +++ b/docs/developer/ui-controls.md @@ -252,6 +252,38 @@ label: Delete where: Admin → Archived Items rows, and other admin destructive rows does: Permanently removes the item and its reading history — no archive, no undo. Every Delete is confirm-guarded and states the scope. +label: Create Library +where: Admin → Libraries → page header +does: Opens the create-library modal (name, optional description, library type). Type is fixed at creation — it cannot be edited later. + +label: Manage +where: Admin → Libraries → a library's card row +does: Opens that library's panel: folders, user access, processing issues, edit/delete. + +label: Edit Details +where: Admin → Libraries → a library's panel +does: Edits the library's name and description. Library type is not editable. + +label: Delete Library +where: Admin → Libraries → a library's panel +does: Permanently deletes the library, its folder mappings, and all book records with reading progress, highlights, notes, bookmarks, and ratings. Files on disk are not touched. + +label: View Archived +where: Admin → Libraries → the archived banner +does: Opens the Archived Items page. + +label: Purge Archived Now +where: Admin → Libraries → the archived banner +does: Same permanent wipe as Purge All Archived on the Archived Items page, offered inline. + +label: Browse +where: Admin → Libraries → a library's panel → folder form +does: Opens the server-side folder browser: walk the filesystem, Select This Folder fills the path input. + +label: User Access +where: Admin → Libraries → a library's panel → section heading +does: Per-user visibility checkboxes — checked (default) shows the library to that user; unchecked hides it everywhere for them, enforced in the database. + label: Resume rewind where: audio player → player settings; profile settings does: Rewinds playback a configured few seconds when you resume.