Navigation

Introduction

Fumadocs UI uses Page Tree to control navigation elements. It's a tree structure as described in the definitions, including all the navigation links related to the docs.

By design, page tree only contains necessary information of all pages and folders.

Page Tree

The page tree itself can be hardcoded, or generated by your content source (e.g. Fumadocs MDX).

For file-system based content sources, it is generated from your file structure. You can see Organizing Pages to learn how to customise the file structure.

It is passed to the Docs Layout component and shared to navigation elements:

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

Link Items

You can use the Links API to add global links.

They are displayed on all Fumadocs UI layouts (e.g. Home Layout and Docs Layout). Links items are passed to the layout.

import { type HomeLayoutProps } from 'fumadocs-ui/home-layout';
 
export const baseOptions: HomeLayoutProps = {
  links: [
    {
      text: 'Documentation',
      url: '/docs',
      active: 'nested-url',
    },
  ],
};

GitHub Url

A shortcut for adding GitHub repository link item.

import { type HomeLayoutProps } from 'fumadocs-ui/home-layout';
 
export const baseOptions: HomeLayoutProps = {
  githubUrl: 'https://github.com',
};

Navbar

A part of all Fumadocs UI layouts, it displays the link items and your logo.

import { type HomeLayoutProps } from 'fumadocs-ui/home-layout';
 
export const baseOptions: HomeLayoutProps = {
  nav: {
    // Give it a logo
    title: <div>Logo</div>,
    // You can also customise the href of Logo
    url: '/docs',
  },
};

For the full options, see Navbar.

Sidebar

A part of Docs Layout, it displays the complete structure of page tree.

Besides the page tree, the sidebar exposes a banner and footer option. You can use them to add additional components.

For example, adding an announcement to the top of sidebar.

import { DocsLayout } from 'fumadocs-ui/layout';
 
<DocsLayout
  sidebar={{
    banner: (
      <div>
        <h3>Nuxt Nation 2024</h3>
        <p>
          Join over 21,000 fellow Nuxt & Vue Developers to learn everything Nuxt
          has to offer in 2024!
        </p>
      </div>
    ),
  }}
/>;

Table Of Contents

A part of Docs Page, it displays the headings of document.

It depends on the toc prop you passed. Generally, it is generated from the Markdown/MDX content (usually supplied by the content source, or using a Remark plugin). You may modify the data passed to toc (e.g. adding another anchor or modify the text).

import { DocsPage } from 'fumadocs-ui/page';
 
<DocsPage
  toc={
    // table of contents
  }
>
  ...
</DocsPage>;

It exposes a banner and footer option, use it to add additional components about the page.

import { DocsPage } from 'fumadocs-ui/page';
 
<DocsPage
  tableOfContent={{
    banner: <Banner />,
  }}
>
  ...
</DocsPage>;

Popover Mode

On smaller devices, it is shown as a popover (dropdown) component. You can also customise it with the exposed props aforementioned.

To display the same banner/footer on both modes, pass them individually.

import { DocsPage } from 'fumadocs-ui/page';
 
<DocsPage
  tableOfContent={{
    banner: <Banner />,
  }}
  tableOfContentPopover={{
    banner: <Banner />,
  }}
>
  ...
</DocsPage>;

Breadcrumbs

A part of Docs Page, it displays the path to the active node of page tree.

For example, when opening page A, the breadcrumbs should display folder > a.

By default, meaningless parts like the page tree root are omitted. You can customise its behaviour with the exposed options.

import { DocsPage } from 'fumadocs-ui/page';
 
<DocsPage
  breadcrumb={
    // options
  }
>
  ...
</DocsPage>;

For the full options, see Breadcrumbs.

Page Footer

A part of Docs Page, it displays two buttons to jump to the next and previous pages.

By default, it selects the neighbour nodes of the active node in page tree. You can specify the items of footer.

import { DocsPage } from 'fumadocs-ui/page';
 
<DocsPage
  footer={{
    next: { name: 'next page', url: 'path/to/next' },
  }}
>
  ...
</DocsPage>;

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:

Links API -> Root Toggle & Document Search -> Page Tree -> Page

1. Links API adds global links to the layout, they should redirect the user to another layout, like the blog page or the landing page.

2. A page tree can have multiple roots, each root contains a tree of navigation links. Users can switch between roots with Root Toggle.

3. The active root 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 (TOC) 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.

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.