---
name: fumadocs-page-tree
description: |
  Structure a Fumadocs page tree — content folders, meta.json, slugs, sidebar. Use when adding,
  moving, or reordering doc pages under a content directory, editing a meta.json, creating
  sidebar sections (folder groups, clickable section headers), or controlling sidebar expansion.
---

# Fumadocs page tree

Page URLs and the sidebar both derive from the content directory layout plus per-folder `meta.json`. This file covers the load-bearing rules and the traps; verify anything beyond it against the local checkout `~/repo/fumadocs` — conventions in `apps/docs/content/docs/headless/page-conventions.mdx`, ground truth in `packages/core/src/source/plugins/slugs.ts` (slugs) and `packages/core/src/source/page-tree/builder.ts` (tree). In this repo `fumadocs-ui` is aliased to `@fumadocs/base-ui` (`packages/base-ui` in the checkout); the layout API is identical.

## Slugs

- `dir/page.mdx` → `/docs/dir/page`; `dir/index.mdx` → `/docs/dir`.
- A parenthesized folder `(name)/` is **slug-transparent**: stripped from slugs, so children keep parent-level URLs. Use it for sidebar-only grouping.
- Each URL may appear once in the entire tree — duplicates are an error by design.

## meta.json

Folder fields: `title`, `icon`, `description`, `defaultOpen`, `collapsible`, `root`, `pages`, `pagesIndex`.

`pages` entry syntax:

| Entry           | Meaning                                             |
| --------------- | --------------------------------------------------- |
| `"page"` / `"dir"` | path to a page or folder (relative paths allowed) |
| `"(group)"`     | folder group, referenced by its literal name        |
| `"---Label---"` | separator (icon form: `---[Icon]Label---`)          |
| `"[Text](url)"` | link; `external:[Text](url)` marks it external      |
| `"..."` / `"z...a"` | remaining items, alphabetical / reversed        |
| `"...dir"`      | inline a folder's items into this level             |
| `"!item"`       | exclude from `...`                                  |

- `pages` is **exhaustive**: once present, unlisted items are dropped unless `...` appears. Use an explicit array to pin sidebar order.
- `"root": true` makes a root folder: rendered as layout tabs, and only the active root's items are visible.

## Clickable section header (folder index)

A folder containing an `index` page attaches it as the folder's own link: the header becomes clickable and the index leaves the child list.

- Keep `pages` free of `"index"` — the index auto-resolves. Listing it demotes the folder to a plain label with the index as an ordinary child row (`builder.ts` deletes `node.index` when `pages` claims it).
- `pagesIndex` overrides which page (or `[Text](url)` link) serves as the folder's index.
- Slug-transparent group + index composes into "section header linking to a parent-level URL": `(intro)/index.mdx` gives a clickable **Intro** header → `/docs`, with siblings like `(intro)/install.mdx` → `/docs/install`.

## Sidebar expansion

- `<DocsLayout sidebar={{ defaultOpenLevel: n }}>` — a folder starts open when `defaultOpenLevel >= depth` (top-level folders are depth 1) or when it contains the active page. Default `0`: everything starts collapsed.
- Per-folder overrides in its `meta.json`: `defaultOpen: true` opens one folder; `collapsible: false` pins it open with no toggle.