Orientation
Content Processing
Search Infrastructure
Rendering and UI
Developer Tooling
How It Works
The following files were used as context for generating this wiki page:
Sidebar navigation is a foundational subsystem that provides structural document hierarchy visualization and site navigation. It serves as the primary way for users to traverse complex documentation content, bridging the gap between raw data structures (like page trees) and a functional UI. By decoupling data rendering (the tree) from structural UI concerns (collapsible folders, drawers, scroll tracking), the system enables developers to inject layout-specific components while maintaining consistent navigation logic.
The design embodies a clear separation between the logic of "being a sidebar"—handling provider state, media queries, and keyboard navigation—and the specific layout representation, such as the notebook layout, which supports desktop collapsing and mobile drawers. This hierarchy ensures that logic like useFolderDepth or useSidebar remains stable across different UI variations while allowing specific slots to render custom elements like tabs, footers, or banners.
Interaction with adjacent components is primarily driven by context providers (SidebarProvider) that manage shared state such as open/collapsed status and navigation hooks. The system also tightly integrates with document loading infrastructure, ensuring that the navigation automatically reflects the site's directory structure via the page-tree loader.
The sidebar subsystem is built as a set of decoupled functional components centered around SidebarProvider. The provider acts as the state arbiter for the entire navigation tree, managing whether the sidebar is in drawer or full mode based on media queries, and holding a ref to closeOnRedirect to prevent premature closure during site navigation.
The subsystem uses React Context to share state across deeply nested nodes (like folder triggers or individual links). The state is split into SidebarContext and FolderContext.
SidebarContext: Manages the global sidebar lifecycle (drawer vs. full mode, global collapse status).FolderContext: Tracks hierarchical concerns for collapsible items, including depth and trigger status.Note
The useSidebar hook provides closeOnRedirect, a RefObject allowing components to inhibit the standard sidebar closure behavior during a page transition. Setting closeOnRedirect.current = false inside an click handler effectively disables the automatic cleanup logic defined in the SidebarProvider.
The sidebar displays content by rendering a page tree, which is generated via createPageTreeRenderer. This function creates a bridge between the raw data object and the UI components provided to it.
SidebarFolder, SidebarItem, etc.) is passed to createPageTreeRenderer.folder, page, separator), it fetches the corresponding UI component from the context.renderList call to process their children, maintaining a running depth tally via useFolderDepth.Tip
The system allows overriding the UI for specific tree node types by passing components (e.g., Folder, Item, Separator) directly into the sidebar props, allowing for rich customization while reusing the built-in tree traversal logic.
The component determines its display strategy using useMediaQuery. This logic is encapsulated within SidebarProvider, ensuring that the rest of the application remains agnostic to the current view mode (drawer on mobile, fixed/full-width on desktop).
The useAutoScroll hook is vital for navigation UX: when a sidebar item becomes active, it ensures that the item is scrolled into view within the SidebarViewport.
export function useAutoScroll(active: boolean, ref: RefObject<HTMLElement | null>) {
const { mode } = useSidebar();
useEffect(() => {
if (active && ref.current) {
scrollIntoView(ref.current, {
boundary: document.getElementById(mode === 'drawer' ? 'nd-sidebar-mobile' : 'nd-sidebar'),
scrollMode: 'if-needed',
});
}
}, [active, mode, ref]);
}This ensures that regardless of whether the user is in a drawer or full-width view, the navigation tree automatically highlights and centers the user's current location.