Sidebar order

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.

{
  "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.