---
title: Navigation
description: Configuring navigation elements
---

import { Files, Folder, File } from 'fumadocs-ui/components/files';

## 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](/docs/ui/layouts/docs) component and shared to navigation elements:

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

<DocsLayout
  tree={
    // page tree here
  }
/>;
```

### Link Items

You can use the [Links API](/docs/ui/layouts/links) 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.

```tsx twoslash title="app/layout.config.tsx"
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.

```tsx twoslash title="app/layout.config.tsx"
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.

```tsx twoslash title="app/layout.config.tsx"
import React from 'react';
// ---cut---
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](/docs/ui/layouts/navbar).

### Sidebar

A part of [Docs Layout](/docs/ui/layouts/docs#sidebar), 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:

```tsx title="layout.tsx"
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](/docs/ui/layouts/page) Layout.

### Table Of Contents

It displays the headings of document.

```tsx page.tsx
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](https://github.com/remarkjs/remark)).
You may modify the data passed to `toc`.

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

```tsx page.tsx
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.

```tsx
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`.

<Files>
  <Folder name="folder" defaultOpen>
    <File name="A" />
  </Folder>
</Files>

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

```tsx title="page.tsx"
import { DocsPage } from 'fumadocs-ui/page';

<DocsPage
  breadcrumb={
    // options
  }
>
  {children}
</DocsPage>;
```

For the full options, see [Breadcrumbs](/docs/ui/layouts/page#breadcrumb).

### 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.

```tsx title="page.tsx"
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](/docs/ui/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.

<Files>
  <Folder name="app" defaultOpen>
    <File name="(home)/docs/page.tsx" />
    <Folder name="docs" defaultOpen>
      <File name="layout.tsx" />
      <File name="[[...slug]]/page.tsx" />
    </Folder>
  </Folder>
</Files>

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](/docs/ui/page-conventions#multiple-page-trees).
