Bookhoard/bookhoard
0
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases 12 Wiki Activity
Files
afdcc7b589f244687fedecf8976d6aff201cff28
bookhoard/docs/INDEX.md
T
john-okeefe 7135571de8 docs: reorganize documentation structure for users and self-hosters 
- Remove internal development docs (phase tracking, implementation plans, security audits)
- Move DEVELOPMENT.md to docs/contributing/ for contributor guidance
- Move TROUBLESHOOTING.md from root to docs/ folder
- Add docs/INDEX.md as navigation hub for all documentation
- Clean up docs to focus on user/self-hoster facing content

This reorganization separates user-facing documentation from
internal contributor documentation, making the project more
approachable for self-hosters.
2026-02-01 17:33:40 -05:00

230 lines
8.5 KiB
Markdown
Raw Blame History

# Bookhoard Documentation Index
Complete guide to Bookhoard documentation. Find what you need quickly.
---
## 🚀 Quick Links
### For New Users
1. [README.md](../README.md) - **Start here!** Project overview and quick start
2. [docs/SYNC_USER_GUIDE.md](SYNC_USER_GUIDE.md) - Understanding and using sync
3. [docs/devices/KOBO_SETUP.md](devices/KOBO_SETUP.md) - Kobo e-reader setup
4. [docs/devices/KOREADER_SETUP.md](devices/KOREADER_SETUP.md) - KOReader setup
### For Self-Hosting
1. [docs/TROUBLESHOOTING.md](TROUBLESHOOTING.md) - Deployment and troubleshooting
2. [.env.example](../.env.example) - Secrets configuration (JWT and DB password)
### For Contributors
1. [docs/contributing/DEVELOPMENT.md](contributing/DEVELOPMENT.md) - Development workflow and architecture
2. [docs/API_REFERENCE.md](API_REFERENCE.md) - Complete API documentation
3. [docs/COLLECTIONS_API.md](COLLECTIONS_API.md) - Collections API
4. [docs/api/WEBSOCKET_API.md](api/WEBSOCKET_API.md) - WebSocket protocol
---
## 📚 Documentation by Topic
### Getting Started
- **[README.md](../README.md)** - Project overview, features, quick start guide
- **[docs/contributing/DEVELOPMENT.md](contributing/DEVELOPMENT.md)** - Development environment setup
### Deployment & Operations
- **[docs/TROUBLESHOOTING.md](TROUBLESHOOTING.md)** - Common deployment issues and solutions
- **[.env.example](../.env.example)** - Required secrets (JWT_SECRET, DBPASS)
- **[docker-compose.yml](../docker-compose.yml)** - Operational configuration with defaults
- **[Makefile](../Makefile)** - Build and test commands
### Using Sync Features
- **[docs/SYNC_USER_GUIDE.md](SYNC_USER_GUIDE.md)** - Universal sync user guide
- Understanding sync
- Book matching and auto-linking
- Conflict resolution
- Best practices
### Device Setup
- **[docs/devices/KOBO_SETUP.md](devices/KOBO_SETUP.md)** - Kobo e-reader configuration
- Device registration
- Sync configuration
- OPDS wireless book delivery
- Troubleshooting
- **[docs/devices/KOREADER_SETUP.md](devices/KOREADER_SETUP.md)** - KOReader configuration
- Installation on Kindle/Kobo/PocketBook
- Sync setup
- OPDS catalog access
- Troubleshooting
### API Documentation
- **[docs/API_REFERENCE.md](API_REFERENCE.md)** - Complete REST API reference
- Authentication
- User management
- Libraries
- Media items
- Reading progress
- Notes & highlights
- Analytics
- Book matching
- OPDS
- Sync protocols (KOReader, Kobo)
- WebSocket
- **[docs/COLLECTIONS_API.md](COLLECTIONS_API.md)** - Collections API
- Create and manage collections
- Auto-assign rules
- Test rules
- Bulk operations
- Device shelf mappings
- **[docs/api/WEBSOCKET_API.md](api/WEBSOCKET_API.md)** - WebSocket protocol
- Connection flow
- Message format
- Real-time sync broadcasts
- Authentication
### Contributing
- **[docs/contributing/DEVELOPMENT.md](contributing/DEVELOPMENT.md)** - Development guide
- Architecture overview
- Directory structure
- Local development setup
- Testing guidelines
- Code style
- Deployment
- **[PROJECT_GUIDELINES.md](../PROJECT_GUIDELINES.md)** - Development rules and standards
- Critical prohibitions
- Mandatory requirements
- Error recovery protocol
### Reference
- **[go.mod](../go.mod)** - Go dependencies
- **[database/schema/schema.sql](../database/schema/schema.sql)** - Database schema
- **[bruno/](../bruno/)** - API test collections
---
## 📖 Reading Path by Role
### Self-Hoster / End User
**Goal**: Set up and use Bookhoard for reading
1. Start with [README.md](../README.md) - Understand what Bookhoard is
2. Follow quick start in README.md to get running
3. Set up your device:
- Kobo: [docs/devices/KOBO_SETUP.md](devices/KOBO_SETUP.md)
- KOReader: [docs/devices/KOREADER_SETUP.md](devices/KOREADER_SETUP.md)
4. Learn about sync: [docs/SYNC_USER_GUIDE.md](SYNC_USER_GUIDE.md)
5. If issues arise: [docs/TROUBLESHOOTING.md](TROUBLESHOOTING.md)
### Developer
**Goal**: Contribute to Bookhoard or integrate with it
1. Start with [README.md](../README.md) - Project overview
2. Read [docs/contributing/DEVELOPMENT.md](contributing/DEVELOPMENT.md) - Architecture and setup
3. Review [docs/API_REFERENCE.md](API_REFERENCE.md) - API endpoints
4. Check [PROJECT_GUIDELINES.md](../PROJECT_GUIDELINES.md) - Development rules
5. Explore codebase and contribute!
### API Integrator
**Goal**: Build integration with Bookhoard
1. Review [README.md](../README.md) - Feature overview
2. Study [docs/API_REFERENCE.md](API_REFERENCE.md) - All endpoints
3. Check specialized docs:
- Collections: [docs/COLLECTIONS_API.md](COLLECTIONS_API.md)
- WebSocket: [docs/api/WEBSOCKET_API.md](api/WEBSOCKET_API.md)
- Sync: [docs/SYNC_USER_GUIDE.md](SYNC_USER_GUIDE.md)
4. Test with [bruno/](../bruno/) collections
---
## 🔍 Quick Find
### "How do I..."
| ...do this? | See this document |
|-------------|------------------|
| ...install Bookhoard? | [README.md](../README.md) - Quick Start |
| ...set up my Kobo? | [docs/devices/KOBO_SETUP.md](devices/KOBO_SETUP.md) |
| ...set up KOReader? | [docs/devices/KOREADER_SETUP.md](devices/KOREADER_SETUP.md) |
| ...understand sync? | [docs/SYNC_USER_GUIDE.md](SYNC_USER_GUIDE.md) |
| ...resolve conflicts? | [docs/SYNC_USER_GUIDE.md](SYNC_USER_GUIDE.md) - Managing Conflicts |
| ...match books? | [docs/SYNC_USER_GUIDE.md](SYNC_USER_GUIDE.md) - Book Matching |
| ...troubleshoot deployment? | [docs/TROUBLESHOOTING.md](TROUBLESHOOTING.md) |
| ...use the API? | [docs/API_REFERENCE.md](API_REFERENCE.md) |
| ...set up development? | [docs/contributing/DEVELOPMENT.md](contributing/DEVELOPMENT.md) |
| ...contribute code? | [docs/contributing/DEVELOPMENT.md](contributing/DEVELOPMENT.md) - Contributing |
### "Where is..."
| ...this information? | See this document |
|-------------------|------------------|
| ...features list? | [README.md](../README.md) |
| ...database schema? | [database/schema/schema.sql](../database/schema/schema.sql) |
| ...API endpoints? | [docs/API_REFERENCE.md](API_REFERENCE.md) |
| ...secrets config? | [.env.example](../.env.example) |
| ...operational config? | [docker-compose.yml](../docker-compose.yml) |
| ...deployment issues? | [docs/TROUBLESHOOTING.md](TROUBLESHOOTING.md) |
---
## 📊 Documentation Statistics
| File | Lines | Purpose | Audience |
|------|-------|---------|----------|
| README.md | 150 | Overview & quick start | Everyone |
| contributing/DEVELOPMENT.md | 450 | Development workflow | Contributors |
| API_REFERENCE.md | 1,300+ | Complete REST API | Developers, integrators |
| COLLECTIONS_API.md | 494 | Collections API | Developers, integrators |
| SYNC_USER_GUIDE.md | 350+ | Sync usage guide | End users |
| TROUBLESHOOTING.md | 300 | Deployment troubleshooting | Self-hosters |
| KOBO_SETUP.md | 598 | Kobo setup | Kobo users |
| KOREADER_SETUP.md | 504 | KOReader setup | KOReader users |
| WEBSOCKET_API.md | 676 | WebSocket protocol | Developers |
| PROJECT_GUIDELINES.md | 250 | Development rules | Developers |
**Total**: ~5,000 lines of comprehensive documentation
---
## 🎯 Common Tasks
### Set up a new device
1. Device setup guide: [docs/devices/KOBO_SETUP.md](devices/KOBO_SETUP.md) or [docs/devices/KOREADER_SETUP.md](devices/KOREADER_SETUP.md)
2. Sync overview: [docs/SYNC_USER_GUIDE.md](SYNC_USER_GUIDE.md)
3. Troubleshooting: Device-specific setup guides
### Troubleshoot sync issues
1. Check [docs/SYNC_USER_GUIDE.md](SYNC_USER_GUIDE.md) - "Managing Conflicts" and "Best Practices"
2. Review device-specific guide for common issues
3. Check [docs/TROUBLESHOOTING.md](TROUBLESHOOTING.md) for general issues
### Integrate with Bookhoard API
1. Start with [docs/API_REFERENCE.md](API_REFERENCE.md) - Complete API reference
2. Check [docs/COLLECTIONS_API.md](COLLECTIONS_API.md) for collections
3. Review [docs/api/WEBSOCKET_API.md](api/WEBSOCKET_API.md) for real-time updates
4. Use [bruno/](../bruno/) test collections as examples
### Deploy to production
1. Follow [README.md](../README.md) quick start
2. Configure environment: [.env.example](../.env.example)
3. Review [docs/TROUBLESHOOTING.md](TROUBLESHOOTING.md) for common issues
4. Check [docs/contributing/DEVELOPMENT.md](contributing/DEVELOPMENT.md) for performance tuning
---
## 📝 Contributing to Documentation
When adding new features:
1. Update [README.md](../README.md) - Add to features list if user-facing
2. Update [docs/API_REFERENCE.md](API_REFERENCE.md) - Document new endpoints
3. Add/update tests in [bruno/](../bruno/)
4. Update relevant guides (SYNC_USER_GUIDE.md, device guides, etc.)
5. Keep [PROJECT_GUIDELINES.md](../PROJECT_GUIDELINES.md) in mind
---
**Last Updated**: 2026-02-01
**Bookhoard Version**: 1.0
Reference in New Issue View Git Blame Copy Permalink