Sidebar Navigation

Relevant source files

The following files were used as context for generating this wiki page:

• src/data/sidebar.ts
• src/components/Sidebar.tsx
• src/components/SidebarItem.tsx
• src/types.ts
• src/layouts/DocsLayout.tsx
• src/components/Nav.tsx

The Sidebar Navigation system is a core feature of the documentation site, providing users with a structured and interactive way to browse content. It is a data-driven system that dynamically generates navigation links based on a centralized configuration. The sidebar is responsive, offering a persistent view on desktop (Sidebar) and a collapsible, on-demand menu on mobile devices (MobileSidebar). Its primary function is to render documentation sections, subsections, and individual page links, while also highlighting the user's current location within the site structure.

Architecture and Components

The sidebar's architecture is composed of a data source, several React components for rendering, and type definitions that enforce the data structure.

Component Overview

The following table describes the key React components that constitute the sidebar system.

Component	File	Description
Sidebar	src/components/Sidebar.tsx	The main container for the desktop sidebar. It is a sticky, full-height navigation panel.
SidebarContent	src/components/Sidebar.tsx	Renders the actual list of navigation items. It manages the state for expanded subsections and the active link. This component is shared between desktop and mobile sidebars.
SidebarItem	src/components/SidebarItem.tsx	A versatile component responsible for rendering one of three types of items: a direct page link, an external link, or a collapsible subsection containing more links.
MobileSidebar	src/components/Sidebar.tsx	A wrapper for SidebarContent that is displayed on smaller screens and toggled by the MobileNav component.
MobileNav	src/components/Nav.tsx	The top navigation bar for mobile, which contains the hamburger menu button to toggle the MobileSidebar.

Sources: src/components/Sidebar.tsx, src/components/SidebarItem.tsx, src/components/Nav.tsx

Component Hierarchy

This diagram illustrates how the sidebar components are structured.

Data Structure

The navigation structure is defined by a set of interfaces and a central data array. This approach decouples the navigation content from the rendering logic, making it easy to update.

Sources: src/types.ts, src/data/sidebar.ts

Data Model

The data model for the sidebar content is defined in src/types.ts. It consists of sections, which can contain pages, external links, or nested subsections.

// src/types.ts:5-23
export type ISidebarContent = ISidebarSection[];

export interface IPage {
  title: string;
  slug: string;
  description?: string;
  category?: string;
}

export interface IExternalLink {
  title: string;
  url: string;
}

export interface ISidebarSection {
  title?: string;
  content: (IPage | ISubSection | IExternalLink)[];
}

export interface ISubSection {
  subTitle: string | IPage;
  pages: (IPage | IExternalLink)[];
}

Sources: src/types.ts:5-23

The relationships between these data entities can be visualized as follows:

Data Source

The sidebarContent array, exported from src/data/sidebar.ts, is the single source of truth for the navigation menu. It is an array of ISidebarSection objects. A helper function makePage is used to create IPage objects with consistent slug generation.

An example of a section with a nested subsection:

// src/data/sidebar.ts:31-48
{
  title: "Guides",
  content: [
    {
      subTitle: makePage("Foundations", "guides"),
      pages: [
        makePage("Projects", "guides"),
        makePage("Staged Changes", "guides"),
        makePage("Services", "guides"),
        makePage("Variables", "guides"),
        makePage("Volumes", "guides"),
        makePage("Environments", "guides"),
        makePage("CLI", "guides"),
        makePage("Join Priority Boarding!", "guides"),
      ],
    },
    // ... more content
  ],
},

Sources: src/data/sidebar.ts:31-48

Rendering and State Management

The SidebarContent component orchestrates the rendering and manages the interactive state of the sidebar.

Sources: src/components/Sidebar.tsx

Rendering Flow

The rendering process begins in SidebarContent, which iterates over the sidebarContent data and uses the SidebarItem component to render each entry.

Active State and Highlighting

The component uses the useRouter hook to get the current page's slug. The isCurrentPage function compares this slug against the slugs of sidebar items to determine which link is active.

• An active IPage link receives a current class, which applies styling to highlight it (e.g., pink background and a right border).
• The isCurrentSection function determines if any page within a top-level section is active, applying a current-section class to the section title.

Sources: src/components/Sidebar.tsx:43-50, src/components/Sidebar.tsx:125-126, src/components/SidebarItem.tsx:83-93

Collapsible Subsections

Subsections are interactive elements that can be expanded or collapsed by the user.

• State: The SidebarContent component maintains an expandedSubSections array in its state to track which subsections are open.
• Toggling: The toggleSubSection function adds or removes a subsection's slug from this state array. This function is passed down to SidebarItem.
• Auto-Expansion: A useEffect hook runs on route changes to find the subsection containing the current page and automatically adds its slug to the expandedSubSections state, ensuring the relevant section is open on page load.
• Rendering: The SidebarItem component conditionally renders the list of pages within a subsection only if its slug is present in the isExpanded prop (which comes from the expandedSubSections state).

This diagram shows the state transitions for a subsection.

Automatic Scrolling

To improve user experience, the sidebar automatically scrolls the active navigation link into view.

1. An activeLinkRef is created in SidebarContent.
2. This ref is passed down to the SidebarItem that corresponds to the current active page.
3. A useEffect hook in SidebarContent watches for changes to the page slug and, if the activeLinkRef is attached to an element, calls scrollIntoView to ensure it is visible.

Sources: src/components/Sidebar.tsx:53, src/components/Sidebar.tsx:65-71, src/components/SidebarItem.tsx:85

Related Utilities

flattenSidebarContent

The DocsLayout component uses a utility function flattenSidebarContent to create a flat array of all IPage objects from the nested sidebarContent structure. This flattened list is used to easily determine the "Next" and "Previous" pages for the bottom-of-page navigation links.

Summary

The Sidebar Navigation is a robust and maintainable system built with React and TypeScript. By defining its structure in a single data file (sidebar.ts), it separates content from presentation, allowing for easy updates. The component-based architecture (Sidebar, SidebarItem) combined with React hooks for state management (useState, useEffect) provides a responsive, interactive, and user-friendly navigation experience, complete with active state highlighting, collapsible sections, and automatic scrolling.