Docs Layout

The layout of documentation pages, it includes a sidebar and navbar.

Usage

Pass your page tree to the component.

import { DocsLayout } from 'fumadocs-ui/layouts/docs';
import { baseOptions } from '@/app/layout.config';
import type { ReactNode } from 'react';
 
export default function Layout({ children }: { children: ReactNode }) {
  return (
    <DocsLayout {...baseOptions} tree={tree}>
      {children}
    </DocsLayout>
  );
}

Sidebar

Provide elements to navigate between pages.

import { DocsLayout } from 'fumadocs-ui/layouts/docs';
 
<DocsLayout
  sidebar={
    {
      // options
    }
  }
/>;

Sidebar Tabs

Add a navigation component to switch between root folders (Enabled by default). You can add items from the page tree (see Root Folder).

Disable Tabs

import { DocsLayout } from 'fumadocs-ui/layouts/docs';
 
<DocsLayout sidebar={{ tabs: false }} />;

Add Description

Add description to the meta file of root folder.

{
  "root": true,
  "description": "The description of root folder"
}

Decoration

Change the icon/styles of tabs.

import { DocsLayout } from 'fumadocs-ui/layouts/docs';
 
<DocsLayout
  sidebar={{
    tabs: {
      transform: (option, node) => ({
        ...option,
        icon: 'my icon',
      }),
    },
  }}
/>;

Disable Prefetching

By default, it uses the Next.js Link component with prefetch enabled. When the link component appears into the browser viewport, the content (RSC payload) will be lazy loaded.

Unless you put most of the page items in folders, all page items on the sidebar will be lazy loaded. On Vercel, this may cause a high usage of serverless functions and Data Cache. It can also hit the limits of some other hosting platforms.

You can disable prefetching to reduce the amount of RSC requests.

import { DocsLayout } from 'fumadocs-ui/layouts/docs';
 
<DocsLayout sidebar={{ prefetch: false }} />;

Disable Sidebar from Pages

This is not supported. Due to the limitations of App Router, layouts are not re-rendered when navigating between pages. It is an anti-pattern to change your layout from a page.

You can consider:

1. Disable sidebar from the entire layout.
2. Create a MDX Page in a layout that doesn't contain a sidebar.

Notebook

Enable the notebook layout with fumadocs-ui/layouts/notebook, it's a more compact layout than the default one.

import { DocsLayout } from 'fumadocs-ui/layouts/notebook';
import { baseOptions } from '@/app/layout.config';
import type { ReactNode } from 'react';
 
export default function Layout({ children }: { children: ReactNode }) {
  return (
    <DocsLayout {...baseOptions} tree={tree}>
      {children}
    </DocsLayout>
  );
}

Replacing Navbar

Fumadocs uses CSS Variables to share the size of layout components, and fit each layout component into appropriate position.

To replace the navbar in Docs Layout, set nav.component to your own component.

import { DocsLayout } from 'fumadocs-ui/layouts/notebook';
import type { ReactNode } from 'react';
 
export default function Layout({ children }: { children: ReactNode }) {
  return (
    <DocsLayout
      // other options
      nav={{
        component: <CustomNavbar />,
      }}
    >
      {children}
    </DocsLayout>
  );
}

You need to override --fd-nav-height to the exact height of your custom navbar, this can be done with a CSS stylesheet (e.g. in global.css):

:root {
  --fd-nav-height: 80px !important;
}

Note that !important is required to override CSS variables.

References

Sidebar

Layout