Page Slugs & Page Tree
A shared convention for organizing your documents
This guide only applies for content sources that uses loader() API, such as Fumadocs MDX.
Overview
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.
File
For MDX & Markdown file, you can customize page information from frontmatter.
---
title: My Page
description: Best document ever
icon: HomeIcon
---
## Learn MoreFumadocs detects from the following properties to construct page trees.
| name | description |
|---|---|
title | The title of page |
description | The description of page |
icon | The name of icon, see Icons |
Good to Know
Page information is supplied by the content source such as Fumadocs MDX.
On Fumadocs MDX, you can specify a schema option to customize frontmatter schema.
Slugs
The slugs of a page are generated from its file path.
| path (relative to content folder) | slugs |
|---|---|
./dir/page.mdx | ['dir', 'page'] |
./dir/index.mdx | ['dir'] |
Folder
Organize multiple pages, you can create a Meta file to customize folders.
Folder Group
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.
| path (relative to content folder) | slugs |
|---|---|
./(group-name)/page.mdx | ['page'] |
Root Folder
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.
Fumadocs UI
Fumadocs UI renders root folders as Layout Tabs, which allows users to switch between them.
Meta
Customize folders by creating a meta.json file in the folder.
{
"title": "Display Name",
"icon": "MyIcon",
"pages": ["index", "getting-started"],
"defaultOpen": true
}| name | description |
|---|---|
title | Display name |
icon | The name of icon, see Icons |
defaultOpen | Open the folder by default |
collapsible | Collapsible folder content (default: true) |
pages | Folder items (see below) |
pagesIndex | The index item (see below) |
Pages
Folder items are sorted alphabetically by default, you can add or control the order of items using pages.
{
"pages": ["index", "getting-started"]
}When specified, items are not included unless they are listed in pages.
| Type | Syntax | Description |
|---|---|---|
| Path | ./path/to/page | a path to page or folder. |
| Separator | ---Label------[Icon]Label--- | a separator between two sections (icon supported). |
| Link | [Text](url)[Icon][Text](url)external:[Text](url) | insert links (icon supported) add a external: prefix to mark links as external. |
| Rest | ... | include remaining pages (sorted alphabetically). |
| Reversed Rest | z...a | reversed Rest item. |
| Extract | ...folder | extract the items from a folder. |
| Except | !item | Exclude an item from ... or z...a. |
{
"pages": [
"components",
"---My Separator---",
"...folder",
"...",
"!file",
"!otherFolder",
"[Vercel](https://vercel.com)",
"[Triangle][Vercel](https://vercel.com)"
]
}No Duplicated URL
The same page URL must not appear more than once in the entire page tree. Duplicated page items are not allowed for the same reason.
This is intentional, such that Fumadocs can locate the active tree item purely based on current pathname.
Folder Index
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"
}Icons
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 Routing
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',
};Add Markdown/meta files for different languages by attending .{locale} to your file name, like:
For the default locale, the locale code is optional.
All content files are grouped by language folders:
How is this guide?