Fumadocs

Routing

A shared convention for organizing your documents

Before reading

This guide only applies for content sources that uses loader() API, such as Fumadocs MDX.

Overview

While your React framework 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 file-system based routing.

index.mdx
getting-started.mdx

File

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

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

## Learn More
namedescription
titleThe title of page
descriptionThe description of page
iconThe name of icon, see Icons

Fumadocs MDX

You can use the schema option to add frontmatter properties.

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 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.

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.

meta.json
{
  "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.

index.mdx
current-page.mdx
other-pages.mdx
my-page.mdx

Fumadocs UI

Fumadocs UI renders root folders as Sidebar Tabs, which allows user to switch between them.

Meta

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

meta.json
{
  "title": "Display Name",
  "icon": "MyIcon",
  "pages": ["index", "getting-started"],
  "defaultOpen": true
}
namedescription
titleDisplay name
iconThe name of icon, see Icons
pagesFolder items (see below)
defaultOpenOpen the folder by default

Pages

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

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

When specified, items are not included unless they are listed in pages.

  • Path: a path to page or folder, like./nested/page.
  • Separator (---Label---): a separator between two sections, use ---[Icon]Label--- to include icons.
  • Link ([Text](url)): insert links, use [Icon][Text](url) to include icons.

Special Items:

  • Rest (...): include remaining pages (sorted alphabetically).
  • Reversed Rest (z...a): reversed Rest item,
  • Extract (...folder): extract the items from a folder.
meta.json
{
  "pages": [
    "components",
    "---My Separator---",
    "...folder",
    "...",
    "[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().

i18n Routing

You can define different style for i18n routing.

lib/i18n.ts
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:

meta.json
meta.cn.json
get-started.mdx
get-started.cn.mdx

For the default locale, the locale code is optional.

All content files are grouped by language folders:

meta.json
get-started.mdx
meta.json
get-started.mdx

How is this guide?

Last updated on