---
title: Front matter
description: The four front-matter keys Docsary reads, how titles and descriptions fall back, and the parser's flat key-value limitation.
order: 2
---

# Front matter

A page may open with a front-matter block: three hyphens, a run of `key: value` lines, three hyphens.

```markdown
---
title: Connecting to the device
description: Pair over Bluetooth, join a network, and reach the web interface.
order: 2
---

# Connecting to the device

...
```

Front matter is optional. A page without it works fine — the title comes from its first heading.

## Recognized keys

| Key | Type | Effect |
| --- | --- | --- |
| `title` | string | Page title. Used in the sidebar, the browser title, the table of contents rail heading, prev/next links, `llms.txt`, and search results. |
| `description` | string | Meta description, Open Graph and Twitter description, and the summary line in `llms.txt`. |
| `order` | number | Sort position within its navigation section. Lower sorts first. |
| `slug` | string | Parsed and stored, but **it does not change the URL**. The URL always comes from the file path. |

Any other key is parsed away and ignored. There is no error for an unrecognized key.

## Fallbacks

Neither `title` nor `description` is required.

**Title** resolves in this order:

1. front-matter `title`
2. the first `# ` heading in the body
3. the literal string `Untitled`

A page called `Untitled` in your sidebar means a file with no front-matter title and no `# ` heading.

**Description** resolves in this order:

1. front-matter `description`
2. the text of the first paragraph, stripped of tags and clamped to 155 characters on a word boundary with a trailing ellipsis
3. the site name plus "documentation", substituted at render time when both are empty

The automatic fallback is usually acceptable and occasionally embarrassing — if your first paragraph is "See the table below," that is your search-result snippet. Write a `description` on any page you care about.

## Ordering

`order` sets the sort key within a navigation section. Entries sort by `order` ascending, then alphabetically by title as a tie-break. The default is `0`, so a folder where nothing declares an order sorts alphabetically.

```markdown
---
title: Installation
order: 1
---
```

Ordering is per-section, not global. A section's own `order` positions the section among its siblings; the `order` of the pages inside it positions them among each other. See [Folders and navigation](/writing/navigation).

## Parser limitations

The parser is deliberately small, and it is not YAML.

- **Flat key-value only.** Nested maps, lists, and multi-line values are not parsed. `tags:` followed by indented `- one` lines is ignored, not an error.
- **One line per key.** The value is everything after the first colon on that line.
- **Quotes are stripped at the ends only.** A single leading and trailing `'` or `"` is removed. Quoting is never required — a value containing a colon is fine unquoted, because only the first colon splits the line.
- **Keys must start with a letter or underscore** and may contain word characters and hyphens.
- **The opening fence must be the first thing in the file.** A blank line or a byte-order mark before `---` means the block is treated as body content.
- **`order` is coerced with `Number()`.** A non-numeric value becomes `NaN`, which sorts unpredictably. Keep it an integer.

If a closing `---` is never found, the whole file is treated as body content and the front matter appears as text on the page. That is the usual cause of a page whose first line reads `title: Something`.