Navigation

Adding Links to Layouts

You can display links by customising the links option of layouts.

Link Item

A link to navigate to a URL/href, can be external.

import { BookIcon } from 'lucide-react';
import type { BaseLayoutProps } from 'fumadocs-ui/layouts/shared';
 
export const baseOptions: BaseLayoutProps = {
  links: [
    {
      icon: <BookIcon />,
      text: 'Blog',
      url: '/blog',
    },
  ],
};

Active Mode

The conditions to be marked as active.

import type { BaseLayoutProps } from 'fumadocs-ui/layouts/shared';
 
export const baseOptions: BaseLayoutProps = {
  links: [
    {
      text: 'Blog',
      url: '/blog',
      active: 'nested-url',
    },
  ],
};

Secondary

Set the item as secondary, secondary items will be displayed differently on navbar.

import type { BaseLayoutProps } from 'fumadocs-ui/layouts/shared';
 
export const baseOptions: BaseLayoutProps = {
  links: [
    {
      text: 'Blog',
      url: '/blog',
      secondary: true,
    },
  ],
};

Filter

You can restrict where the item is displayed.

import type { BaseLayoutProps } from 'fumadocs-ui/layouts/shared';
 
export const baseOptions: BaseLayoutProps = {
  links: [
    {
      on: 'menu',
      url: '/blog',
      text: 'Blog',
    },
  ],
};

Icon Item

Same as link item, but is shown as an icon button on navbar. Icon items are secondary by default.

import { BookIcon } from 'lucide-react';
import type { BaseLayoutProps } from 'fumadocs-ui/layouts/shared';
 
export const baseOptions: BaseLayoutProps = {
  links: [
    {
      type: 'icon',
      label: 'Visit Blog', // `aria-label`
      icon: <BookIcon />,
      text: 'Blog',
      url: '/blog',
    },
  ],
};

Button Item

Same as link item, but is shown as a button.

import type { BaseLayoutProps } from 'fumadocs-ui/layouts/shared';
 
export const baseOptions: BaseLayoutProps = {
  links: [
    {
      type: 'button',
      text: 'Feedback',
      url: '/feedback',
    },
  ],
};

Navigation Menu

A navigation menu containing link items.

import type { BaseLayoutProps } from 'fumadocs-ui/layouts/shared';
 
export const baseOptions: BaseLayoutProps = {
  links: [
    {
      type: 'menu',
      text: 'Guide',
      items: [
        {
          text: 'Getting Started',
          description: 'Learn to use Fumadocs',
          url: '/docs',
 
          // (optional) Props for Radix UI Navigation Menu item in Home Layout
          menu: {
            className: 'row-span-2',
            // add banner to navigation menu card
            // can be an image or other elements
            banner: <div>Banner</div>,
          },
        },
      ],
    },
  ],
};

Note that the description field will only be displayed on the navbar in Home Layout.

Custom Item

Display a custom component.

import type { BaseLayoutProps } from 'fumadocs-ui/layouts/shared';
 
export const baseOptions: BaseLayoutProps = {
  links: [
    {
      type: 'custom',
      children: <div>Hey</div>,
    },
  ],
};

GitHub Url

There's also a shortcut for adding GitHub repository link item.

import type { BaseLayoutProps } from 'fumadocs-ui/layouts/shared';
 
export const baseOptions: BaseLayoutProps = {
  githubUrl: 'https://github.com',
};

Customise Sidebar

You can customise all navigation elements with Page Tree, a tree that describes all available pages.

It can be hardcoded, or generated from your file structure for content sources like Fumadocs MDX. See Organizing Pages to learn how to customise the generated page tree.

Pass it to the Docs Layout component:

import { DocsLayout } from 'fumadocs-ui/layouts/docs';
 
<DocsLayout
  tree={
    // page tree here
  }
/>;

Others

Document Search

Search is also an important way to navigate between pages, you can refer to Search to learn more about configuring document search.

Hierarchy

Hierarchy can create an intuition to users, Fumadocs UI is designed in:

Layout Links -> Sidebar Tabs & Document Search -> Sidebar Items -> Page

1. Layout links should redirect the user to another layout, like the blog page or landing page.

2. A sidebar can have multiple tabs, each tab opens a different tree of navigation links.

3. The active page tree will be shown on navigation elements like sidebar, allowing users to switch between pages.

4. The page shows its content, with elements like Table of Contents to improve the reading experience.

Nodes should not impact their upper nodes (ancestors). For example, clicking a page tree item on sidebar should not change the root of page tree.

Changing Routes

The default routing structure of your docs can also be changed as it is essentially a Next.js app.

Remove the docs layout of a certain page

The /docs/[[...slug]] route is a catch-all route.

To use another layout for a certain page, move the page outside the app/docs folder, to a place that's accessible with the same base route /docs.

This is possible using Next.js Route Group. For example, adding a /docs page without docs layout.

Ensure there's no duplicated page with the same URL in the catch-all route [[...slug]]/page.tsx. In the above example, a MDX file with the path content/docs/index.mdx will produce errors.

FAQ

Multi versions

Use a separate deployment for each version.

On Vercel, this can be done by creating another branch for a specific version on your GitHub repository. To link to the sites of other versions, use the Links API or a custom navigation component.

Multi Docs

See Multiple Page Trees.