---
title: Organizing Pages
description: Organize documents with file-system based routing
---

import { File, Files, Folder } from 'fumadocs-ui/components/files';

## Overview

This is a shared convention for organizing your documents.

Fumadocs MDX, and other file-system based content sources generate slugs and page trees depending on your file structure.
Meaning that you can customise the sidebar and other navigation elements by changing the file structure.

## File

A [MDX](https://mdxjs.com) or Markdown file.

### Frontmatter

By default, it includes:

| name          | description                                        |
| ------------- | -------------------------------------------------- |
| `title`       | The title of page                                  |
| `description` | The description of page                            |
| `icon`        | The name of icon, see [Icons](#icons)              |
| `full`        | Fill all available space on the page (Fumadocs UI) |

You may extend your content source to add additional properties.

```mdx
---
title: My Page
description: Best document ever
icon: HomeIcon
full: false
---

## Learn More
```

### Slugs

The generated slugs will be same as your file path.

| path (relative to content folder) | slugs             |
| --------------------------------- | ----------------- |
| `./dir/page.mdx`                  | `['dir', 'page']` |
| `./dir/index.mdx`                 | `['dir']`         |

## 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](#meta).

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

<Files>
  <Folder name="(group-name)" defaultOpen>
    <File name="file.mdx" />
  </Folder>
</Files>

## Meta

Customize a folder by creating a `meta.json` file in the folder.

### Display Name

```json
{
  "title": "Name of Folder"
}
```

### Icon

Specify an icon name for folder with the `icon` property, see [Icons](#icons).

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

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

<Files>
  <File name="meta.json" />
  <File name="guide.mdx" />
  <File name="components.mdx" />
</Files>

### Path

The items of `pages` property can be a relative path to a page or folder. File extensions are not required.

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

### Open by Default

Force to open the folder by default.

```json title="meta.json"
{
  "title": "Name of Folder",
  "defaultOpen": true
}
```

### Separator

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

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

### Rest

Add a Rest (`...`) item to automatically add and sort remaining page items.

<Callout title="Note">
  Index pages won't be included, you must specify the order of `index`.
</Callout>

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

### Except

In conjunction with the Rest item (`...`), you can use `!name` to exclude an item from the rest.

```json
{
  "title": "Folder",
  "pages": ["...", "!hide-this-page"]
}
```

### Extract

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

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

### Link

Use the syntax `[Text](url)` to insert links.

```json
{
  "title": "Folder",
  "pages": ["index", "[Vercel](https://vercel.com)"]
}
```

You can add an icon too.

```json
{
  "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 use [the `icon` handler](/docs/headless/source-api#icons) from Source API.

## Multiple Page Trees

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

```json title="meta.json"
{
  "title": "Name of Folder",
  "root": true
}
```

When the user is browsing a page under a root folder, only the child items of the folder will be visible.

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

<Files>
  <Folder name="core" defaultOpen>
    <File name="Current Page" className="!text-fd-primary !bg-fd-primary/10" />
    <File name="Other Pages" />
  </Folder>
  <Folder name="ui" className="opacity-50" disabled defaultOpen>
    <File name="Invisible Page" />
  </Folder>
</Files>

<Callout title='Fumadocs UI'>

    When a root folder exists, Fumadocs UI will add a Tabs component to the sidebar.
    It allows user to switch between different roots.

    You can customise it via [`sidebar.tabs`](/docs/ui/layouts/docs#sidebar-tabs) in Docs Layout.

</Callout>

<HeadlessOnly>
  To allow users switching root folders, implement a navigation component that
  navigates to a page under the root folder.
</HeadlessOnly>

### Index Pages

By default, index pages are not considered as a page "under" the folder, you must specify them in the `pages` property.

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

> If it's the default language, just leave it empty like `get-started.mdx`. Do
> not add locale code to file name.

### Example

Assume your default language is `en`.

| Name              |                                           |
| ----------------- | ----------------------------------------- |
| file.mdx          | Correct                                   |
| file.cn.mdx       | Correct                                   |
| file.en.mdx       | Default locale doesn't need a locale code |
| components.cn.mdx | Pages can't be language-specific          |
