Organizing Pages

Overview

Page slugs and sidebar items (page tree) are generated from your file structure, similar to file-system based routing in Next.js.

File

A MDX or Markdown file.

Frontmatter

By default, it includes:

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.

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.

Meta

Customize a folder by creating a meta.json file in a folder under content folder.

Display Name

{
  "title": "Name of Folder"
}

Icon

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

{
  "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"]
}

Path

The items of pages can also be a relative path to a page or folder, no file extensions needed.

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

Open by Default

Force to open the folder by default.

{
  "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 alphabetically.

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

You can also sort items reversely.

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

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"]
}

Link

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 add an icon handler to loader().

Root Folder

Marks the folder as a root folder.

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

Only items in the current root folder will be considered.

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

Index Pages

By default, index pages are not considered as the child item of a folder, you must specify them in the pages property.

Internationalization

You can add Markdown/meta files for different languages by attending .{locale} to your file name, like page.fr.md and meta.fr.json.

Make sure to create a file for the default locale first, the locale code is optional (e.g. both get-started.mdx and get-started.en.mdx are accepted).