Layouts

Guides use one of five Fumadocs layouts. You pick it with layout.type, and every other layout option maps to the Fumadocs prop of the same meaning. The API reference and the API client keep their own layout; these options only change guide pages.

The sidebar and the table of contents have their own pages: Sidebar and Table of contents.

Choose a layoutCopy Anchor Link

import { defineConfig } from '@orbitdocs/next/config';

export default defineConfig({
  site: { title: 'Acme' },
  layout: {
    type: 'docs',
  },
});

The home page can also be a full-width landing page with layout: landing in its frontmatter. See Landing pages.

Configure the navbarCopy Anchor Link

layout: {
  type: 'notebook',
  navMode: 'auto',
  transparentNav: 'top',
},

• navMode (notebook only): top puts the navbar above everything, sidebar included. auto puts it beside the sidebar.
• transparentNav: always keeps the navbar transparent, top only while the page is scrolled to the top, none never.

The links in the navbar come from navigation. See Navigation bar.

Breadcrumb and page footerCopy Anchor Link

layout: {
  breadcrumb: { enabled: true, includeRoot: true, includePage: false, includeSeparator: false },
  footer: true,
},

• The breadcrumb shows the folders above the current page. includeRoot adds the root folder; includePage adds the page itself; includeSeparator adds the sidebar separator the page sits under.
• footer shows "Previous" and "Next" links at the bottom of each guide. Their order follows the sidebar. To pick other pages, set footer.items in lib/overrides.tsx (see Override React-only options).

Page widthCopy Anchor Link

full: true removes the table of contents column so content fills the page. Set it for the whole site, or per page in frontmatter:

---
title: Changelog
full: true
---

To change the width of the layout itself, use theme.widths (see Themes and colors).

"Last updated" and "Edit on GitHub"Copy Anchor Link

layout: {
  lastUpdated: true,
  editOnGithub: { owner: 'acme', repo: 'api', branch: 'main', dir: 'docs/content' },
},

• lastUpdated shows the date of the page's last commit, read from git at build time.
• editOnGithub adds an "Edit on GitHub" link to https://github.com/<owner>/<repo>/blob/<branch>/<dir>/<page file>. dir is the path of content/ from the repository root: docs/content when the docs app lives in docs/.

Page actionsCopy Anchor Link

Every guide page shows three buttons under its title: Copy page, Open in ChatGPT and Open in Claude. Keep the ones you want, or pass an empty list to hide them all:

layout: {
  pageActions: ['copy-markdown'],
},

llms.txt and page actions explains what each button does.

What each layout supportsCopy Anchor Link

Fumadocs layouts don't all accept the same props. OrbitDocs passes each one what it accepts; the rest is ignored.

Layout optionsCopy Anchor Link

The options on this page. Sidebar and table of contents options are listed on their own pages.

Override React-only optionsCopy Anchor Link

Some Fumadocs options take React: components, elements or functions. They can't go in orbitdocs.config.ts, so the docs app has lib/overrides.tsx. OrbitRoot, every layout and every guide page in app/ get its overrides object and merge it over what the config sets.

import type { OrbitOverrides } from '@orbitdocs/next';

import { VersionPicker } from '@/components/version-picker';

export const overrides: OrbitOverrides = {
  layout: {
    // A custom navbar title. The link target is navigation.titleUrl in the config.
    nav: { title: <span className="font-semibold">Acme Docs</span> },
    // Items after the config's header links. A function gets them all and returns the list.
    links: [{ type: 'custom', children: <VersionPicker /> }],
    containerProps: { className: 'acme-docs' },
  },
  page: (page) => ({
    // Previous / next links from the page's frontmatter instead of the sidebar order.
    footer: page.data.next ? { items: { next: { name: 'Next step', url: String(page.data.next) } } } : undefined,
  }),
};

layout.slots replaces parts of the layout (navTitle, searchTrigger, themeSwitch, header, container, …); which slots exist depends on layout.type, and the types are Fumadocs' own. layout also applies to the top bar of the API reference and the API client, except sidebar, tabs and containerProps. A component used in a slot, or anything else that runs in the browser, needs 'use client' at the top of its file.

Use a Fumadocs layout directlyCopy Anchor Link

app/(guides)/layout.tsx renders GuidesLayout, which picks the layout from your config. When overrides aren't enough (a different sidebar component, a layout of your own), render the Fumadocs layout yourself. orbitLayoutOptions keeps the OrbitDocs header: logo, Guides, API Reference, API Client, your header links, Ask AI and the user menu.

import { orbitLayoutOptions } from '@orbitdocs/next';
import { guidesTree } from '@orbitdocs/next/server';
import { DocsLayout } from 'fumadocs-ui/layouts/docs';
import type { ReactNode } from 'react';

import { orbit } from '@/lib/orbit';
import { overrides } from '@/lib/overrides';
import { source } from '@/lib/source';

export default function Layout({ children }: { children: ReactNode }) {
  return (
    <DocsLayout
      {...orbitLayoutOptions(orbit, { overrides })}
      // With private docs, only pages every reader may open (see Access rules).
      tree={guidesTree(source.getPageTree())}
      // Any DocsLayout prop, e.g. a custom sidebar footer:
      sidebar={{ footer: <p className="text-xs">Need help? support@acme.com</p> }}
    >
      {children}
    </DocsLayout>
  );
}

With private docs, make the same change in app/~/[variant]/layout.tsx, which renders the guides for readers who may open restricted pages; its tree is guidesTree(source.getPageTree(), variant), and orbitLayoutOptions(orbit, { readerOf: `/~/${variant}`, overrides }) lets its top bar list the APIs those readers may open.

The layout options in orbitdocs.config.ts no longer apply to the sidebar when you do this. Page options (toc, breadcrumb, pageActions, …) still work because GuidePage renders them.

Next stepsCopy Anchor Link