User Guide

Adding Books

There are multiple ways to add books to your library:

Manual Entry

Click the "+ Add Book" button to add a book manually with full details:

• Basic Info: Title, authors (with roles), rating, status
• Details: ISBN, ASIN, publisher, page count, language
• Classification: Genre, format, series, tags
• Dates: Release date, start/completion dates
• Personal: Summary, notes, DNF tracking
• Cover: Upload image or provide URL

ISBN Lookup

Save time by looking up books by ISBN:

1. Click "+ Add Book"
2. Click the "ISBN Lookup" button
3. Enter ISBN (10 or 13 digit)
4. BookShelf searches multiple providers (Google Books, Open Library, Goodreads, Hardcover, Amazon, ComicVine)
5. Review fetched metadata and select fields to include
6. Save to create the book

Search & Add

Search for books online without an ISBN:

1. Click "Metadata Search"
2. Enter book title and/or author
3. Browse results from multiple providers
4. Click a result to preview metadata
5. Add to your library

BookDrop Auto-Import

Drop ebook files into a folder and have them automatically imported:

1. Enable BookDrop in Admin → BookDrop settings
2. Set watch folder (default: /app/bookdrop in Docker)
3. Drop files into the folder (EPUB, PDF, CBZ supported)
4. BookShelf automatically detects, extracts metadata, creates entry, and moves file

Organizing Books

Statuses

Books can have different statuses:

You can create custom statuses in Settings → Statuses.

Genres

Organize books by genre with custom colors and icons. Create custom genres beyond the built-in ones (Fiction, Non-Fiction, Fantasy, etc.).

Tags

Create flexible categorization with tags:

• System Tags: Favorite, Wishlist (always available)
• Custom Tags: Create your own with colors and icons
• Bulk Tagging: Apply tags to multiple books at once

Example tags: "Beach Reads", "Book Club", "Library", "Gift", "2026 Challenge"

Series Tracking

Track reading order for series:

• Add books to series with book numbers (supports decimals like 2.5 for novellas)
• Book number ranges for omnibus editions
• Primary series designation for books in multiple series
• Series status tracking and gap detection

Multi-Author Support

Books can have multiple authors with different roles:

• Author, Co-Author, Editor, Translator, Illustrator, Narrator
• Designate primary author for sorting and display

Smart Collections (Magic Shelves)

Create dynamic collections that automatically update based on rules you set.

Creating a Smart Collection

1. Go to Shelves → Create Smart Collection
2. Name your shelf (e.g., "Recent Favorites")
3. Add rules (Field, Operator, Value)
4. Combine rules with AND/OR logic
5. Set display options (sort order, max items, show on dashboard)

Example Smart Collections

Ebook Reader

Read your digital books directly in BookShelf.

Supported Formats

EPUB Reader Features

• Themes: Light, Dark, Sepia, or Custom colors
• Font: Size, family (including OpenDyslexic), line spacing
• Navigation: Click edges, swipe, arrow keys, TOC
• Bookmarks: Save and jump to marked positions
• Progress: Auto-saved position and reading time tracking

Keyboard Shortcuts

Uploading Ebooks

1. Open book details
2. Click "Upload Ebook" button
3. Select file (EPUB, PDF, CBZ, CBR)
4. Wait for upload
5. "Read" button appears when done

Reading Goals

Set and track reading goals to stay motivated. BookShelf supports 6 types of reading challenges:

Goal Insights

• On Track Green indicator when ahead of pace
• Behind Yellow when slightly behind with catch-up suggestions
• At Risk Red when significantly behind with suggested pace

Statistics

View detailed statistics and visualizations of your reading habits.

Reading Heatmap

A GitHub-style contribution graph showing your reading activity over the last 365 days. Each square represents a day with color intensity showing books finished.

Dashboard Stats

• Library Size: Total books, by status, by format
• Reading Activity: Books this year/month, current streak
• Quick Stats: Average rating, most read genre/author

Analytics

• Timeline: Visual timeline of books read, grouped by month/year
• Genre Analytics: Pie charts, distribution over time, ratings by genre
• Author Analytics: Most read authors, favorites, discovery timeline
• Format Analytics: Physical vs Digital vs Audio breakdown

DNF Tracking

Track books you didn't finish with reason, page stopped, and percentage read. View DNF analysis including rate, common reasons, and genres with highest DNF.

Import & Export

Importing Books

CSV Import (Goodreads)

1. Export from Goodreads: My Books → Import/Export → Export Library
2. In BookShelf: Import/Export → CSV Import
3. Upload CSV, preview, map columns
4. Configure options (skip duplicates, fetch metadata, download covers)
5. Import!

Audible Import

1. Go to Audible.com → Library
2. Save page as HTML
3. Upload to BookShelf's Audible Import
4. Review and import (narrator info preserved)

BookDrop (Automatic)

Enable BookDrop in Admin settings, then simply drop ebook files (EPUB, PDF, CBZ) into the watch folder. BookShelf automatically imports them.

Exporting Data

• CSV Export: For spreadsheets or other apps
• JSON Backup: Complete backup of all data
• Database File: SQLite file for direct access

Scheduled Backups

Automate backups with cron jobs. See Getting Started for backup scripts.

Admin Settings

Admin users can configure BookShelf from Admin → Settings:

General Settings

• Library Name: Display name in header
• Branding: Custom logos and favicon
• Items Per Page: 12-100 books per page
• Date Format: US, EU, or ISO
• Default View: Grid or list

Metadata Providers

Configure book metadata sources with priority ordering:

• Google Books
• Open Library
• Goodreads
• Hardcover (requires API key)
• Amazon
• ComicVine (requires API key)

OPDS Catalog

Serve your library to e-reader apps like Calibre, KOReader, Moon+ Reader:

• Enable/disable OPDS catalog
• Configure public access
• Auto-generated catalog URL

Email & Notifications

Configure SMTP for password resets and notifications.

Advanced Features

• BookDrop: Auto-import ebooks from folder
• AI Features: OpenAI integration for recommendations
• Widgets: Embeddable stats for websites
• Database: Backup, maintenance, diagnostics