docs(gates): widen relative-link checker to all docs, repair the rot it finds
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
1 parent
bf4735f3ce
commit
913174cdf8
10 files changed
+85
-111
No files matched your search
@@ -4,7 +4,7 @@ Welcome to the Bookhoard contributing documentation. This section contains guide
|
||||
|
||||
## 🚀 Getting Started
|
||||
|
||||
- **[Development Guide](Development.md)** - Development workflow and architecture
|
||||
- **[Development Guide](development.md)** - Development workflow and architecture
|
||||
- Architecture overview
|
||||
- Directory structure
|
||||
- Local development setup
|
||||
@@ -14,7 +14,7 @@ Welcome to the Bookhoard contributing documentation. This section contains guide
|
||||
|
||||
## 📋 Project Guidelines
|
||||
|
||||
- **[AGENTS.md](../../AGENTS.md)** - Agent/development rules
|
||||
- **[AGENTS.md](../contributing/contributing.md)** - Development rules and standards live in the Contributing portal
|
||||
- Critical prohibitions
|
||||
- Mandatory requirements
|
||||
- Error recovery protocol
|
||||
@@ -22,7 +22,7 @@ Welcome to the Bookhoard contributing documentation. This section contains guide
|
||||
|
||||
## 🤝 How to Contribute
|
||||
|
||||
We welcome contributions! Please see our [Development Guide](Development.md) for information on:
|
||||
We welcome contributions! Please see our [Development Guide](development.md) for information on:
|
||||
|
||||
- Setting up your development environment
|
||||
- Understanding the codebase
|
||||
|
||||
@@ -510,9 +510,9 @@ DEBUG=true
|
||||
|
||||
## 📚 Additional Resources
|
||||
|
||||
- [AGENTS.md](../../AGENTS.md) - Agent/development rules
|
||||
- [API Reference](../API_REFERENCE.md) - Complete API documentation
|
||||
- [Troubleshooting](../TROUBLESHOOTING.md) - Deployment issues
|
||||
- [Development rules and standards](contributing.md) - Contributing portal
|
||||
- [API Reference](../developer/api/api-reference.md) - Split endpoint docs, indexed from its overview
|
||||
- [Troubleshooting](../operations/troubleshooting.md) - Deployment issues
|
||||
- [Go Documentation](https://go.dev/doc/)
|
||||
- [Echo Framework](https://echo.labstack.com/docs)
|
||||
- [pgx Documentation](https://pgx.github.io/pgx/)
|
||||
|
||||
@@ -623,6 +623,6 @@ This is a great example of how user feedback can improve implementation design!
|
||||
|
||||
## See Also
|
||||
|
||||
- [User Guide: Calibre Integration](../../user/calibre-integration.md)
|
||||
- [Implementation Plan](../../CALIBRE_OPF_IMPLEMENTATION.md)
|
||||
- [Scanner Source Code](../../internal/services/media_scanner.go)
|
||||
- [User Guide: Calibre Integration](../user/calibre-integration.md)
|
||||
- The original implementation plan file was removed from the repo when this page absorbed its content.
|
||||
- The scanner implementation lives in `internal/services/` (not hyperlinked — the docs site serves only docs).
|
||||
+40
-81
@@ -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)
|
||||
@@ -15,19 +15,19 @@ Welcome to the Bookhoard operations documentation. This section contains guides
|
||||
|
||||
### Additional Deployment Guides
|
||||
|
||||
**[Deployment Guide](deployment.md)** - Comprehensive deployment guide
|
||||
**Deployment Guide** - Comprehensive deployment guide
|
||||
|
||||
- _Coming Soon_
|
||||
|
||||
## 🛠️ Maintenance
|
||||
|
||||
**[Maintenance Guide](maintenance.md)** - Ongoing operations and maintenance
|
||||
**Maintenance Guide** - Ongoing operations and maintenance
|
||||
|
||||
- _Coming Soon_
|
||||
|
||||
## 📊 Monitoring
|
||||
|
||||
**[Monitoring Guide](monitoring.md)** - Monitoring and alerting
|
||||
**Monitoring Guide** - Monitoring and alerting
|
||||
|
||||
- _Coming Soon_
|
||||
|
||||
|
||||
@@ -13,4 +13,4 @@ This guide will cover:
|
||||
|
||||
---
|
||||
|
||||
_In the meantime, check out our [Operations Portal](../operations/)_
|
||||
_In the meantime, check out our [Operations Portal](../operations/operations.md)_
|
||||
@@ -34,7 +34,7 @@ A: Nothing — KOReader will keep working. Native sync simply adds another optio
|
||||
|
||||
- [KOReader Setup Guide](koreader-setup.md) — works on Kobo today
|
||||
- [Bookhoard Universal Sync Guide](../sync-guide.md)
|
||||
- [Bookhoard API Reference](../../developer/api-reference.md)
|
||||
- Kobo sync protocol (for developers): [Kobo API docs](../../developer/api/kobo/sync_from_server.md)
|
||||
|
||||
---
|
||||
|
||||
|
||||
@@ -13,4 +13,4 @@ This guide will cover:
|
||||
|
||||
---
|
||||
|
||||
_In the meantime, check out our [Device Setup Guides](devices/)_
|
||||
_In the meantime, check out our [Device Setup Guides](devices/android-app.md) and [KOReader setup](devices/koreader-setup.md)_
|
||||
@@ -12,4 +12,4 @@ This guide will cover:
|
||||
|
||||
---
|
||||
|
||||
_In the meantime, check out our [Device Setup Guides](devices/)_
|
||||
_In the meantime, check out our [Device Setup Guides](devices/android-app.md) and [KOReader setup](devices/koreader-setup.md)_
|
||||
+29
-14
@@ -8,40 +8,55 @@ import (
|
||||
"testing"
|
||||
)
|
||||
|
||||
// TestDocsRelativeLinks keeps the developer docs tree internally navigable:
|
||||
// every relative markdown link must point at a file that exists. The
|
||||
// api-reference overview once shipped 20+ directory-style links
|
||||
// (authentication/ etc.) that 404'd — this gate makes that class of rot
|
||||
// fail make test. (docs/user is excluded: end-user prose has its own pass.)
|
||||
// TestDocsRelativeLinks keeps every doc tree internally navigable: every
|
||||
// relative markdown link must point at a file that exists. The api-reference
|
||||
// overview once shipped 20+ directory-style links (authentication/ etc.)
|
||||
// that 404'd — this gate makes that class of rot fail make test.
|
||||
//
|
||||
// Rules:
|
||||
// - http(s):, mailto:, and pure #anchors are skipped
|
||||
// - every other target must end in .md and resolve (relative to the
|
||||
// linking file) to an existing file inside the tree
|
||||
// linking file) to an existing file inside the docs tree
|
||||
// - directory-style targets ("area/") are the exact bug this test exists
|
||||
// for and always fail
|
||||
//
|
||||
// Hands-off sources (project owner instruction, 2026-11-02: DO NOT EDIT THE
|
||||
// FILTER DOCS): docs/user/filters/** and docs/user/searching-and-filtering.md
|
||||
// are not scanned as link sources, so no future gate failure can force an
|
||||
// edit there. Files linking INTO them are still checked — resolution needs
|
||||
// file existence only, never edits to their content.
|
||||
|
||||
var docsLinkRe = regexp.MustCompile(`\[[^\]]*\]\(([^)\s]+)\)`)
|
||||
|
||||
var handsOffFilterDocs = []string{
|
||||
"user/filters/",
|
||||
"user/searching-and-filtering.md",
|
||||
}
|
||||
|
||||
func TestDocsRelativeLinks(t *testing.T) {
|
||||
// Walk developer docs; escape-check against the whole docs tree —
|
||||
// cross-area links into docs/user are legitimate (same site).
|
||||
devRoot, err := filepath.Abs("../../docs/developer")
|
||||
if err != nil {
|
||||
t.Fatalf("abs developer root: %v", err)
|
||||
}
|
||||
treeRoot, err := filepath.Abs("../../docs")
|
||||
if err != nil {
|
||||
t.Fatalf("abs docs root: %v", err)
|
||||
}
|
||||
err = filepath.WalkDir(devRoot, func(path string, d os.DirEntry, err error) error {
|
||||
err = filepath.WalkDir(treeRoot, func(path string, d os.DirEntry, err error) error {
|
||||
if err != nil || d.IsDir() || !strings.HasSuffix(path, ".md") {
|
||||
return err
|
||||
}
|
||||
rel, err := filepath.Rel(treeRoot, path)
|
||||
if err != nil {
|
||||
return err
|
||||
}
|
||||
relSlash := filepath.ToSlash(rel)
|
||||
for _, off := range handsOffFilterDocs {
|
||||
if strings.HasPrefix(relSlash, off) {
|
||||
return nil
|
||||
}
|
||||
}
|
||||
|
||||
raw, err := os.ReadFile(path)
|
||||
if err != nil {
|
||||
return err
|
||||
}
|
||||
rel, _ := filepath.Rel(docsRoot, path)
|
||||
absPath, err := filepath.Abs(path)
|
||||
if err != nil {
|
||||
return err
|
||||
|
||||
Reference in new issue
Block a user