Customizing Layouts

Overview

About Customizing Layouts

Customizing layouts allows you to tailor your documentation site's visual appearance, structure, and branding to fit your needs. You can configure color themes, modify page headers and footers, adjust logos and titles, and personalize specific sections like sidebars and tables of contents using layout slots and configuration options.

Customizing Color Themes and Variables

You can customize the color scheme and appearance of your layouts by adjusting styling configuration variables in your global stylesheet.

Supported color and layout theme variable keys include:

• Background and foreground colors (--color-fd-background, --color-fd-foreground, --color-fd-muted, --color-fd-muted-foreground)
• Card and popover elements (--color-fd-card, --color-fd-card-foreground, --color-fd-popover, --color-fd-popover-foreground)
• Interactive elements and borders (--color-fd-primary, --color-fd-primary-foreground, --color-fd-secondary, --color-fd-secondary-foreground, --color-fd-accent, --color-fd-accent-foreground, --color-fd-border, --color-fd-ring)
• Layout dimensions (--spacing-fd-container, --fd-page-width, --fd-sidebar-width, --fd-toc-width, --fd-layout-width, --fd-banner-height, --fd-nav-height, --fd-tocnav-height)

Configuring Logos and Navigation Titles

You can customize the site title and logo displayed in the navigation bar by updating your base layout configuration.

Copyimport { FumadocsLogo } from '@/components/logo';
 
export function layoutConfig(config) {
  const { base } = config.layout;
 
  return {
    async base() {
      let defaultConfig;
      if (typeof base === 'function') defaultConfig = await base();
      else if (typeof base === 'object') defaultConfig = base;
 
      return {
        ...defaultConfig,
        nav: {
          title: (
            <>
              <FumadocsLogo className="size-5" />
              My Documentation
            </>
          ),
          ...defaultConfig?.nav,
        },
      };
    },
  };
}

Adding and Configuring Banners

Banners allow you to display important announcements or alerts at the very top of your pages. Banners support normal and animated rainbow styles, automatic layout padding adjustments, and persistent dismissal options.

Copyimport { Banner } from '@/components/banner';
 
export function AnnouncementBanner() {
  return (
    <Banner id="announcement-v2" variant="normal">
      Check out our brand new release!
    </Banner>
  );
}

Using Layout Slots for Custom Headers and Footers

Overview of Layout Slots

Layout slots let you swap out or extend internal layout components—such as navigation headers, sidebars, tables of contents, breadcrumbs, and footers—without rebuilding the entire layout structure.

Customizing Page Slots

At your page component level, you can supply custom components to individual slots like the table of contents, container, footer, or breadcrumb:

Copyimport { DocsPage } from 'fumadocs-ui/layouts/notebook/page';
import { Container, Footer, Breadcrumb } from './custom-components';
 
return (
  <DocsPage
    slots={{
      container: Container,
      footer: Footer,
      breadcrumb: Breadcrumb,
    }}
  >
    {/* Page content */}
  </DocsPage>
);

Customizing Layout Slots

At your layout level, you can customize structural elements like the sidebar, header, and tab dropdowns:

Copyimport { DocsLayout } from 'fumadocs-ui/layouts/notebook';
import { SidebarProvider, Sidebar, SidebarTrigger, useSidebar } from './custom-sidebar';
 
return (
  <DocsLayout
    slots={{
      sidebar: {
        provider: SidebarProvider,
        root: Sidebar,
        trigger: SidebarTrigger,
        useSidebar: useSidebar,
      },
    }}
  >
    {/* Layout content */}
  </DocsLayout>
);

Workflow Summary

Configuration Reference

Related

• Interactive Components
• Site Navigation