Skip to Content

Layouts

Choose a Fumadocs layout and change what each page renders.

Content pages use the Docs Layout by default, and plugin pages like the blog use the Home Layout. To use another layout, pass it to renderDefault() in ui.renderPage.

Built-in Layouts

The default, with a sidebar and a table of contents. See its props.

Docs Layout

Switching the Layout

Pass a Fumadocs layout to renderDefault(). This example renders the docs source with the Notebook Layout:

press.config.tsx
export default app.config({
  ui: {
    renderPage(props) {
      if (props.type === "docs") return props.renderDefault({ layout: "notebook" });
      return props.renderDefault();
    },
  },
});

layout is one of "docs", "notebook", "glass", "spacious" and "flux". Plugin pages, like the blog, keep the Home Layout.

Glass and Spacious also need their styles, imported before the theme. Use spacious.css for Spacious:

src/app.css
@import "tailwindcss";
@import "fumadocs-ui/css/generated/glass.css";
@import "fumadocs-ui/css/neutral.css";

A combined stylesheet like default.css can't go after them, so use the separate theme imports.

Layout Props

layoutProps go to the layout, and pageProps to the page. Their types follow layout:

press.config.tsx
props.renderDefault({
  layout: "notebook",
  layoutProps: { tabMode: "navbar" },
  pageProps: { tableOfContent: { style: "clerk" } },
});

They take priority over ui.layoutProps and over the UI of plugins in the same place, like a banner in sidebar.banner.

The layout is a client component, so a function in these props, like the transform of tabs, must come from a 'use client' file:

"use client";
import type { LayoutTab } from "fumadocs-ui/layouts/shared";

export function transformTab(tab: LayoutTab): LayoutTab {
  return { ...tab, description: undefined };
}

Rendering Pages

Every page goes through ui.renderPage. props.type tells you the kind of page: a source key like "docs", or the name of a plugin page like "blog.index".

Custom Layouts

To change the structure of a page, write its layout yourself with the components of Fumadocs UI:

src/ui/layout.tsx
import type { RenderPageProps } from "fumapress";
import { DocsLayout } from "fumadocs-ui/layouts/notebook";
import { DocsBody, DocsDescription, DocsPage, DocsTitle } from "fumadocs-ui/layouts/notebook/page";
import type { app } from "../../press.config";

function Docs({ layoutProps, pageData, toc, body, slots }: RenderPageProps<typeof app, "docs">) {
  return (
    <DocsLayout {...layoutProps}>
      <DocsPage toc={toc} full={pageData.full}>
        <DocsTitle>{pageData.title}</DocsTitle>
        <DocsDescription>{pageData.description}</DocsDescription>
        {slots["core:markdown"]?.element}
        <DocsBody>{body}</DocsBody>
      </DocsPage>
    </DocsLayout>
  );
}

export function renderPage(props: RenderPageProps<typeof app>) {
  // taken first: `props` is `never` in `default` once every type has a case
  const { renderDefault } = props;
  switch (props.type) {
    case "docs":
      return <Docs {...props} />;
    default:
      return renderDefault();
  }
}

The second type argument of RenderPageProps narrows the props to one page type. The layout reads these props:

  • layoutProps: ui.layoutProps with the props from plugins, and the page tree as tree.
  • pageData: the title, description and other fields a layout shows. Your frontmatter is on page.data.
  • toc: the table of contents.
  • body: the content.
  • slots: the UI of plugins and the page buttons, see Slots.

The AI chat reaches a custom layout through useLayoutProps() in a client component.

Layout per Source

Add a case for each source. The fields of its schema are typed on page.data.

src/ui/layout.tsx
function Guide({ page, body }: RenderPageProps<typeof app, "guides">) {
  return (
    <article>
      <span>{page.data.level}</span>
      {body}
    </article>
  );
}

export function renderPage(props: RenderPageProps<typeof app>) {
  const { renderDefault } = props;
  switch (props.type) {
    case "guides": 
      return <Guide {...props} />;
    case "docs":
      return <Docs {...props} />;
    default:
      return renderDefault();
  }
}

You can also check props.page.path, for example to use another layout for pages under reference/.

layoutProps.tree has every source, with each baseDir as a folder. selectTreeRoot() scopes the sidebar to one folder:

src/ui/layout.tsx
import { selectTreeRoot } from "fumapress";

<DocsLayout {...layoutProps} tree={selectTreeRoot(layoutProps.tree, "docs")} />;

Nested paths like "docs/guides" work too. To hide pages from the sidebar, see Hiding Pages from the Sidebar.

Slots

props.slots has the UI of plugins by name, like feedback:page, the form of Feedback. The page buttons are core:markdown and core:view-options. Each item has an element and the region it belongs to, like actions or footer. Banners of plugins aren't in it, since Fumapress renders them above every page.

A custom layout renders only the items it places. Place an item by its name, or collect the items of a region:

src/ui/layout.tsx
function Docs({ layoutProps, pageData, toc, body, slots }: RenderPageProps<typeof app, "docs">) {
  const footer: ReactNode[] = [];
  for (const slot of Object.values(slots)) if (slot?.region === "footer") footer.push(slot.element);

  return (
    <DocsLayout {...layoutProps}>
      <DocsPage toc={toc}>
        <DocsTitle>{pageData.title}</DocsTitle>
        <div className="flex gap-2">
          {slots["core:markdown"]?.element}
          {slots["core:view-options"]?.element}
        </div>
        <DocsBody>{body}</DocsBody>
        {footer}
      </DocsPage>
    </DocsLayout>
  );
}

Plugin Pages

Plugin pages, like the blog index, use the Home Layout by default. To restyle them, add a case to renderPage and render props.children, which is the content of the plugin page without a layout:

press.config.tsx
import { HomeLayout } from "fumadocs-ui/layouts/home";

renderPage(props) {
  const { renderDefault } = props;
  // the Home Layout takes these props, the others are for docs layouts
  const { nav, links, githubUrl, i18n, themeSwitch, searchToggle } = props.layoutProps;
  const home = { nav, links, githubUrl, i18n, themeSwitch, searchToggle };
  switch (props.type) {
    case "blog":
    case "blog.index":
    case "blog.tags":
    case "blog.tag":
      return (
        <HomeLayout {...home}>
          <div className="mx-auto w-full max-w-[1400px] px-4 py-6">{props.children}</div>
        </HomeLayout>
      );
    default:
      return renderDefault();
  }
},

To replace the content too, use the props of the plugin, as in the blog.

Customizing Fumadocs UI

npx @fumadocs/cli add banner
npx @fumadocs/cli customize

The Fumadocs CLI copies Fumadocs UI into your project, so that you can change its source. add copies a component, and customize copies a layout. Fumapress styles still apply to the copies.

Register a copied component in your MDX components module, and use a copied layout from ui.renderPage.

Features come from plugins

On a Fumapress site, the CLI only installs UI and rejects the rest. Use plugins for AI chat and MCP, Markdown, Open Graph images, search and feedback.

Last updated on

On this page