Bookhoard/bookhoard
0
0 Fork 0
Code Issues 1 Pull Requests Actions Packages Projects Releases 69 Wiki Activity

docs(gates): widen relative-link checker to all docs, repair the rot it finds

Browse Source 
TestDocsRelativeLinks walked only docs/developer; widening it to all of
docs/ immediately surfaced the same class of rot the gate was built
for, outside its old reach:

- docs/index.md was the old monolith's landing page: linked the deleted
  api-reference.md, 10 directory-style area links, and escaped the docs
  tree to README/AGENTS/.env/compose. Rewritten as a portal whose every
  link resolves, with one representative endpoint doc per API area and
  pointers to the new writing-ui-docs.md standard.
- directory-style links in user stubs (devices/, ../operations/)
- case-mismatched links (Development.md) in contributing.md
- monolith-era pointer (API_REFERENCE.md, TROUBLESHOOTING.md) and
  escaped AGENTS.md links in contributing/development.md
- docs/development/calibre-opf-implementation.md double-up escapes, a
  link to the removed repo-root plan file (absorbed here), and a
  source-code hyperlink the docs site can't serve (now inline code)
- operations/operations.md linked three never-written guide pages as
  aspirational links - they stay plain text until pages exist

HANDS-OFF (project owner, 2026-11-02): docs/user/filters/** and
docs/user/searching-and-filtering.md are exempt as link sources so no
future checker failure can force edits to the filter documentation.
Files linking INTO them remain checked.
This commit is contained in:
John O'Keefe committed 2026-11-02 08:21:47 -05:00
1 parent bf4735f3ce
commit 913174cdf8
10 files changed
+85 -111
Download Patch File Download Diff File Expand all files Collapse all files

No files matched your search

docs/index.md
+40 -81
View File
@@ -13,6 +13,7 @@ Complete guide to Bookhoard documentation. Find what you need quickly.
- **Device Setup**
- [KOReader Setup Guide](user/devices/koreader-setup.md) - KOReader on Kindle/Kobo/PocketBook hardware
- [Kobo Setup Guide](user/devices/kobo-setup.md) - Native Kobo sync (coming soon; use KOReader today)
- [Android App](user/devices/android-app.md)
- **Sync Configuration**
- [Universal Sync Guide](user/sync-guide.md) - Understanding sync, book matching, conflicts
@@ -22,53 +23,51 @@ Complete guide to Bookhoard documentation. Find what you need quickly.
- [Filter cookbook](user/filters/cookbook.md) - ready-made recipes, exact clicks
- [Every filter field](user/filters/fields.md) - the generated, always-current reference
- **Frontend & Settings** (Coming Soon)
- Frontend Guide
- User Areas Guide
- Settings Guide
- Admin Guide
- **Guides**
- [Reader Guide](user/reader-guide.md) - reading, highlights, notes
- [Library Browsing](user/library-browsing.md) - browsing and searching your library
- [Collections](user/collections.md) - manual and ⚡ smart shelves, books and episodes
- [Dashboard](user/dashboard.md)
- [Themes](user/themes.md)
- [Calibre Integration](user/calibre-integration.md)
- [Settings Guide](user/settings-guide.md)
- [Profile Guide](user/profile-guide.md)
- [Admin Guide](user/admin-guide.md)
- [Frontend Guide](user/frontend-guide.md)
### 👨‍💻 For Developers
**[Developer Documentation Portal](developer/development.md)** - Technical documentation & API reference
- **API Documentation**
- [Complete API Reference](developer/api-reference.md) - Monolithic REST API reference (1,300+ lines)
- [Split Endpoint Docs](developer/api/api-reference.md) - Individual endpoint docs
- [Collections API](developer/api/collections/list_collections.md) - Collections management API
- [Admin API](developer/api/admin/) - User management (admin operations)
- [Media Items API](developer/api/media-items/) - Media item operations including bulk operations and downloads
- [Devices API](developer/api/devices/) - Device sync and shelf management
- [Conflicts API](developer/api/conflicts/) - Sync conflict resolution endpoints
- [Queue API](developer/api/queue/) - Sync queue management endpoints
- [Scanner API](developer/api/scanner/) - Library scanning and automated watch mode (admin)
- [KOReader API](developer/api/koreader/) - KOReader sync protocol endpoints
- [Kobo API](developer/api/kobo/) - Kobo sync protocol endpoints (feature coming soon)
- [WebSocket API](developer/api/websocket/) - Real-time sync events
- **API Documentation** — every endpoint is documented individually; the links below are entry points
- [API Reference overview](developer/api/api-reference.md) - index of all endpoint docs
- [Collections API](developer/api/collections/list_collections.md) - collections management API
- [Media Items API](developer/api/media-items/list_media_items.md) - media item operations including bulk operations and downloads
- [Devices API](developer/api/devices/list_devices.md) - Device sync and shelf management
- [Conflicts API](developer/api/conflicts/list_conflicts.md) - Sync conflict resolution endpoints
- [Queue API](developer/api/queue/list_all_queue_items.md) - Sync queue management endpoints
- [Scanner API](developer/api/scanner/overview.md) - Library scanning and automated watch mode (admin)
- [KOReader API](developer/api/koreader/get_library.md) - KOReader sync protocol endpoints
- [Kobo API](developer/api/kobo/sync_from_server.md) - Kobo sync protocol endpoints
- [Admin API](developer/api/admin/list_users.md) - User management (admin operations); content-duplicate cleanup lives in [hash conflicts](developer/api/admin/hash_conflicts_api.md)
- **Protocol Specifications**
- [KOReader Sync Protocol](developer/api/sync/koreader-protocol.md) - KOReader sync
- [Kobo Sync Protocol](developer/api/sync/kobo-protocol.md) - Kobo device sync (coming soon)
- [WebSocket API](developer/websocket-api.md) - Real-time events
- [Kobo Sync Protocol](developer/api/sync/kobo-protocol.md) - Kobo device sync
- **Writing UI docs?** Read [Writing UI documentation without screenshots](developer/writing-ui-docs.md) first.
### 🔧 For Operations
**[Operations Documentation Portal](operations/operations.md)** - Deployment & maintenance
- **Deployment**
- [Troubleshooting Guide](operations/troubleshooting.md) - Common deployment issues and solutions
- **Maintenance** (Coming Soon)
- Deployment Guide
- Maintenance Guide
- Monitoring Guide
- [Troubleshooting Guide](operations/troubleshooting.md) - Common deployment issues and solutions
### 🤝 For Contributors
**[Contributing Portal](contributing/contributing.md)** - Development workflow
- [Development Guide](contributing/development.md) - Architecture, setup, testing
- [../../AGENTS.md](../../AGENTS.md) - Development rules and standards
- [Development Guide](contributing/development.md) - Architecture, setup, testing, and the project rules
---
@@ -76,11 +75,11 @@ Complete guide to Bookhoard documentation. Find what you need quickly.
| Want to... | Go to |
| -------------------- | ---------------------------------------------------------------------- |
| **Get started** | [README.md](../README.md) - Project overview and quick start |
| **Get started** | [Development Guide](contributing/development.md) - Architecture and quick start |
| **Set up a device** | [User Portal → Device Setup](user/user-guide.md) |
| **Use the API** | [Developer Portal → API Docs](developer/development.md) |
| **Deploy Bookhoard** | [Operations Portal → Troubleshooting](operations/troubleshooting.md) |
| **Contribute code** | [Contributing Portal → Development Guide](contributing/development.md) |
| **Use the API** | [API Reference overview](developer/api/api-reference.md) |
| **Deploy Bookhoard** | [Operations → Troubleshooting](operations/troubleshooting.md) |
| **Contribute code** | [Development Guide](contributing/development.md) |
| **Understand sync** | [User Portal → Sync Guide](user/sync-guide.md) |
| **Read in the browser** | [User Portal → Web Reader Guide](user/reader-guide.md) |
@@ -92,65 +91,25 @@ Complete guide to Bookhoard documentation. Find what you need quickly.
| Question | Answer |
| --------------------------- | ------------------------------------------------------ |
| ...install Bookhoard? | [README.md](../README.md) - Quick Start |
| ...set up KOReader? | [KOReader Setup Guide](user/devices/koreader-setup.md) |
| ...use a Kobo? | [Kobo Setup Guide](user/devices/kobo-setup.md) - native sync coming soon; KOReader works today |
| ...understand sync? | [Sync Guide](user/sync-guide.md) |
| ...read in the browser? | [Web Reader Guide](user/reader-guide.md) - reading, highlights, notes |
| ...resolve conflicts? | [Sync Guide](user/sync-guide.md) - Managing Conflicts |
| ...troubleshoot deployment? | [Troubleshooting Guide](operations/troubleshooting.md) |
| ...use the API? | [API Reference](developer/api-reference.md) |
| ...use the API? | [API Reference overview](developer/api/api-reference.md) |
| ...write UI docs? | [Writing UI documentation](developer/writing-ui-docs.md) |
| ...contribute code? | [Development Guide](contributing/development.md) |
### "Where is..."
| Information | Location |
| ---------------------- | ----------------------------------------------------------- |
| ...features list? | [README.md](../README.md) |
| ...database schema? | [database/schema/schema.sql](../database/schema/schema.sql) |
| ...API endpoints? | [API Reference](developer/api-reference.md) |
| ...secrets config? | [.env.example](../.env.example) |
| ...operational config? | [docker-compose.yml](../docker-compose.yml) |
| ...deployment issues? | [Troubleshooting Guide](operations/troubleshooting.md) |
---
## 🎯 Common Workflows
### Set up a new device
1. Choose your device: [KOReader](user/devices/koreader-setup.md) (works on Kindle, Kobo, and PocketBook hardware)
2. Understand sync: [Sync Guide](user/sync-guide.md)
3. Troubleshoot: Device-specific guides
### Integrate with Bookhoard API
1. Start with [API Reference](developer/api-reference.md)
2. Explore [Collections API](developer/api/collections/list_collections.md)
3. Review [WebSocket API](developer/websocket-api.md)
4. Test with [bruno/](../bruno/) collections
### Deploy to production
1. Follow [README.md](../README.md) quick start
2. Configure environment: [.env.example](../.env.example)
3. Review [Troubleshooting Guide](operations/troubleshooting.md)
4. Check [Development Guide](contributing/development.md) for performance tuning
---
## 📝 Contributing to Documentation
When adding new features:
1. **User-facing features** → Update relevant User docs
2. **API endpoints** → Update [API Reference](developer/api-reference.md) & split docs
3. **Backend changes** → Update [Development Guide](contributing/development.md)
4. **Deployment changes** → Update [Operations Portal](operations/operations.md)
Keep [../../AGENTS.md](../../AGENTS.md) in mind for documentation standards.
---
**Last Updated**: August 2026
**Bookhoard Version**: 1.0
1. **User-facing features** → Update the relevant User docs
2. **API endpoints** → Update the endpoint docs under `developer/api/` (start from the [API Reference overview](developer/api/api-reference.md))
3. **Backend changes** → Update the [Development Guide](contributing/development.md)
4. **Deployment changes** → Update the [Operations Portal](operations/operations.md)
5. **New UI controls in docs** → Add them to the [UI controls glossary](developer/ui-controls.md)
6. **UI appearances in docs** → Follow [Writing UI documentation without screenshots](developer/writing-ui-docs.md)