docs(nav): Administration section lives in docs/admin/; sidebar ordered by usability

Two structural changes, one owner-approved plan:

- Move the admin guides out of docs/user/ into their own docs/admin/
  area — admin-guide.md becomes the Administration section landing page
  (pinned first), and the 32-line admin-library-management.md stub
  becomes admin/libraries.md, which the admin-docs build-out rebuilds
  into the real Libraries page next. Retired URLs 301 via a new
  docRedirects map in the docs HTTP handler (checked before .md
  canonicalization so even .md spellings one-hop to the new clean URL);
  the two inbound links (docs index, user-guide front door) updated.

- Sidebar direct items now sort by usabilityOrder — an explicit,
  per-section display order — instead of alphabetically: User Guide
  mirrors the 'Where to go' table on user-guide.md, Devices orders
  Android → KOReader → Kobo (alphabetically Kobo used to sort ahead of
  KOReader), and Administration pre-lists its planned pages so each
  lands in place as the admin build writes it. Unlisted docs fall back
  to alphabetical after the listed ones. Display-order only by
  construction: the URL-driven expand/highlight machinery keys on
  containsURL membership and never sees sort order — nav tests updated
  to pin the new orders plus a real-tree test
  (TestBuildNavigationUsabilityOrder) guarding all three sections.
This commit is contained in:
John O'Keefe committed 2026-11-02 13:38:01 -05:00
1 parent 7e2e1c4c60
commit 393a00e8dd
7 files changed
+152 -15

No files matched your search

+23
View File
@@ -18,6 +18,19 @@ type HTTPHandler struct {
docs *DocsHandler
}
// docRedirects maps retired doc paths (as passed to ShowDocumentation —
// no leading /docs, .md suffix optional) to their current paths. Docs move
// rarely; when one moves, add it here so old links 301 to the new home
// instead of 404ing. Checked BEFORE .md canonicalization so a moved page's
// .md spelling also one-hops straight to the new clean URL.
// 2026-11-02: admin guides moved from docs/user/ to docs/admin/, and
// admin-library-management.md became admin/libraries.md (it will be
// rebuilt as the Libraries page).
var docRedirects = map[string]string{
"user/admin-guide": "admin/admin-guide",
"user/admin-library-management": "admin/libraries",
}
// NewHTTPHandler creates a new docs HTTP handler
func NewHTTPHandler(docsPath string) *HTTPHandler {
return &HTTPHandler{
@@ -76,6 +89,16 @@ func (h *HTTPHandler) ShowDocumentation(c *echo.Context) error {
// Get the document path from URL parameter
docPath := c.Param("*")
// Retired doc paths 301 to their current homes (see docRedirects)
// before any load attempt.
if target, moved := docRedirects[strings.TrimSuffix(docPath, ".md")]; moved {
loc := "/docs/" + target
if c.Request().URL.RawQuery != "" {
loc += "?" + c.Request().URL.RawQuery
}
return c.Redirect(http.StatusMovedPermanently, loc)
}
// Canonicalize ".md" URLs to the clean form. Markdown links across the
// docs tree point at `area/file.md`; the handler loads them fine, but
// the sidebar logic keys on the URL path (contains-URL expansion, the