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.
3.1 KiB
3.1 KiB
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 - 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 - Split endpoint docs
- Authentication - Register, login, tokens
- Users - Profile management
- Libraries - Library operations
- Media Items - Book/ebook management
- Progress - Reading progress tracking
- Notes - User notes
- Highlights - Book highlights
- Ratings - Book ratings
- Devices - Device management
- Analytics - Usage statistics
- Book Matching - Search and link books
- Collections - Collection management
- OPDS - Open Publication Distribution
- Sync Protocols - KOReader and Kobo sync
- WebSocket - Real-time events
Collections API
- Collections API - 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 - Kobo device sync protocol
- Kobo markup sync
- Library fetch
- Authentication
-
KOReader Sync Protocol - KOReader sync protocol
- Progress sync
- Metadata fetch
- Conflict handling
WebSocket Protocol
- WebSocket API - Real-time sync and events
- Connection flow
- Message format
- Event types
- Authentication
🛠 Implementation Guides
Library Visibility
- Library Visibility - 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 - 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 Need to deploy? See the Operations Portal