Customizing the Layout

Using Built-in Layouts

Fumadocs provides ready-to-use layouts. Let's go through them.

1.1. Docs Layout

The Docs Layout is the default option.
It's a clean, simple layout optimized for technical documentation.

To use this layout, update your layout.tsx file in src/docs/layout.tsx:

import { DocsLayout } from 'fumadocs-ui/layouts/docs'

1.2. Notebook Layout

The Notebook Layout is a more compact variation of the Docs Layout. It supports three different design modes:

1.2.1. Default Design

• The context switcher is integrated directly into the sidebar.
• You can switch between contexts (e.g., framework docs, API reference) without leaving the navigation area.
• The sidebar combines both navigation sections (like Setup, Writing, UI) and the context switcher in a single column.

import { DocsLayout } from 'fumadocs-ui/layouts/notebook';
import { baseOptions } from '@/lib/layout.shared';
import { source } from '@/lib/source';
import type { ReactNode } from 'react';

export default function Layout({ children }: { children: ReactNode }) {
  return (
    <DocsLayout {...baseOptions()} tree={source.pageTree}>
      {children}
    </DocsLayout>
  );
}

1.2.2. Tab Mode

• The context switcher appears as horizontal tabs at the top of the documentation page.
• Each tab represents a different context (e.g., Framework, Core, MDX, CLI, OpenAPI Example).
• The sidebar remains dedicated to page-level navigation, while the top tabs control context switching.

import { DocsLayout } from 'fumadocs-ui/layouts/notebook';
import { baseOptions } from '@/lib/layout.shared';
import { source } from '@/lib/source';
import type { ReactNode } from 'react';

export default function Layout({ children }: { children: ReactNode }) {
  return (
    <DocsLayout
      {...baseOptions()}
      tabMode="navbar"
      tree={source.pageTree}
    >
      {children}
    </DocsLayout>
  );
}

1.2.3. Nav Mode

• Both the search bar and context switcher move into a global navigation area above the sidebar and main content.
• This creates a header-like navigation where search and context switching are the primary controls.
• The sidebar is shifted downward and focuses only on document hierarchy.

import { DocsLayout } from 'fumadocs-ui/layouts/notebook';
import { baseOptions } from '@/lib/layout.shared';
import { source } from '@/lib/source';
import type { ReactNode } from 'react';

export default function Layout({ children }: { children: ReactNode }) {
  const { nav, ...base } = baseOptions();

  return (
    <DocsLayout
      {...base}
      tabMode="navbar"
      nav={{ ...nav, mode: 'top' }}
      tree={source.pageTree}
    >
      {children}
    </DocsLayout>
  );
}

Creating a Custom Layout

If you need a design that cannot be achieved by styling the built-in layouts, you can generate a custom layout using the Fumadocs CLI.

⚠️ Caution: Custom layouts are not officially maintained. You will be responsible for updating them whenever Fumadocs releases new versions.

Run this command to create one:

npx @fumadocs/cli customise