Skip to main content

Feature Request: Docusaurus Navigation — Sidebar IA and Landing Page

Type: Feature Request (FR)
ID: FR-068
Submitted: 2026-03-30
Submitted By: User (via agent)
Priority: MEDIUM
Status: ACCEPTED
Assigned Task: E5:S09:T04 — T04-docusaurus-navigation-fr-068.md

Summary​

Replace autogenerated-only navigation with an information architecture aligned to the canonical KB pillars (architecture, changelog/release notes, project-management, guides, documentation, knowledge), implemented in portal/sidebars.js (and _category_.json where helpful). Replace the template homepage with an AI Dev Kit–specific landing that orients visitors to major doc areas—without changing doc source locations (those are FR-066).

Problem Statement​

Even with a green build, a flat or auto-generated sidebar is hard to navigate for a large KB. The default Docusaurus homepage sells the framework, not the dev kit.

Scope (Atomic)​

In scope

  • portal/sidebars.js: explicit sections (or hybrid autogen per top-level folder) matching pillars named in ultimate-canonical-kb-structure.md.
  • portal/src/pages/index.js (and related styles/components): new hero, feature blocks, or links to key /docs/... sections.
  • Remove or archive tutorial-only nav items that duplicate “Getting Started” if they confuse the ADK story (optional within this FR if already isolated in portal/docs).

Out of scope

  • New written tutorial content (large guides); only wayfinding.
  • Search (FR-071).
  • CI/deploy (FR-069–FR-070).

Functional Requirements​

  • FR-068:R01 – Sidebar top-level group labels map to named pillars (mapping table in portal/README.md — E5:S09:T04 / S1–S2).
  • FR-068:R02 – Homepage lists primary entry points (portal index, versioning policy, framework adoption guide, Kanban governance) as links to built routes — S3.
  • FR-068:R03 – No dead sidebar entries (valid autogen dirName paths under docs/) — S5.
  • FR-068:R04 – npm run build remains green after IA changes — S6 / PORTAL_BUILD_STRICT.

Non-Functional Requirements​

  • FR-068:NF01 – Maintainability: Comment in sidebars.js explains ordering philosophy (canonical pillars first, then extension folders) — S1.
  • FR-068:NF02 – Accessible: Landing page keeps semantic headings and sensible link text — S4.

Acceptance Criteria​

  • AC1: Reviewer can reach each pillar’s docs within two clicks from home or sidebar root — S7 surrogate + manual spot-check.
  • AC2: Homepage does not present “Docusaurus Tutorial” as primary CTA — S3.
  • AC3: Build passes — S6.

Dependencies / Ordering​

  • FR-067 recommended (stable routes and build); FR-065 for correct site title/branding on landing.
  • FR-066 – Docs root and scope.
  • FR-071 – Search complements navigation.

References​

  • docs/architecture/standards-and-adrs/ultimate-canonical-kb-structure.md
  • portal/sidebars.js, portal/src/pages/index.js