From 1098075ccb2a760b6f944a8607c8018eae022dcc Mon Sep 17 00:00:00 2001 From: ACX <8075870+acx10@users.noreply.github.com> Date: Fri, 13 Feb 2026 00:07:51 -0700 Subject: [PATCH] chore: redesign README with cleaner layout and rewritten copy (#2728) --- README.md | 452 +++++++++++++++++------------------------------------- 1 file changed, 138 insertions(+), 314 deletions(-) diff --git a/README.md b/README.md index 97a4a450c..4fe89c991 100644 --- a/README.md +++ b/README.md @@ -1,249 +1,105 @@ -
- -# ๐Ÿ“š BookLore - -### *Your Personal Library, Beautifully Organized* - -**๐ŸŒ Official Website: [https://booklore.org](https://booklore.org/)** -

- BookLore Demo + BookLore

-[![Release](https://img.shields.io/github/v/release/adityachandelgit/BookLore?color=4c6ef5&style=for-the-badge&logo=github)](https://github.com/booklore-app/booklore/releases) -[![License](https://img.shields.io/github/license/adityachandelgit/BookLore?color=fab005&style=for-the-badge)](LICENSE) -[![Stars](https://img.shields.io/github/stars/adityachandelgit/BookLore?style=for-the-badge&color=ffd43b)](https://github.com/booklore-app/booklore/stargazers) -[![Docker Pulls](https://img.shields.io/docker/pulls/booklore/booklore?color=2496ED&style=for-the-badge&logo=docker&logoColor=white)](https://hub.docker.com/r/booklore/booklore) +

Your books deserve a home. This is it.

-[![Discord](https://img.shields.io/badge/Join_Discord-5865F2?style=for-the-badge&logo=discord&logoColor=white)](https://discord.gg/Ee5hd458Uz) -[![Open Collective](https://img.shields.io/opencollective/all/booklore?style=for-the-badge&color=7FADF2&logo=opencollective)](https://opencollective.com/booklore) -[![Translate](https://img.shields.io/weblate/progress/booklore?style=for-the-badge&logo=weblate&logoColor=white&color=2ECCAA)](https://hosted.weblate.org/engage/booklore/) +

+BookLore is a self-hosted app that brings your entire book collection under one roof.
+Organize, read, annotate, sync across devices, and share, all without relying on third-party services. +

+ +

+ Release + License + Docker Pulls + Stars + Discord + Open Collective + Translate +

+ +

+ ๐ŸŒ Website ยท + ๐Ÿ“– Docs ยท + ๐ŸŽฎ Demo ยท + ๐Ÿš€ Quick Start ยท + ๐Ÿ’ฌ Discord +

+ +

+ BookLore Demo +

--- -**BookLore** is a powerful, self-hosted web application designed to organize and manage your personal book collection with elegance and ease. Build your dream library with an intuitive interface, robust metadata management, and seamless multi-user support. +## โœจ Features -[๐Ÿš€ Get Started](#-getting-started-with-booklore) โ€ข [๐Ÿ“– Documentation](https://booklore.org/docs/getting-started) โ€ข [๐ŸŽฎ Try Demo](#-live-demo-explore-booklore-in-action) โ€ข [๐Ÿ’ฌ Community](https://discord.gg/Ee5hd458Uz) - -
+| | Feature | Description | +|:---:|:---|:---| +| ๐Ÿ“š | **Smart Shelves** | Custom and dynamic shelves that organize themselves with rule-based Magic Shelves, filters, and full-text search | +| ๐Ÿ” | **Automatic Metadata** | Covers, descriptions, reviews, and ratings pulled from Google Books, Open Library, and Amazon, all editable | +| ๐Ÿ“– | **Built-in Reader** | Open PDFs, EPUBs, and comics right in the browser with annotations, highlights, and reading progress | +| ๐Ÿ”„ | **Device Sync** | Connect your Kobo, use any OPDS-compatible app, or sync progress with KOReader. Your library follows you everywhere | +| ๐Ÿ‘ฅ | **Multi-User Ready** | Individual shelves, progress, and preferences per user with local or OIDC authentication | +| ๐Ÿ“ฅ | **BookDrop** | Drop files into a watched folder and BookLore detects, enriches, and queues them for import automatically | +| ๐Ÿ“ง | **One-Click Sharing** | Send any book to a Kindle, an email address, or a friend instantly | --- -
+## ๐Ÿš€ Quick Start -## โœจ **Features That Make BookLore Shine** +> [!TIP] +> Looking for OIDC setup, advanced config, or upgrade guides? See the [full documentation](https://booklore.org/docs/getting-started). -
- - - - - - - - - - -
- -### ๐Ÿ“– **Library Management** - -- **Smart Organization**: Custom shelves with powerful filters -- **Magic Shelves**: Dynamic, auto-updating collections -- **Auto Metadata**: Rich details from multiple sources -- **Advanced Search**: Find any book instantly - - - -### ๐ŸŒ **Connectivity** - -- **Kobo Integration**: Seamless device sync -- **OPDS Support**: Connect any reading app -- **KOReader Sync**: Cross-platform progress tracking -- **Email Sharing**: One-click book sending - -
- -### ๐Ÿ‘ฅ **User Experience** - -- **Multi-User Support**: Granular permissions -- **Flexible Auth**: Local or OIDC providers -- **Mobile Ready**: Responsive on all devices -- **Built-in Reader**: PDFs, EPUBs, comics - - - -### ๐Ÿš€ **Smart Features** - -- **BookDrop Import**: Auto-detect bulk files -- **Private Notes**: Personal reading annotations -- **Community Reviews**: Enriched book data -- **Progress Tracking**: Reading statistics - -
- ---- - -
- -## ๐Ÿ’– **Support the Project** - -
- -
- -Your support helps BookLore grow and improve! ๐ŸŒฑ - - - - - - - -
- -### โญ **Star Us** - -Give us a star to show your support and help others discover BookLore! - -[![Star this repo](https://img.shields.io/github/stars/adityachandelgit/BookLore?style=social)](https://github.com/booklore-app/booklore) - - - -### ๐Ÿ’ฐ **Sponsor** - -Support development, hosting, and testing costs - -[![Open Collective](https://img.shields.io/badge/Open_Collective-7FADF2?style=for-the-badge&logo=opencollective&logoColor=white)](https://opencollective.com/booklore) - - - -### ๐Ÿ“ข **Spread the Word** - -Share BookLore with fellow book lovers and developers! - -
- -> ๐ŸŽฏ **Current Goal:** Raising funds for a **Kobo device** to implement native Kobo sync support -> [๐Ÿ’ก Support the Kobo Sync Bounty โ†’](https://opencollective.com/booklore/projects/kobo-device-for-testing) - -
- ---- - -
- -## ๐ŸŽฎ **Live Demo: Explore BookLore in Action** - -
- -
- -Experience BookLore's features in a live environment before deploying your own instance! - -| ๐ŸŒ Demo URL | ๐Ÿ‘ค Username | ๐Ÿ”‘ Password | -|----------------------------------------------------|-------------|--------------------| -| **[demo.booklore.org](https://demo.booklore.org)** | `booklore` | `9HC20PGGfitvWaZ1` | - -> โš ๏ธ **Note:** Demo account has standard user permissions only. -> Admin features (user management, library setup) require a self-hosted instance. - -
- ---- - -
- -## ๐Ÿš€ **Getting Started with BookLore** - -### Choose Your Path - - - - - - -
- -### ๐Ÿ“˜ **Documentation** - -Guides for installation, setup, features, and more - -[![Read the Docs](https://img.shields.io/badge/๐Ÿ“–_Read_the_Docs-4c6ef5?style=for-the-badge)](https://booklore.org/docs/getting-started) - -*Contribute to the docs at: [booklore-docs](https://github.com/booklore-app/booklore-docs)* - - - -### ๐Ÿณ **Quick Deploy** - -Get up and running in minutes with Docker - -[![Deploy with Docker](https://img.shields.io/badge/๐Ÿณ_Deploy_Now-2496ED?style=for-the-badge)](#-deploy-with-docker) - -*Easiest way to self-host BookLore* - -
- -
- ---- - -
- -## ๐Ÿณ **Deploy with Docker** - -
- -### **Prerequisites** - -Ensure you have [Docker](https://docs.docker.com/get-docker/) and [Docker Compose](https://docs.docker.com/compose/install/) installed. +All you need is [Docker](https://docs.docker.com/get-docker/) and [Docker Compose](https://docs.docker.com/compose/install/).
-๐Ÿ“ฆ Image Repositories +๐Ÿ“ฆ Image Repositories -- ๐Ÿณ **Docker Hub:** `booklore/booklore` -- ๐Ÿ“ฆ **GitHub Container Registry:** `ghcr.io/booklore-app/booklore` +| Registry | Image | +|----------|-------| +| Docker Hub | `booklore/booklore` | +| GitHub Container Registry | `ghcr.io/booklore-app/booklore` | -> ๐Ÿ’ก Legacy images at `ghcr.io/adityachandelgit/booklore-app` remain available but won't receive updates. +> Legacy images at `ghcr.io/adityachandelgit/booklore-app` remain available but won't receive updates.
-### **Step 1๏ธโƒฃ: Create Environment Configuration** +### Step 1: Environment Configuration -Create a `.env` file in your project directory: +Create a `.env` file: ```ini -# ๐ŸŽฏ BookLore Application Settings +# Application APP_USER_ID=1000 APP_GROUP_ID=1000 TZ=Etc/UTC -# ๐Ÿ—„๏ธ Database Connection (BookLore) +# Database DATABASE_URL=jdbc:mariadb://mariadb:3306/booklore DB_USER=booklore DB_PASSWORD=ChangeMe_BookLoreApp_2025! -# ๐Ÿ’พ Storage type: LOCAL (default) or NETWORK. Set to NETWORK if using NFS/SMB - this disables file reorganization features to prevent data corruption. +# Storage: LOCAL (default) or NETWORK (for NFS/SMB, disables file reorganization) DISK_TYPE=LOCAL -# ๐Ÿ”ง MariaDB Container Settings +# MariaDB DB_USER_ID=1000 DB_GROUP_ID=1000 MYSQL_ROOT_PASSWORD=ChangeMe_MariaDBRoot_2025! MYSQL_DATABASE=booklore ``` -### **Step 2๏ธโƒฃ: Create Docker Compose File** +### Step 2: Docker Compose -Create a `docker-compose.yml` file: +Create a `docker-compose.yml`: ```yaml services: booklore: image: booklore/booklore:latest - # Alternative: Use GitHub Container Registry - # image: ghcr.io/booklore-app/booklore:latest + # Alternative: ghcr.io/booklore-app/booklore:latest container_name: booklore environment: - USER_ID=${APP_USER_ID} @@ -290,33 +146,34 @@ services: retries: 10 ``` -### **Step 3๏ธโƒฃ: Launch BookLore** +### Step 3: Launch ```bash docker compose up -d ``` -### **Step 4๏ธโƒฃ: Access Your Library** - -Open your browser and navigate to: - -**๐ŸŒ http://localhost:6060** - -๐ŸŽ‰ **Welcome to your personal library!** +Open **http://localhost:6060**, create your admin account, and start building your library. --- -
+## ๐ŸŽฎ Live Demo -## ๐Ÿ“ฅ **BookDrop: Automatic Import** +See BookLore in action before deploying your own instance. -### *Drop Files, Import Automatically* +| | | +|:---|:---| +| ๐ŸŒ **URL** | **[demo.booklore.org](https://demo.booklore.org)** | +| ๐Ÿ‘ค **Username** | `booklore` | +| ๐Ÿ”‘ **Password** | `9HC20PGGfitvWaZ1` | -
+> [!NOTE] +> This is a standard user account. Admin features like library creation, user management, and system settings are only available on your own instance. -BookLore's **BookDrop** feature automatically detects and processes book files dropped into a designated folder. +--- -### **How It Works** +## ๐Ÿ“ฅ BookDrop: Zero-Effort Import + +Drop book files into a folder. BookLore picks them up, pulls metadata, and queues everything for your review. ```mermaid graph LR @@ -325,96 +182,60 @@ graph LR C --> D[โœ… Review & Import] ``` -1. **File Watcher**: Monitors the BookDrop folder continuously -2. **Auto-Detection**: Processes new files and extracts metadata -3. **Metadata Enrichment**: Fetches details from Google Books, Open Library -4. **Review & Finalize**: Review, edit, and import to your library +| Step | What Happens | +|:---|:---| +| 1. **Watch** | BookLore monitors the BookDrop folder around the clock | +| 2. **Detect** | New files are picked up and parsed automatically | +| 3. **Enrich** | Metadata is fetched from Google Books and Open Library | +| 4. **Import** | You review, tweak if needed, and add to your library | -### **Docker Configuration** - -Add the BookDrop volume to your `docker-compose.yml`: +Mount the volume in `docker-compose.yml`: ```yaml -services: - booklore: - volumes: - - ./data:/app/data - - ./books:/books - - ./bookdrop:/bookdrop # ๐Ÿ‘ˆ BookDrop magic happens here +volumes: + - ./bookdrop:/bookdrop ``` --- -
- -## ๐Ÿค **Community & Support** - - - - - - - -
- -### ๐Ÿž **Bug Reports** - -Found an issue? - -[![Open Issue](https://img.shields.io/badge/Report-ff6b6b?style=for-the-badge)](https://github.com/booklore-app/booklore/issues/new?template=bug_report.yml) - - - -### ๐Ÿ’ก **Feature Req** - -Have an idea? - -[![Request Feature](https://img.shields.io/badge/Suggest-4ecdc4?style=for-the-badge)](https://github.com/booklore-app/booklore/issues/new?template=feature_request.yml) - - - -### ๐Ÿค **Contribute** - -Join development! - -[![Contributing](https://img.shields.io/badge/Contribute-95e1d3?style=for-the-badge)](CONTRIBUTING.md) - - - -### ๐Ÿ’ฌ **Chat** - -Join community! - -[![Discord](https://img.shields.io/badge/Discord-5865F2?style=for-the-badge&logo=discord&logoColor=white)](https://discord.gg/Ee5hd458Uz) - -
- -
+## ๐Ÿค Community & Support +| | | +|:---|:---| +| ๐Ÿž **Something not working?** | [Report a Bug](https://github.com/booklore-app/booklore/issues/new?template=bug_report.yml) | +| ๐Ÿ’ก **Got an idea?** | [Request a Feature](https://github.com/booklore-app/booklore/issues/new?template=feature_request.yml) | +| ๐Ÿ› ๏ธ **Want to help build?** | [Contributing Guide](CONTRIBUTING.md) | +| ๐Ÿ’ฌ **Come hang out** | [Discord Server](https://discord.gg/Ee5hd458Uz) | --- -
+## ๐Ÿ’œ Support BookLore -## ๐ŸŒ **Translations** +BookLore is free, open source, and built with care. Here's how you can give back: -Help translate BookLore into your language! +| Action | How | +|:---|:---| +| โญ **Star this repo** | It's the simplest way to help others find BookLore | +| ๐Ÿ’ฐ **Sponsor development** | [Open Collective](https://opencollective.com/booklore) funds hosting, testing, and new features | +| ๐Ÿ“ข **Tell someone** | Share BookLore with a friend, a subreddit, or your local book club | + +> [!IMPORTANT] +> We're raising funds for a Kobo device to build and test native Kobo sync support. +> [Contribute to the Kobo Bounty โ†’](https://opencollective.com/booklore/projects/kobo-device-for-testing) + +--- + +## ๐ŸŒ Translations + +BookLore is used by readers around the world. Help make it accessible in your language on [Weblate](https://hosted.weblate.org/engage/booklore/). Translation status -Read more about translations [here](https://hosted.weblate.org/engage/booklore/). - -
- --- -
- -## ๐Ÿ“Š **Project Analytics** - -### Repository Activity +## ๐Ÿ“Š Project Analytics ![Repository Activity](https://repobeats.axiom.co/api/embed/44a04220bfc5136e7064181feb07d5bf0e59e27e.svg) @@ -428,45 +249,53 @@ Read more about translations [here](https://hosted.weblate.org/engage/booklore/) -
- --- -
- -## ๐Ÿ‘จโ€๐Ÿ’ป **Contributors** - -### Thanks to all our amazing contributors! ๐Ÿ™ +## ๐Ÿ‘ฅ Contributors [![Contributors](https://contrib.rocks/image?repo=adityachandelgit/BookLore)](https://github.com/booklore-app/booklore/graphs/contributors) -**Want to see your face here?** [Start contributing today!](CONTRIBUTING.md) - -
+Every contribution matters. [See how you can help โ†’](CONTRIBUTING.md) ---
-## ๐ŸŒŸ **Sponsors** +## ๐ŸŒŸ Sponsors & Partners -### Thank you to our amazing sponsors! + + + + + + +
- Run on PikaPods - -     - - ElfHosted + Run on PikaPods -### Powered by +**PikaPods** + + + + + ElfHosted + + +**ElfHosted** + + - JetBrains logo + JetBrains -*Become a sponsor and get your logo here! [Support us on Open Collective](https://opencollective.com/booklore)* +**JetBrains** + +
+ +*Want your logo here? [Become a sponsor โ†’](https://opencollective.com/booklore)*
@@ -474,17 +303,12 @@ Read more about translations [here](https://hosted.weblate.org/engage/booklore/)
-## โš–๏ธ **License** +## โš–๏ธ License -**GNU Affero General Public License v3.0 (AGPL-3.0)** +**GNU Affero General Public License v3.0** -Copyright ยฉ 2024-2026 BookLore +Copyright 2024โ€“2026 BookLore -[![License: AGPL v3](https://img.shields.io/badge/License-AGPLv3-blue.svg?style=for-the-badge)](https://www.gnu.org/licenses/agpl-3.0.html) ---- - -Made with โค๏ธ by the BookLore community - -**[โฌ† Back to Top](#-booklore)** +[![License: AGPL v3](https://img.shields.io/badge/License-AGPL_v3-blue.svg?style=for-the-badge)](https://www.gnu.org/licenses/agpl-3.0.html)