SpecsModelExplore
Spec Tree and Groups
Spec Tree and Groups

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

FileRole
specs/meta.yamlLists top-level groups
<group>/meta.yamlGroup title and its page order
<group>/index.mdxThe group’s landing page
<group>/<page>.mdxA leaf page (no children, no attachments)
<group>/<page>/index.mdxThe 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
  - specifications

Group 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-groups

Order 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.yaml

Adding 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