0 Fork 0

Files

T

John O'Keefe a8f8c4def9 docs(ui): cookie-rendered sidebar state, data-collapsed CSS, working overview links + link-checker gate

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.

2026-10-24 20:20:07 -04:00

6.7 KiB

Raw Blame History

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
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 endpoints with interactive API Explorer
- 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

6.7 KiB Raw Blame History