---
title: Sidebar order
description: Control navigation labels and page order with section metadata.
---

Each section can define its sidebar label and page order with `meta.json`.

## Basic example

This example shows the smallest useful version of the pattern.

```json
{
  "title": "Writing pages",
  "pages": ["index", "frontmatter", "mdx-basics", "images", "code-blocks", "links"]
}
```

### Section title

The `title` value becomes the label shown for the section. Keep it short enough to scan in a narrow sidebar.

### Page list

The `pages` array controls order. Use file names without `.mdx`.

## Ordering tips

Use these tips when a section starts to have more than a few pages.

- Put overview pages first.
- Group beginner pages before advanced pages.
- Keep reference pages near the end.
- Remove pages from `pages` only when they should stay hidden from navigation.

### Deep sections

When a section has many pages, group the pages by workflow rather than alphabetically. Readers rarely browse docs like a file explorer.

## Hidden pages

Sometimes a page should exist without appearing in the main sidebar. This is useful for campaign pages, migration notes, or pages linked from a specific guide.

### When to hide pages

Hide pages only when they are not part of the normal reading path. If readers need the page often, add it to the sidebar.

### How to review hidden pages

Keep a short list of hidden pages and the pages that link to them. Hidden pages are easier to forget during maintenance.

## Ordering review

Review sidebar order with a first-time reader in mind. The order should answer what to read first, what to do next, and where to look up details.

### Sequence test

Read the sidebar from top to bottom and ask whether each page prepares the reader for the next one.