Issue/330

[rudy128]

📌 Fixes

Fixes #330 - Add mobile navigation menu and table of contents for responsive documentation experience
Fixes 3578

---

📝 Summary of Changes

This PR implements a complete mobile navigation solution for the KubeStellar documentation site, addressing the lack of navigation on mobile devices (< 768px) and improving the overall responsive experience.

Key Features Added:

• Mobile Navigation Menu - Slide-out sidebar menu with full navigation structure
• Mobile Table of Contents - Collapsible TOC component for easy page navigation on mobile/tablet
• Shared Search System - Centralized search hook with Context API for consistent search experience
• Direct Route Highlighting - Sidebar highlighting and folder expansion for /docs/direct/* URLs

---

Changes Made

🎯 Mobile Navigation Menu

• Created DocsMobileMenu.tsx - Custom mobile sidebar menu component

  • Renders full pageMap navigation structure
  • Supports nested folders with expand/collapse functionality
  • Active page highlighting with Nextra theme colors
  • Dark mode support
  • Search integration (opens shared search dialog)
  • Positioned below navbar using CSS variables (--nextra-navbar-height, --nextra-banner-height)

• Created MobileMenuWrapper.tsx - Client-side wrapper component

  • Manages menu show/hide state
  • Displays trigger button with hamburger icon and page title
  • Smart title mapping (e.g., "readme" → "Overview", "/docs" → "Welcome")
  • Integrates with shared search hook

• Updated [...slug]/page.tsx

  • MobileMenuWrapper rendered outside Nextra Wrapper for proper viewport positioning
  • Passes pageMap and title props

• Updated page.mdx (root docs page)

  • Added MobileMenuWrapper with pageMap integration
  • Ensures mobile menu works on landing page

📱 Mobile Table of Contents

• Created MobileTOC.tsx - Collapsible TOC component for mobile/tablet

  • Displays "On this page" heading with expand/collapse toggle
  • Only visible below xl breakpoint (< 1280px)
  • Smooth scrolling to headings
  • Auto-closes after navigation
  • Sticky positioning with proper z-index
  • Dark mode support with theme-aware colors
  • Indented heading levels (H2, H3, H4)

• Integrated into page layout

  • Positioned inside Nextra Wrapper component
  • Appears at top of content area on mobile/tablet
  • Hidden on desktop where floating sidebar TOC is used

🔍 Search System Refactoring

• Created useSearch.tsx hook with Context Provider

  • Centralized search state management
  • Keyboard shortcuts (Cmd/Ctrl+K, Escape, Arrow navigation)
  • Debounced search API calls (300ms)
  • Smooth result navigation
  • Single source of truth for search across all components

• Refactored DocsNavbar.tsx to use shared search hook

  • Removed duplicate search state and handlers
  • Cleaner implementation with hook
  • Maintains all existing functionality

• Updated layout.tsx

  • Wrapped app with SearchProvider for global state sharing

🎨 Direct Route Support Enhancement

• Maintained DirectRouteHighlighter.tsx functionality
  • Client-side sidebar highlighting for /docs/direct/* URLs
  • Auto-expands parent folders for direct links
  • Uses exact Nextra theme classes for consistency

🧹 Code Quality

• Removed debug console.logs from production code
• Proper TypeScript typing throughout
• Followed project coding standards
• Component documentation with JSDoc comments

---

Technical Implementation Details

Z-Index Hierarchy

- Navbar dropdowns & search: z-50
- Navbar container: z-20
- Mobile menu: z-60 (above navbar, intentionally for overlay)
- Mobile TOC: z-20 (within content flow)

Responsive Breakpoints

• Mobile menu trigger: Visible < 768px (md breakpoint)
• Mobile menu sheet: Hidden ≥ 1024px (lg breakpoint)
• Mobile TOC: Visible < 1280px (xl breakpoint)
• Desktop sidebar TOC: Visible ≥ 1280px

Component Architecture

SearchProvider (Context)
  └─ Layout
      ├─ Banner
      ├─ Navbar (uses useSearch)
      └─ Content
          ├─ MobileMenuWrapper (uses useSearch)
          │   └─ DocsMobileMenu
          ├─ Sidebar (desktop)
          └─ Main Content
              ├─ MobileTOC (mobile/tablet)
              └─ MDX Content

---

Checklist

Please ensure the following before submitting your PR:

• I have reviewed the project's contribution guidelines.
• I have written unit tests for the changes (N/A - UI components).
• I have updated the documentation (N/A - documentation site itself).
• I have tested the changes locally and ensured they work as expected.
• My code follows the project's coding standards.
• All TypeScript errors resolved.
• Dark mode support verified.
• Responsive behavior tested across breakpoints.

---

Screenshots or Logs (if applicable)

Mobile Navigation Menu

• Hamburger menu trigger button with page title
• Slide-out navigation with full pageMap structure
• Search integration opens shared dialog
• Active page highlighting

Mobile Table of Contents

• Collapsible "On this page" component
• Sticky positioning at top of content
• Smooth scrolling to headings
• Auto-collapse after navigation

Search Integration

• Unified search experience across navbar and mobile menu
• Keyboard shortcuts work globally
• Results displayed in command palette style

---

👀 Reviewer Notes

Testing Recommendations:

1. Test mobile menu on various screen sizes (< 768px)
2. Verify TOC appears correctly between 768px - 1280px
3. Test search from both navbar and mobile menu
4. Verify direct routes (/docs/direct/*) highlight correctly
5. Test dark mode across all new components
6. Check z-index stacking with navbar dropdowns

Key Files to Review:

• src/components/docs/DocsMobileMenu.tsx - Main mobile menu logic
• src/components/docs/MobileTOC.tsx - Mobile TOC component
• src/hooks/useSearch.tsx - Shared search hook with Context
• src/app/docs/layout.tsx - SearchProvider integration

Known Considerations:

• Mobile menu z-index is intentionally z-60 (above navbar z-20) to create modal overlay effect
• CSS variables used for dynamic positioning: --nextra-navbar-height, --nextra-banner-height
• PageMap structure from buildPageMapForBranch() required for navigation rendering

Impact:
This PR significantly improves the mobile UX of the KubeStellar documentation site by:

• Providing full navigation access on mobile devices
• Making long pages easier to navigate with collapsible TOC
• Unifying search experience across all screen sizes
• Maintaining consistency with desktop experience

[netlify]

✅ Deploy Preview for kubestellar-docs ready!

Built without sensitive environment variables

Name	Link
🔨 Latest commit	2d644b8
🔍 Latest deploy log	https://app.netlify.com/projects/kubestellar-docs/deploys/6953d71861d2b100082340a9
😎 Deploy Preview	https://deploy-preview-467--kubestellar-docs.netlify.app
📱 Preview on mobile	Toggle QR Code... Use your smartphone camera to open QR code link.

---

To edit notification comments on pull requests, go to your Netlify project configuration.

[rudy128]

Hello @naman9271,

I have tried to inject the TOC and MobileMenuBar in the Nextra Mdx wrapper and I have also tried to replicate that but I was running into alot of errors. The example you gave me (Asyncapi), they use custom mdx wrapper implementation.

Right now as it is, it's not good enough and that implementation will take me a little bit more time as I am already trying to implement it.

Please let me know if you want that implementation or if you have some other suggestion on this.

[naman9271]

@rudy128 screenshots looking good you are on right track let me know when you are finished and also share screen recording at the end

[naman9271]

@rudy128 could you please make the further changes after taking the pull as we have consolidated the docs into this repo compeltely from ks/ks