Page Conventions

Overview

This is a shared convention for organizing your pages, followed by all file-system based content sources including Fumadocs MDX.

File

A MDX or Markdown file.

Frontmatter

You may extend your content source to add additional properties.

• title
• description

---
title: My Page
description: Best document ever
---
 
## Learn More

Folder

Organize multiple pages. If not specified, folder name will be used as the display name.

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

Use meta file to customise a folder.

Open by Default

Force to open the folder by default.

{
  "title": "Name of Folder",
  "defaultOpen": true
}

Multiple Page Trees

Adding a root property in meta can mark your folder as a root folder. The nearest root folder of current page will be used as the root of page tree.

{
  "title": "Name of Folder",
  "root": true
}

Meta

Customize the display name, order of pages, or its items on the sidebar by creating a meta.json in the folder.

When a meta file presents, items are not included unless you have explicitly add them to pages.

{
  "title": "Name of Folder",
  "pages": ["guide", "components"]
}

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

Separator

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

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

Rest

Tired to specify the order of every single page in meta.json? You can use ... to automatically add and sort remaining items.

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

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

Icons

Add custom icons for a page or a folder with the icon property.

---
title: My Page
icon: MyIcon
---

{
  "title": "My Folder",
  "icon": "MyIcon"
}

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.

Example

Assume your default language is en.