# Frontmatter

The YAML fields at the top of a page, and what each one changes.

Every page starts with a YAML block between `---` lines. `title` is required; an unknown field fails the build, so a
typo does not go unnoticed.

```md
---
title: Retries
description: How failed jobs are retried and when they give up.
group: Concepts
order: 3
badge: New
---
```

| Field | Value | Effect |
|---|---|---|
| `title` | text, required | Page title, h1 and sidebar label. Quote it when it contains a colon. |
| `description` | text | Lead paragraph under the title, search excerpt and `llms.txt` line. |
| `layout` | `guide` (default) or `product` | `product` is a narrower article with reading time and an audience chip, for end-user guides. |
| `audience` | text | Product pages: shows a "For" chip with this text. |
| `readingTime` | minutes or `auto` | Reading time chip. Product pages compute it when the field is missing (200 words a minute). |
| `group` | text | Sidebar group label. Groups appear in the order of their first page. Without it, the page is in a group named after the section. |
| `order` | number | Position in the sidebar and in the previous and next links. Pages without it come after, sorted by title. |
| `badge` | text, or `{ text, tone }` | Badge next to the sidebar entry. A plain string uses the `warn` tone. |
| `sidebarLabel` | text | Shorter label for the sidebar. |
| `updated` | `YYYY-MM-DD` | Date in the article footer. Without it, the date of the last git commit of the file. |
| `symbols` | list of symbol ids | Symbols this page explains; links to them open this page. Needs a `symbols` block in `project.json`. |

`symbols` is described in [Symbol index](../features/symbols.md).

Badge tones are `ok`, `warn`, `err`, `info` and `neu`:

```yaml
badge: { text: Beta, tone: info }
```

## Groups across locales

The sidebar groups pages by the `group` of the page in the default locale, so a translated page and a page shown from
the fallback locale land in the same group. The label shown is the `group` of the translated page.

## Release notes

Files in `changelog/` use different fields: `version`, `date` and `title` are required, `status` is optional. See
[Release notes](./changelog.md).
