Page metadata
Use titles and descriptions to make pages easier to scan and preview.
Page metadata controls how a page is introduced in layouts, previews, and search surfaces.
Metadata block
Use this block at the top of a page to define how it appears in the layout.
---
title: Page metadata
description: Use titles and descriptions to make pages easier to scan and preview.
---Title
The title should be the shortest accurate name for the page. It becomes the visible page heading.
Description
The description should explain the outcome of reading the page. Avoid repeating the title with more words.
Strong metadata
Use the examples below to make page labels more specific and easier to scan.
| Weak | Better |
|---|---|
| Page setup | Create your first page |
| Config | Sidebar order |
| Images | Add images to blog posts |
Review question
Ask whether the title and description would still make sense in a search result or a social preview.
Metadata in lists
Metadata becomes more important when pages appear in lists, cards, command menus, or search results. It should work outside the full article context.
Sidebar labels
Short page titles are easier to scan in sidebars. If a title needs too much explanation, the page may be trying to cover too much.
Search labels
Search results need enough detail to distinguish similar pages. Use descriptions to explain the difference between related topics.
Metadata review
Review metadata after the body content is stable. Draft titles often describe the writing process instead of the final reader outcome.
Final pass
Read the title, description, and first paragraph together. They should reinforce each other without repeating the same sentence.