{"id":29564972,"url":"https://github.com/paviro/koshelf","last_synced_at":"2026-04-19T16:05:26.209Z","repository":{"id":300104505,"uuid":"1005056018","full_name":"paviro/KoShelf","owner":"paviro","description":"All your KOReader notes \u0026 highlights combined into a beautiful reading dashboard with statistics.","archived":false,"fork":false,"pushed_at":"2026-03-27T23:45:56.000Z","size":2946,"stargazers_count":150,"open_issues_count":4,"forks_count":9,"subscribers_count":2,"default_branch":"main","last_synced_at":"2026-03-27T23:58:04.368Z","etag":null,"topics":["dashboard","ebook","ebooks","epub","koreader","reaading","self-hosted","statistic","statistics"],"latest_commit_sha":null,"homepage":"","language":"Rust","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"eupl-1.2","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/paviro.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"License","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-06-19T15:39:39.000Z","updated_at":"2026-03-27T08:26:34.000Z","dependencies_parsed_at":"2025-12-31T21:06:08.515Z","dependency_job_id":null,"html_url":"https://github.com/paviro/KoShelf","commit_stats":null,"previous_names":["paviro/koshelf"],"tags_count":65,"template":false,"template_full_name":null,"purl":"pkg:github/paviro/KoShelf","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/paviro%2FKoShelf","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/paviro%2FKoShelf/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/paviro%2FKoShelf/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/paviro%2FKoShelf/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/paviro","download_url":"https://codeload.github.com/paviro/KoShelf/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/paviro%2FKoShelf/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31290736,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-01T13:12:26.723Z","status":"ssl_error","status_checked_at":"2026-04-01T13:12:25.102Z","response_time":53,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["dashboard","ebook","ebooks","epub","koreader","reaading","self-hosted","statistic","statistics"],"created_at":"2025-07-18T20:37:55.407Z","updated_at":"2026-04-01T17:59:11.753Z","avatar_url":"https://github.com/paviro.png","language":"Rust","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003cdiv align=\"center\"\u003e\n\n# KoShelf\n\n\u003cp\u003e\n  \u003ca href=\"https://github.com/paviro/koshelf/stargazers\"\u003e\n    \u003cimg src=\"https://img.shields.io/github/stars/paviro/koshelf?style=social\" alt=\"Stars\" /\u003e\n  \u003c/a\u003e\n  \u003ca href=\"https://github.com/paviro/koshelf/releases/latest\"\u003e\n    \u003cimg src=\"https://img.shields.io/github/v/release/paviro/koshelf?label=release\" alt=\"Latest Release\" /\u003e\n  \u003c/a\u003e\n  \u003ca href=\"https://github.com/paviro/koshelf/blob/main/LICENSE\"\u003e\n    \u003cimg src=\"https://img.shields.io/github/license/paviro/koshelf\" alt=\"License\" /\u003e\n  \u003c/a\u003e\n\u003c/p\u003e\n\n![Statistics dashboard](https://github.com/user-attachments/assets/94a094d2-298b-412c-80b3-b3b2e2cfc6de)\n\n###### A reading companion powered by KOReader metadata — browse your library, highlights, annotations, and reading statistics from a web dashboard.\n\n\u003c/div\u003e\n\n## Features\n\n- 📚 **Library Overview (Books + Comics)**: Displays your currently reading, completed, and unread items (ebooks + comics)\n- 🎨 **Modern UI**: Clean design powered by Tailwind CSS with readable typography and responsive layout\n- 📖 **In-App Reader (EPUB/FB2/MOBI/CBZ)**: Open supported files directly in KoShelf with keyboard navigation, progress scrubber controls, and inline highlight notes\n- 📝 **Annotations, Highlights \u0026 Ratings**: All your KoReader highlights, notes, star ratings, and review notes (summary note) are shown together on each book's details page\n- ✏️ **Metadata Writeback**: Edit annotations, review notes, ratings, and reading status directly in KoShelf and sync changes back to your KOReader sidecar files (serve mode, opt-in)\n- 📊 **Reading Statistics**: Track your reading habits with detailed statistics including reading time, pages read, customizable activity heatmaps, and weekly breakdowns\n- 📅 **Reading Calendar**: Monthly calendar view showing your reading activity with items read on each day and monthly statistics\n- 🎉 **Yearly Recap**: Celebrate your reading year with a timeline of completions, monthly summaries (finished items, hours read), and rich per-item details\n- 📈 **Per-Item Statistics**: Detailed statistics for each item including session count, average session duration, reading speed, last read date, and a page-level reading activity heatmap\n- 🔍 **Search \u0026 Filter**: Search through your library by title, author, or series, with filters for reading status\n- ⬇️ **Original File Downloads**: Download original item files from item detail pages, including static exports when `--include-files` is enabled\n- 🔐 **Optional Authentication**: Password-protect server mode with session-based auth, login rate limiting, password rotation, and session management\n- 🚀 **Static Site**: Generates a complete static website you can host anywhere\n- 🖥️ **Server Mode**: Built-in web server with live file watching for use with reverse proxy\n- 📱 **Responsive**: Optimized for desktop, tablet, and mobile with adaptive grid layouts\n\n## Screenshots\n\n![Library overview](https://github.com/user-attachments/assets/ad096bc9-c53a-40eb-9de9-06085e854a26)\n![Book details](https://github.com/user-attachments/assets/44113be0-aa19-4018-b864-135ddb067a9d)\n![Reading calendar](https://github.com/user-attachments/assets/a4ac51f1-927e-463d-b2d6-72c29fdc4323)\n![Recap](https://github.com/user-attachments/assets/9558eea9-dee1-4b0a-adac-1bc0157f0181)\n\n## Quick Start\n\n### Install\n\n**Home Assistant** — [One-click install](https://my.home-assistant.io/redirect/supervisor_addon/?addon=5d189d71_koshelf\u0026repository_url=https%3A%2F%2Fgithub.com%2Fpaviro%2Fhome-assistant-addons)\n\n[![Open your Home Assistant instance and show the dashboard of an add-on.](https://my.home-assistant.io/badges/supervisor_addon.svg)](https://my.home-assistant.io/redirect/supervisor_addon/?addon=5d189d71_koshelf\u0026repository_url=https%3A%2F%2Fgithub.com%2Fpaviro%2Fhome-assistant-addons)\n\n**Docker Compose** — Community-maintained image via [koshelf-docker](https://github.com/DevTigro/koshelf-docker). See the [Installation Guide](docs/installation.md) for a sample `docker-compose.yml`.\n\n**Prebuilt binaries** — Download from the [releases page](https://github.com/paviro/koshelf/releases) (Windows x64, macOS, Linux x64/ARM64).\n\nFor detailed installation instructions (building from source, first-time CLI guide, Windows Defender notes), see the [Installation Guide](docs/installation.md).\n\n### Usage\n\n```bash\n# Start a web server (live file watching, requires --data-path)\nkoshelf serve -i ~/Library --data-path ~/koshelf-data\n\n# Generate a static site\nkoshelf export ~/my-reading-site -i ~/Library\n\n# Generate a static site with downloadable original files\nkoshelf export ~/my-reading-site -i ~/Library --include-files\n```\n\nFor all subcommands, options, environment variables, and examples, see the [Configuration Guide](docs/configuration.md).\n\n## Documentation\n\n| Guide | Description |\n|-------|-------------|\n| [Installation](docs/installation.md) | Home Assistant, Docker, prebuilt binaries, building from source |\n| [Configuration](docs/configuration.md) | Subcommands, CLI options, environment variables, config file, examples |\n| [KoReader Setup](docs/koreader-setup.md) | Metadata storage options (sdr/hashdocsettings/docsettings), deployment setup |\n| [Authentication](docs/authentication.md) | Password authentication for serve mode |\n| [Supported Data](docs/supported-data.md) | Supported formats and extracted metadata fields |\n| [Stable Page Metadata](docs/stable-page-metadata.md) | KOReader stable page metadata \u0026 synthetic page scaling |\n| [Static Export](docs/static-export.md) | Generated site directory structure |\n| [API Reference](docs/API.md) | REST API endpoints, parameters, and response schemas |\n| [Syncthing Setups](docs/syncthing_setups/README.md) | Community-contributed device sync guides |\n\n## Credits\n\nDesign and feature inspiration comes from [KoInsight](https://github.com/GeorgeSG/KoInsight), an excellent alternative that focuses on reading statistics and can also act as a KOReader sync server.\n\nThe calendar view is powered by [EventCalendar](https://github.com/vkurko/calendar), a lightweight JavaScript event calendar library.\n\n## Disclaimer\n\nThis was built for personal use and relies heavily on AI-generated code. While I've tested everything and use it daily, I take no responsibility for any issues you might encounter. Use at your own risk.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpaviro%2Fkoshelf","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fpaviro%2Fkoshelf","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpaviro%2Fkoshelf/lists"}