John O'Keefe
a8f8c4def9
Three problems, one root cause each: 1. Sidebar jump: the server rendered its own default (current section open, rest collapsed) and restoreDocsNav corrected it after paint — open-then-close. Fix: persistence moved server-side. toggleCollapsible now writes a docs_nav cookie (strictly-necessary UI state, no identifiers, SameSite=Lax); ApplyNavOverrides merges it into the nav before render, so first paint IS the visitor's state. The post-paint restore is deleted. 2. Arrows out of sync / double-click: two visibility mechanisms disagreed. There was NO data-collapsed CSS at all — collapsed sections were only ever hidden by JS after paint, and the arrow rotation came from a different (server) state. Now: style.css hides on [data-collapsed=true] (single source of truth, server-rendered), applyCollapsed sets only the attribute, arrows rotate from the same merged value. Live check: 37/37 collapsibles arrow-consistent. 3. api-reference.md links: all 20+ quick links were directory-style (authentication/ etc.) that 404 on the docs site, plus stale targets (books/, ../collections-api.md, websocket 'coming soon'). Rewritten to real per-file links — all 9 unique targets return 200 live. Same rot fixed in admin/hash-conflicts.md, development.md, android-app.md, create_media_item.md, koreader-protocol.md; docs/index.md redirected from the deleted collections-api monolith (stale 530-line duplicate of the gated api/collections docs — deleted, per the WO2 doctrine). New gate: TestDocsRelativeLinks walks docs/developer/** and fails make test on any relative link that is directory-style or unresolvable — overview links can never silently rot again.
96 lines
3.1 KiB
Markdown
96 lines
3.1 KiB
Markdown
# Developer Documentation
|
|
|
|
Welcome to the Bookhoard developer documentation. This section contains API references, protocol specifications, and technical documentation for integrating with Bookhoard.
|
|
|
|
## 📚 API Documentation
|
|
|
|
### Complete API Reference
|
|
|
|
- **[API Reference](api/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
|
|
|
|
### Split Endpoint Documentation
|
|
|
|
Browse individual endpoint documentation with interactive API Explorer:
|
|
|
|
- **[API Documentation](api/api-reference.md)** - Split endpoint docs
|
|
- [Authentication](api/authentication/login.md) - Register, login, tokens
|
|
- [Users](api/users/get_profile.md) - Profile management
|
|
- [Libraries](api/libraries/list_libraries.md) - Library operations
|
|
- [Media Items](api/media-items/get_media_item.md) - Book/ebook management
|
|
- [Progress](api/progress/get_media_progress.md) - Reading progress tracking
|
|
- [Notes](api/notes/get_notes.md) - User notes
|
|
- [Highlights](api/highlights/get_highlights.md) - Book highlights
|
|
- [Ratings](api/ratings/get_ratings.md) - Book ratings
|
|
- [Devices](api/devices/get_devices.md) - Device management
|
|
- [Analytics](api/analytics/get_analytics.md) - Usage statistics
|
|
- [Book Matching](api/book-matching/search_books.md) - Search and link books
|
|
- [Collections](api/collections/list_collections.md) - Collection management
|
|
- [OPDS](api/opds/feeds.md) - Open Publication Distribution
|
|
- [Sync Protocols](api/sync/koreader-protocol.md) - KOReader and Kobo sync
|
|
- [WebSocket](api/websocket/protocol.md) - Real-time events
|
|
|
|
### Collections API
|
|
|
|
- **[Collections API](api/collections/list_collections.md)** - Complete collections API reference
|
|
- Create and manage collections
|
|
- Auto-assign rules
|
|
- Test rules
|
|
- Bulk operations
|
|
- Device shelf mappings
|
|
|
|
## 🔌 Protocol Specifications
|
|
|
|
### Sync Protocols
|
|
|
|
- **[Kobo Sync Protocol](api/sync/kobo-protocol.md)** - Kobo device sync protocol
|
|
- Kobo markup sync
|
|
- Library fetch
|
|
- Authentication
|
|
|
|
- **[KOReader Sync Protocol](api/sync/koreader-protocol.md)** - KOReader sync protocol
|
|
- Progress sync
|
|
- Metadata fetch
|
|
- Conflict handling
|
|
|
|
### WebSocket Protocol
|
|
|
|
- **[WebSocket API](websocket-api.md)** - Real-time sync and events
|
|
- Connection flow
|
|
- Message format
|
|
- Event types
|
|
- Authentication
|
|
|
|
## 🛠 Implementation Guides
|
|
|
|
### Library Visibility
|
|
|
|
- **[Library Visibility](library-visibility.md)** - Per-user library
|
|
visibility: the family-lens rule. New media endpoints MUST thread the
|
|
visible-library set (helpers, SQL pattern, series per-library).
|
|
|
|
### Calibre Integration
|
|
|
|
- **[Calibre OPF Implementation](../development/calibre-opf-implementation.md)** - Technical implementation details
|
|
- Architecture and design
|
|
- Data structures and functions
|
|
- Database schema mapping
|
|
- Testing strategy
|
|
- Error handling
|
|
- Performance considerations
|
|
|
|
---
|
|
|
|
**Looking for user documentation?** See the [User Portal](../user/user-guide.md)
|
|
**Need to deploy?** See the [Operations Portal](../operations/operations.md)
|