Organize specification pages into groups and control sidebar navigation.
Specifications are organized into groups, and meta.yaml files control what appears in the sidebar and in what order. Understanding this structure lets you shape navigation deliberately.
How the tree is built
| File | Role |
|---|---|
specs/meta.yaml | Lists top-level groups |
<group>/meta.yaml | Group title and its page order |
<group>/index.mdx | The group’s landing page |
<group>/<page>.mdx | A leaf page (no children, no attachments) |
<group>/<page>/index.mdx | The same page once it has children or attachments |
A page is a flat .mdx file until it gains a child or an attachment; then it
becomes a directory with index.mdx. The URL does not change. See
File & Folder Structure.
Top-level groups
# specs/meta.yaml
groups:
- getting-started
- specificationsGroup meta
Each pages: entry is one URL segment. Nested folders are listed by their own
key; that folder’s meta.yaml lists its children.
# specs/base/specifications/meta.yaml
title: Specifications
pages:
- authoring
- embeds
- editing
# specs/base/specifications/authoring/meta.yaml
title: Authoring
pages:
- mdx-basics
- spec-frontmatter-and-icons
- spec-tree-and-groupsOrder comes from meta
Sidebar order follows the pages: list in meta.yaml, not the filesystem.
Add a page to pages: to make it visible and to place it. Do not write nested
keys such as authoring/mdx-basics — that is a fumadocs shortcut, not how
Studio writes meta.yaml.
Nesting
Groups can contain subfolders, each with its own meta.yaml and index.mdx.
List the subfolder by name; do not inline a path of two segments.
pages:
- overview
- embeds # subfolder with its own meta.yaml
- editing # subfolder with its own meta.yamlAdding a page
Create the MDX file
A leaf page is <group>/<page>.mdx. Adding a child to an existing leaf
promotes that page to <page>/index.mdx in the same commit (Studio does this
from Add child; in git it is a git mv).
Register it in meta
Add the page’s own key — one segment — to the parent’s pages: list.
Verify the sidebar
Confirm the page appears in the intended position.
Unlisted pages are hidden
A page that exists on disk but is not in pages: will not appear in the
sidebar. Keep meta.yaml in sync as you add pages. _attachments/ is never
a page — it holds files the document owns. A page that is a folder only
because of attachments does not get an empty meta.yaml.
Group by reader task, not by file type. A predictable tree is the single biggest factor in whether docs get used.
Last updated on