Naming pages and categories
Page titles, slugs, sidebar labels, and the small naming decisions that affect search, share-ability, and how docs feel as a whole.
A useful page name tells readers what they will find before they open it. Choose names that work in the sidebar, search results and a shared link.
Page titles
Use specific sentence-case titles. "Connect a custom domain" tells a reader more than "Advanced configuration". For task guides, start with the action. For reference pages, name the thing being explained.
Sidebar labels
Keep labels short and recognizable. Avoid three unrelated pages all called "Overview". Use navigation metadata when a section needs a clearer title. Current sites do not use the older sidebar_label convention as their standard ordering system.
Slugs
Current page URLs follow the file and folder path. docs/publishing/custom-domains.mdx appears at /docs/publishing/custom-domains. Use lowercase words separated by hyphens.
Changing the page title can keep its URL intact. Renaming or moving the file can break inbound links. Inspect references before moving a published page and plan redirects when URLs must change.
Naming categories
Use names readers recognize: Getting started, Publishing, Billing or API reference. Put detailed explanations in the section's landing page, not in a long navigation label.
When you're stuck
Ask the agent to identify ambiguous or duplicate labels and propose improvements without changing file paths. Review the proposal before applying it.