Routing

Overview

While Next.js handles routing, Fumadocs generates page slugs and sidebar items (page tree) from your content directory using loader().

You can define folders and pages similar to the file-system based routing of Next.js.

File

A MDX or Markdown file, you can customise its frontmatter.

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

Slugs

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

Folder

Organize multiple pages, you can create a Meta file to customise 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.

Meta

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

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

Pages

By default, folder items are sorted alphabetically.

You can control the order of items using pages, items are not included unless they are listed inside.

{
  "title": "Name of Folder",
  "pages": ["guide", "components", "./nested/page"]
}

Separator

{
  "pages": ["guide", "---My Separator---", "components"]
}

Rest

Add a ... item to include remaining pages (sorted alphabetically), or z...a for descending order.

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

You can add !name to prevent an item from being included.

{
  "pages": ["guide", "...", "!components"]
}

Extract

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

{
  "pages": ["guide", "...nested"]
}

Link

Use the syntax [Text](url) to insert links, or [Icon][Text](url) to add icon.

{
  "pages": [
    "[Vercel](https://vercel.com)",
    "[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, only items in the opened root folder will be considered.

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

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 will also be hidden unless it is listed in the pages property.

Internationalization

You can add Markdown/meta files for different languages by attending .{locale} to your file name, like page.cn.md and meta.cn.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).