Organizing Pages

Organize documents with file-system based routing

Overview

This is a shared convention for organizing your documents.

Fumadocs MDX, and other file-system based content sources generate slugs and page trees depending on your file structure. Meaning that you can customise the sidebar and other navigation elements by changing the file structure.

File

A MDX or Markdown file.

Frontmatter

By default, it includes:

namedescription
titleThe title of page
descriptionThe description of page
iconThe name of icon, see Icons
fullFill all available space on the page (Fumadocs UI)

You may extend your content source to add additional properties.

---
title: My Page
description: Best document ever
icon: HomeIcon
full: false
---
 
## Learn More

Slugs

The generated slugs will be same as your file path.

path (relative to root folder)slugs
./dir/page.mdx['dir', 'page']
./dir/index.mdx['dir']

Folder

Organize multiple pages. When not specified, the display name will be generated from its folder name.

Pages are sorted alphabetically, except index.mdx which is always ordered at the top.

To customise folders, use Meta file.

Folder Group

By default, putting a file into folder will change its slugs and generated page URL. You can use folder group to add a folder without impacting the slugs of child files.

To create a folder group, wrap the folder name in parentheses.

file.mdx

Meta

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

Display Name

{
  "title": "Name of Folder"
}

Icon

Specify an icon name for folder with the icon property, see Icons.

meta.json
{
  "title": "My Folder",
  "icon": "MyIcon"
}

Pages

Control the order of items.

When a meta file is present, items are not included unless you have explicitly added them to pages.

{
  "title": "Name of Folder",
  "pages": ["guide", "components"]
}
meta.json
guide.mdx
components.mdx

Path

The items of pages property can be a relative path to a page or folder. File extensions are not required.

{
  "title": "Name of Folder",
  "pages": ["../headless/page"]
}

Open by Default

Force to open the folder by default.

meta.json
{
  "title": "Name of Folder",
  "defaultOpen": true
}

Separator

You can define a separator in meta by adding a item surrounded with ---.

{
  "title": "Name of Folder",
  "pages": ["---Separator---"]
}

Rest

Add a Rest (...) item to automatically add and sort remaining page items.

Note

Index pages won't be included, you must specify the order of index.

{
  "title": "Folder",
  "pages": ["guide", "..."]
}

Except

In conjunction with the Rest item (...), you can use !name to exclude an item from the rest.

{
  "title": "Folder",
  "pages": ["...", "!hide-this-page"]
}

Extract

You can extract the items from a folder with ...folder_name.

{
  "title": "Folder",
  "pages": ["guide", "...folder"]
}

Use the syntax [Text](url) to insert links.

{
  "title": "Folder",
  "pages": ["index", "[Vercel](https://vercel.com)"]
}

You can add an icon too.

{
  "title": "Folder",
  "pages": ["index", "[Triangle][Vercel](https://vercel.com)"]
}

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 use the icon handler from Source API.

Multiple Page Trees

Adding a root property in meta file can mark your folder as a root.

meta.json
{
  "title": "Name of Folder",
  "root": true
}

When the user is browsing a page under a root folder, only the child items of the folder will be visible.

For example, when you are in a root folder called core, the other folders (e.g. ui) are not shown on the sidebar and other navigation elements.

Current Page
Other Pages
Invisible Page

Fumadocs UI

When a root folder exists, Fumadocs UI will add a Tabs component to the sidebar. It allows user to switch between different roots.

You can customise it via sidebar.tabs in Docs Layout.

Index Pages

By default, index pages are not considered as a page "under" the folder, you must specify them in the pages property.

Internationalization

You can create a localized page for specific language by adding .{locale} to your file name. Pages can't be language-specific, you must create a page for default locale in order to have its localized version.

This works for meta files too, you can add .{locale} to the file name like meta.cn.json.

If it's the default language, just leave it empty like get-started.mdx. Do not add locale code to file name.

Example

Assume your default language is en.

Name
file.mdxCorrect
file.cn.mdxCorrect
file.en.mdxDefault locale doesn't need a locale code
components.cn.mdxPages can't be language-specific
Edit on GitHub

Last updated on

On this page