Organizing Pages

How to structure pages and control sidebar navigation.

Directory Structure

Documentation pages are organized by directories. Each directory becomes a group in the sidebar navigation.

content/docs/
├── index.mdx              → /docs
├── _meta.json
├── getting-started/
│   ├── _meta.json
│   ├── installation.mdx   → /docs/getting-started/installation
│   └── configuration.mdx  → /docs/getting-started/configuration
└── guides/
    ├── _meta.json
    └── deployment.mdx      → /docs/guides/deployment

_meta.json Files

Each directory uses a _meta.json file to control its sidebar title and page ordering.

Root _meta.json

Controls the order and titles of directory groups:

{
  "getting-started": { "title": "Getting Started", "order": 1 },
  "guides": { "title": "Guides", "order": 2 }
}

Directory _meta.json

Controls the order and titles of pages within a group:

{
  "installation": { "title": "Installation", "order": 1 },
  "configuration": { "title": "Configuration", "order": 2 }
}

If no _meta.json exists, pages are sorted by their frontmatter order field, and directory names are converted from kebab-case to Title Case.

Directories can be nested to any depth. Sub-directories become collapsible groups in the sidebar.

content/docs/
├── _meta.json
└── getting-started/
    ├── _meta.json
    ├── installation.mdx
    └── setup/                    ← nested sub-group
        ├── _meta.json
        ├── environment.mdx
        └── editor-config.mdx

Each level needs its own _meta.json. The parent directory's _meta.json defines the title and order for sub-directories, just like it does for pages:

content/docs/getting-started/_meta.json

{
  "installation": { "title": "Installation", "order": 1 },
  "setup": { "title": "Setup Guides", "order": 2 }
}

content/docs/getting-started/setup/_meta.json

{
  "environment": { "title": "Environment Setup", "order": 1 },
  "editor-config": { "title": "Editor Configuration", "order": 2 }
}

This renders as:

▼ Getting Started
    Installation
  ▼ Setup Guides
      Environment Setup
      Editor Configuration

There is no depth limit — you can nest as many levels as needed. Each level just needs a _meta.json for ordering and titles.

Adding a New Section

Create a directory

Create a new directory under content/docs/:

mkdir content/docs/guides

Add _meta.json

Create content/docs/guides/_meta.json:

{
  "deployment": { "title": "Deployment", "order": 1 }
}

Register in root _meta.json

Add the directory to content/docs/_meta.json:

{
  "getting-started": { "title": "Getting Started", "order": 1 },
  "guides": { "title": "Guides", "order": 2 }
}

Create pages

Add MDX files to the directory:

touch content/docs/guides/deployment.mdx

Edit this page on GitHub

Frontmatter Callout

On This Page

Directory Structure
_meta.json Files
Root _meta.json
Directory _meta.json
Nested Navigation
Adding a New Section
Create a directory
Add _meta.json
Register in root _meta.json
Create pages