Page Slugs & Page Tree

OverviewCopy Anchor Link

Fumadocs generates page slugs and page tree (sidebar items) from your content directory using loader(), the routing functionality will be handled by your React framework.

You can define folders and pages similar to file-system based routing.

To customize its output further, you may use Loader Plugins.

FileCopy Anchor Link

For MDX & Markdown file, you can customize page information from frontmatter.

---
title: My Page
description: Best document ever
icon: House
---

## Learn More

Fumadocs detects from the following properties to construct page trees.

SlugsCopy Anchor Link

The slugs of a page are generated from its file path.

FolderCopy Anchor Link

Organize multiple pages, you can create a Meta file to customize folders.

Folder GroupCopy Anchor Link

By default, putting a file into folder will change its slugs. You can wrap the folder name in parentheses to avoid impacting the slugs of child files.

Root FolderCopy Anchor Link

Marks the folder as a root folder, only items in the opened root folder will be visible.

{
  "title": "Name of Folder",
  "description": "The description of root folder (optional)",
  "root": true
}

For example, when you are opening root folder framework, the other folders (e.g. headless) are not shown on the sidebar and other navigation elements.

Root TypeCopy Anchor Link

root also accepts a string, the type of root folder: root folders of the same type under the same parent scope are interchangeable, such as versions of the same docs.

{
  "title": "1.0.0",
  "root": "version"
}

root: true is simply the default type, displayed as tabs.

Switching to another root folder of the same type maps a page to its structural projection, the page at the same path relative to the root folder:

Path ParamsCopy Anchor Link

A folder or file named [name] is a dynamic segment. The meta file of a dynamic folder lists the values in staticParams, and Fumadocs generates a page for every value:

{
  "title": "Framework",
  "root": true,
  "staticParams": [{ "framework": "waku" }, { "framework": "astro" }]
}

Each page is compiled once per param value. The content reads the params as props.framework and can branch on them with <show>. In loader code, the params are in page.params.

The meta file of [framework] applies to every generated folder (waku, astro). A [name] segment whose meta file has no staticParams stays a literal folder name.

Page ParamsCopy Anchor Link

A page can also list staticParams in its frontmatter. When a page and its folder both list the same param name, the page is generated only for values that appear in both lists.

---
title: Fumadocs MDX
staticParams:
  - framework: waku
---

The page only exists for waku, at /docs/waku/fumadocs-mdx.

Data in CodeCopy Anchor Link

Frontmatter and meta files written in YAML or JSON are the same for every param value. To set a different title or description for each value, like a title that names the framework, write them in code. Fumadocs MDX and local Markdown sources support it.

A meta file can be a module (meta.ts or meta.js). In a dynamic folder, the default export is a function that receives the params, and staticParams is a named export:

const names = { waku: 'Waku', astro: 'Astro' };

export const staticParams = [{ framework: 'waku' }, { framework: 'astro' }];

export default ({ framework }: { framework: keyof typeof names }) => ({
  title: names[framework],
  root: true,
});

An MDX page can export frontmatter in code. The export is merged over the YAML frontmatter, and the page reads its params as props:

---
title: Deploy
---

export const frontmatter = {
  description: props.framework === 'astro' ? 'Deploy with an adapter.' : 'Deploy your docs.',
};

staticParams stays in YAML frontmatter, because the loader reads it before the export runs.

Static PathsCopy Anchor Link

A file at a literal path overrides the generated page for that value. astro/deploy.mdx overrides the astro page of [framework]/deploy.mdx, and astro/meta.json overrides the meta file of the astro folder.

With i18n, files of a locale take priority over those of its fallback locale: astro/deploy.cn.mdx, then [framework]/deploy.cn.mdx, then astro/deploy.mdx.

A localized page, like deploy.cn.mdx, reads staticParams from meta.cn.json before meta.json. With the dir parser, each language folder lists its own staticParams.

MetaCopy Anchor Link

Customize folders by creating a meta.json file in the folder.

{
  "title": "Display Name",
  "icon": "MyIcon",
  "pages": ["index", "getting-started"],
  "defaultOpen": true
}

PagesCopy Anchor Link

Folder items are sorted alphabetically by default, you can add or control the order of items using pages.

{
  "pages": ["index", "getting-started"]
}

{
  "pages": [
    "components",
    "---My Separator---",
    "...folder",
    "...",
    "!file",
    "!otherFolder",
    "[Vercel](https://vercel.com)",
    "[Triangle][Vercel](https://vercel.com)"
  ]
}

Folder IndexCopy Anchor Link

When folder owns a index item, it becomes clickable and jumps to the index item when clicked.

By default, it is the index file under each folder. You can specify the index item of a folder, it accepts Path and Link.

{
  // assume there's a "overview.mdx" file under the folder
  "pagesIndex": "overview"
}

IconsCopy Anchor Link

Since Fumadocs doesn't include an icon library, you have to convert the icon names to JSX elements in runtime, and render it as a component.

You can add an icon handler to loader().

i18n RoutingCopy Anchor Link

You can define different style for i18n routing.

import type { I18nConfig } from 'fumadocs-core/i18n';

export const i18n: I18nConfig = {
  // default
  parser: 'dot',
  // or
  parser: 'dir',
};