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.