Page Conventions

Overview

This is a shared convention for organizing your pages, should be followed by all built-in file-system based sources including Contentlayer and Fumadocs MDX.

File

By default, it uses MDX and supports title and description frontmatter:

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

## Learn More

You may edit the configuration file to add additional properties.

Folder

You can use folders to organize multiple pages, the uppercased name of the folder will be used as the display name.

By default, pages are sorted with String.localeCompare{:js}. The index.mdx file is always ordered at the top.

Meta

You can also customize the folder name, order of pages, or add a separator by creating a meta.json in the folder.

{
  "title": "Name of Folder",
  "pages": ["guide", "---Separator---", "components"] // file name of pages
}

Multiple Page Trees

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

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

The nearest root folder of current page will be used as the root of page tree.

Separator

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

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

Icons

It is supported to have custom icons for a page or a folder with the icon property in your frontmatter or meta file.

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

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

Internationalization

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

It is same for meta files, you have to add .{locale} to the file name like meta.cn.json.

Assume your default language is en.