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:
The Layout System provides a standardized, compositional framework for structuring documentation sites. It addresses the common challenge of fragmented UI components by offering unified primitives for sidebars, headers, and content areas, ensuring consistent navigation and layout behavior across different documentation styles (Notebook and Flux).
At its core, the system utilizes a hierarchical layout strategy driven by shared context providers. These providers encapsulate cross-cutting concerns like navigation states, theme switching, and language selection, allowing individual layout components to remain decoupled from the specific configuration of the host application.
By separating the "slots" (extensible areas of the UI) from the underlying implementation logic, the system allows for modular customization. Whether using the sophisticated "Notebook" style—focused on hierarchical content trees—or the more modern, interactive "Flux" style, developers interact with a predictable interface to inject custom branding, toolsets, and page content.
The Sidebar subsystem acts as the primary navigation engine. It is built upon a SidebarProvider that manages open/collapsed states and responsive transitions (drawer vs. full mode). The sidebar logic is defined in packages/base-ui/src/components/sidebar/base.tsx, which serves as the foundation for both Notebook and Radix-UI layout variants.
The system uses a FolderContext to track hierarchy depth and collapsible states recursively. This ensures that tree-based navigation correctly handles indentation and trigger behavior.
Sources: packages/base-ui/src/components/sidebar/base.tsx:75-112, packages/base-ui/src/components/sidebar/base.tsx:298-305
Tip
The sidebar uses a timerRef in SidebarContent to handle hover states on collapsed sidebars. If the mouse leaves the viewport, it triggers a 500ms delay before closing, improving usability on desktop.
The Notebook layout implementation defines a rigid grid structure to manage the documentation lifecycle. It relies on LayoutBody (in client.tsx) to initialize the LayoutContext, which bundles navigational items, header/sidebar slots, and scroll-transparency logic.
The grid layout is computed dynamically in the Container component:
pageCol based on layout width and sidebar/TOC column widths.sidebar, header, main, and toc.--fd-sidebar-col, etc.) that control the layout responsiveness.Sources: packages/base-ui/src/layouts/notebook/client.tsx:67-124, packages/base-ui/src/layouts/notebook/slots/container.tsx:24-54
Link items are the building blocks of navigation. They are resolved via resolveLinkItems in packages/base-ui/src/layouts/shared/index.tsx. The system supports multiple types, filtering them by their on property ('menu', 'nav', 'all') to ensure they appear only where intended.
The Notebook layout includes a transparency feature for navigation, enabled by the transparentMode option ('top', 'always', or 'none'). When 'top' is selected, it uses the useIsScrollTop hook to toggle the transparency state as the user scrolls.
Note
isNavTransparent is passed via LayoutContext to the Header component, which applies a data-transparent attribute to its container. This allows CSS to reactively change background opacity based on scroll state.
Sources: packages/base-ui/src/layouts/notebook/client.tsx:82-83, packages/base-ui/src/layouts/notebook/slots/header.tsx:38-41
The Flux layout differs from the Notebook layout by prioritizing a mobile-first, floating navigation panel. It uses a custom NavigationPanel component that persists at the bottom of the screen on mobile or becomes a fixed floating element on larger screens via CSS grid or flexbox manipulation.
The Flux layout context provider also exposes slots for search triggers and layout tabs, but centers its interaction pattern around the NavigationPanel component, which manages search modal states and navigation toolsets.
The system supports multiple frameworks (Next.js, Waku, Tanstack) via the FrameworkProvider pattern. This decouples layout logic from the framework-specific router (e.g., usePathname, push).
To customize the header behavior in a Notebook layout, one can inject a custom component using the slots prop provided by the DocsLayout.
import { DocsLayout } from 'fumadocs-ui/layouts/notebook';
// Custom header implementation
const CustomHeader = () => (
<header className="custom-header">
<h1>My Docs</h1>
</header>
);
export default function RootLayout({ children }) {
return (
<DocsLayout
tree={tree}
slots={{
header: CustomHeader,
}}
>
{children}
</DocsLayout>
);
}