Navigation

Layouts

Add links to Fumadocs UI layouts.

Page Tree

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

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

import { DocsLayout } from 'fumadocs-ui/layouts/docs';
 
<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 { BaseLayoutProps } from 'fumadocs-ui/layouts/shared';
 
export const baseOptions: BaseLayoutProps = {
  links: [
    {
      text: 'Documentation',
      url: '/docs',
      active: 'nested-url',
    },
  ],
};

GitHub Url

A shortcut for adding GitHub repository link item.

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

Navbar

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

import type { BaseLayoutProps } from 'fumadocs-ui/layouts/shared';
 
export const baseOptions: BaseLayoutProps = {
  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 as the banner of sidebar:

import { DocsLayout } from 'fumadocs-ui/layouts/docs';
 
<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>
    ),
  }}
/>;

Docs Page

A documentation page, with Docs Page Layout.

Table Of Contents

It displays the headings of document.

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

Generally, toc 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.

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: <div>Hello World</div>, // your banner
  }}
>
  {children}
</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: <div>Hello World</div>,
  }}
  tableOfContentPopover={{
    banner: <div>Hello World</div>,
  }}
>
  {children}
</DocsPage>;

Breadcrumbs

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
  }
>
  {children}
</DocsPage>;

For the full options, see Breadcrumbs.

Page Footer

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' },
  }}
>
  {children}
</DocsPage>;

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:

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

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

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

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.