From 35a039d720b29aecfed0b5c30d19bfe01961f4b8 Mon Sep 17 00:00:00 2001 From: John O'Keefe Date: Mon, 2 Feb 2026 20:25:18 -0500 Subject: [PATCH] docs: rename INDEX files to meaningful names and fix navigation MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - Renamed subdirectory INDEX.md files to section-specific names: - user/INDEX.md → user/user-guide.md - developer/INDEX.md → developer/development.md - operations/INDEX.md → operations/operations.md - contributing/INDEX.md → contributing/contributing.md - developer/api/INDEX.md → developer/api/api-reference.md - developer/api/collections/INDEX.md → developer/api/collections/collections-api.md - Updated all internal links to use new filenames - Updated navigation.go to skip subdirectory INDEX files from sidebar - Added Dockerfile to include docs directory in container build This fixes the issue where multiple 'INDEX' links appeared in the sidebar, making navigation confusing. Now each section has a descriptive name. --- Dockerfile | 3 +++ docs/INDEX.md | 16 ++++++++-------- .../contributing/{INDEX.md => contributing.md} | 0 .../api/{INDEX.md => api-reference.md} | 0 .../{INDEX.md => collections-api.md} | 0 docs/developer/{INDEX.md => development.md} | 0 docs/operations/{INDEX.md => operations.md} | 0 docs/user/{INDEX.md => user-guide.md} | 0 internal/docs/navigation.go | 18 +++++++++++++++++- 9 files changed, 28 insertions(+), 9 deletions(-) rename docs/contributing/{INDEX.md => contributing.md} (100%) rename docs/developer/api/{INDEX.md => api-reference.md} (100%) rename docs/developer/api/collections/{INDEX.md => collections-api.md} (100%) rename docs/developer/{INDEX.md => development.md} (100%) rename docs/operations/{INDEX.md => operations.md} (100%) rename docs/user/{INDEX.md => user-guide.md} (100%) diff --git a/Dockerfile b/Dockerfile index 163d8dd..c588c97 100644 --- a/Dockerfile +++ b/Dockerfile @@ -61,6 +61,9 @@ COPY --from=builder /app/templates ./templates # Copy web assets (HTML, CSS, JS, etc.) COPY --from=builder /app/web ./web +# Copy documentation +COPY --from=builder /app/docs ./docs + # Expose port EXPOSE 8765 diff --git a/docs/INDEX.md b/docs/INDEX.md index 6ca5b8f..7d10383 100644 --- a/docs/INDEX.md +++ b/docs/INDEX.md @@ -8,7 +8,7 @@ Complete guide to Bookhoard documentation. Find what you need quickly. ### 👤 For End Users -**[User Documentation Portal](user/INDEX.md)** - Guides for using Bookhoard features +**[User Documentation Portal](user/user-guide.md)** - Guides for using Bookhoard features - **Device Setup** - [Kobo Setup Guide](user/devices/kobo-setup.md) - Complete Kobo e-reader configuration @@ -25,11 +25,11 @@ Complete guide to Bookhoard documentation. Find what you need quickly. ### 👨‍💻 For Developers -**[Developer Documentation Portal](developer/INDEX.md)** - Technical documentation & API reference +**[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/INDEX.md) - Individual endpoints with interactive API Explorer + - [Split Endpoint Docs](developer/api/api-reference.md) - Individual endpoints with interactive API Explorer - [Collections API](developer/collections-api.md) - Collections management API - **Protocol Specifications** @@ -39,7 +39,7 @@ Complete guide to Bookhoard documentation. Find what you need quickly. ### 🔧 For Operations -**[Operations Documentation Portal](operations/INDEX.md)** - Deployment & maintenance +**[Operations Documentation Portal](operations/operations.md)** - Deployment & maintenance - **Deployment** - [Troubleshooting Guide](operations/troubleshooting.md) - Common deployment issues and solutions @@ -51,7 +51,7 @@ Complete guide to Bookhoard documentation. Find what you need quickly. ### 🤝 For Contributors -**[Contributing Portal](contributing/INDEX.md)** - Development workflow +**[Contributing Portal](contributing/contributing.md)** - Development workflow - [Development Guide](contributing/DEVELOPMENT.md) - Architecture, setup, testing - [PROJECT_GUIDELINES.md](PROJECT_GUIDELINES.md) - Development rules and standards @@ -63,8 +63,8 @@ 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 | -| **Set up a device** | [User Portal → Device Setup](user/INDEX.md) | -| **Use the API** | [Developer Portal → API Docs](developer/INDEX.md) | +| **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) | | **Understand sync** | [User Portal → Sync Guide](user/sync-guide.md) | @@ -127,7 +127,7 @@ 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/INDEX.md) +4. **Deployment changes** → Update [Operations Portal](operations/operations.md) Keep [PROJECT_GUIDELINES.md](PROJECT_GUIDELINES.md) in mind for documentation standards. diff --git a/docs/contributing/INDEX.md b/docs/contributing/contributing.md similarity index 100% rename from docs/contributing/INDEX.md rename to docs/contributing/contributing.md diff --git a/docs/developer/api/INDEX.md b/docs/developer/api/api-reference.md similarity index 100% rename from docs/developer/api/INDEX.md rename to docs/developer/api/api-reference.md diff --git a/docs/developer/api/collections/INDEX.md b/docs/developer/api/collections/collections-api.md similarity index 100% rename from docs/developer/api/collections/INDEX.md rename to docs/developer/api/collections/collections-api.md diff --git a/docs/developer/INDEX.md b/docs/developer/development.md similarity index 100% rename from docs/developer/INDEX.md rename to docs/developer/development.md diff --git a/docs/operations/INDEX.md b/docs/operations/operations.md similarity index 100% rename from docs/operations/INDEX.md rename to docs/operations/operations.md diff --git a/docs/user/INDEX.md b/docs/user/user-guide.md similarity index 100% rename from docs/user/INDEX.md rename to docs/user/user-guide.md diff --git a/internal/docs/navigation.go b/internal/docs/navigation.go index b180245..3de5f3b 100644 --- a/internal/docs/navigation.go +++ b/internal/docs/navigation.go @@ -28,6 +28,12 @@ func (h *DocsHandler) BuildNavigation() *templates.Navigation { categories := make(map[string][]templates.NavItem) for _, doc := range docs { + // Skip INDEX.md files in subdirectories (they're section landing pages, not nav items) + // Only show root INDEX.md, skip all others like user/INDEX.md, api/INDEX.md, etc. + if strings.HasSuffix(doc, "INDEX.md") && doc != "INDEX.md" { + continue + } + item := h.createNavItem(doc) category := h.getCategoryForNav(doc) categories[category] = append(categories[category], item) @@ -100,9 +106,19 @@ func (h *DocsHandler) getDocTitle(docPath string) string { switch filename { case "INDEX.md": return "Documentation Index" + case "user/user-guide.md": + return "User Guide" + case "developer/development.md": + return "Developer Portal" + case "operations/operations.md": + return "Operations Guide" + case "contributing/contributing.md": + return "Contributing" case "developer/api-reference.md": return "API Reference" - case "developer/collections-api.md": + case "developer/api/api-reference.md": + return "API Reference" + case "developer/api/collections-api.md": return "Collections API" case "developer/websocket-api.md": return "WebSocket API"