John O'Keefe
a4dc03984c
The filter manual (1ed1602e) was reachable only by knowing /docs
already existed — nothing in the UI pointed at it (the parked manual
plan's open decision). Every filter-builder mount now carries a "?"
in its header linking to the guide (opens in a new tab so drawer and
editor state survive): the All Books drawer and the collection rules
page — the two mounts sharing FilterBuilderRows. The docs home
indexes the manual (guide, cookbook, generated field reference).
Two docs-loader fixes surfaced by pinning this:
- Folder URLs resolve to their index page: /docs/user/filters now
serves user/filters/index.md (the manual is a folder: guide +
cookbook + generated reference); previously only root /docs had
index handling.
- The docs folder path is resolved by walking upward (bounded):
`go test` runs test binaries from the PACKAGE directory, so the
relative "docs" path resolved to a folder that didn't exist there
and every /docs route 404'd in tests while working in prod —
found by the new pin, fixed so tests exercise the docs routes
exactly as prod serves them.
Pins: TestFilterHelpAffordance (folder URL serves the guide; drawer
and rules pages carry the link). internal/docs suite + full suite
green (239s).
7.0 KiB
7.0 KiB
Bookhoard Documentation
Complete guide to Bookhoard documentation. Find what you need quickly.
🚀 By Audience
👤 For End Users
User Documentation Portal - Guides for using Bookhoard features
-
Device Setup
- KOReader Setup Guide - KOReader on Kindle/Kobo/PocketBook hardware
- Kobo Setup Guide - Native Kobo sync (coming soon; use KOReader today)
-
Sync Configuration
- Universal Sync Guide - Understanding sync, book matching, conflicts
-
Filters
- Filters — the complete guide - rules, groups (ALL/ANY), saved filters, smart collections
- Filter cookbook - ready-made recipes, exact clicks
- Every filter field - the generated, always-current reference
-
Frontend & Settings (Coming Soon)
- Frontend Guide
- User Areas Guide
- Settings Guide
- Admin Guide
👨💻 For Developers
Developer Documentation Portal - Technical documentation & API reference
-
API Documentation
- Complete API Reference - Monolithic REST API reference (1,300+ lines)
- Split Endpoint Docs - Individual endpoint docs
- Collections API - Collections management API
- Admin API - User management (admin operations)
- Media Items API - Media item operations including bulk operations and downloads
- Devices API - Device sync and shelf management
- Conflicts API - Sync conflict resolution endpoints
- Queue API - Sync queue management endpoints
- Scanner API - Library scanning and automated watch mode (admin)
- KOReader API - KOReader sync protocol endpoints
- Kobo API - Kobo sync protocol endpoints (feature coming soon)
- WebSocket API - Real-time sync events
-
Protocol Specifications
- KOReader Sync Protocol - KOReader sync
- Kobo Sync Protocol - Kobo device sync (coming soon)
- WebSocket API - Real-time events
🔧 For Operations
Operations Documentation Portal - Deployment & maintenance
-
Deployment
- Troubleshooting Guide - Common deployment issues and solutions
-
Maintenance (Coming Soon)
- Deployment Guide
- Maintenance Guide
- Monitoring Guide
🤝 For Contributors
Contributing Portal - Development workflow
- Development Guide - Architecture, setup, testing
- ../../AGENTS.md - Development rules and standards
📚 Quick Links
| Want to... | Go to |
|---|---|
| Get started | README.md - Project overview and quick start |
| Set up a device | User Portal → Device Setup |
| Use the API | Developer Portal → API Docs |
| Deploy Bookhoard | Operations Portal → Troubleshooting |
| Contribute code | Contributing Portal → Development Guide |
| Understand sync | User Portal → Sync Guide |
| Read in the browser | User Portal → Web Reader Guide |
🔍 Quick Find
"How do I..."
| Question | Answer |
|---|---|
| ...install Bookhoard? | README.md - Quick Start |
| ...set up KOReader? | KOReader Setup Guide |
| ...use a Kobo? | Kobo Setup Guide - native sync coming soon; KOReader works today |
| ...understand sync? | Sync Guide |
| ...read in the browser? | Web Reader Guide - reading, highlights, notes |
| ...resolve conflicts? | Sync Guide - Managing Conflicts |
| ...troubleshoot deployment? | Troubleshooting Guide |
| ...use the API? | API Reference |
| ...contribute code? | Development Guide |
"Where is..."
| Information | Location |
|---|---|
| ...features list? | README.md |
| ...database schema? | database/schema/schema.sql |
| ...API endpoints? | API Reference |
| ...secrets config? | .env.example |
| ...operational config? | docker-compose.yml |
| ...deployment issues? | Troubleshooting Guide |
🎯 Common Workflows
Set up a new device
- Choose your device: KOReader (works on Kindle, Kobo, and PocketBook hardware)
- Understand sync: Sync Guide
- Troubleshoot: Device-specific guides
Integrate with Bookhoard API
- Start with API Reference
- Explore Collections API
- Review WebSocket API
- Test with bruno/ collections
Deploy to production
- Follow README.md quick start
- Configure environment: .env.example
- Review Troubleshooting Guide
- Check Development Guide for performance tuning
📝 Contributing to Documentation
When adding new features:
- User-facing features → Update relevant User docs
- API endpoints → Update API Reference & split docs
- Backend changes → Update Development Guide
- Deployment changes → Update Operations Portal
Keep ../../AGENTS.md in mind for documentation standards.
Last Updated: August 2026 Bookhoard Version: 1.0